refactored to be more testable and added tests

Author: lachiebol

API.php

@@ -34,14 +34,13 @@ class API extends \Piwik\Plugin\API
      */
     public function getMatomoOpenApiSpec(): array
     {
-        $currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
-        $filePath = $currentPluginDir . OpenApiDocs::GENERATED_SPECS_PATH . 'matomo_openapi_spec_v' . OpenApiDocs::DEFAULT_SPEC_VERSION . '.json';
+        $filePath = $this->getMatomoSpecFilePath();
 
-        if (!is_file($filePath) || !is_readable($filePath)) {
+        if (!$this->isSpecFileReadable($filePath)) {
             throw new \Exception('OpenAPI spec file was not found. Generate it first via openapidocs:generate-spec-file.');
         }
 
-        $specContents = file_get_contents($filePath);
+        $specContents = $this->readSpecFile($filePath);
         if ($specContents === false) {
             throw new \Exception('OpenAPI spec file could not be read.');
         }
@@ -54,6 +53,27 @@ public function getMatomoOpenApiSpec(): array
         return $decodedSpec;
     }
 
+    protected function getMatomoSpecFilePath(): string
+    {
+        $currentPluginDir = Manager::getInstance()::getPluginDirectory('OpenApiDocs');
+
+        return $currentPluginDir . OpenApiDocs::GENERATED_SPECS_PATH . 'matomo_openapi_spec_v' . OpenApiDocs::DEFAULT_SPEC_VERSION . '.json';
+    }
+
+    protected function isSpecFileReadable(string $filePath): bool
+    {
+        return is_file($filePath) && is_readable($filePath);
+    }
+
+    /**
+     * @param string $filePath
+     * @return string|false
+     */
+    protected function readSpecFile(string $filePath)
+    {
+        return file_get_contents($filePath);
+    }
+
     /**
      * Get the generated API documentation data for the specified plugin.
      *

tests/Unit/APITest.php

@@ -0,0 +1,75 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\OpenApiDocs\tests\Unit;
+
+require_once PIWIK_INCLUDE_PATH . '/plugins/OpenApiDocs/vendor/autoload.php';
+
+use PHPUnit\Framework\TestCase;
+use Piwik\Plugins\OpenApiDocs\API;
+
+/**
+ * @group OpenApiDocs
+ * @group OpenApiDocs_Unit
+ * @group OpenApiDocs_APITest
+ */
+class APITest extends TestCase
+{
+    public function testGetMatomoOpenApiSpecReturnsDecodedJson()
+    {
+        $expectedSpec = [
+            'openapi' => '3.1.0',
+            'info' => [
+                'title' => 'Matomo Reporting API',
+                'version' => '1.0.0',
+            ],
+        ];
+
+        $api = $this->buildApiMock(true, json_encode($expectedSpec));
+
+        $result = $api->getMatomoOpenApiSpec();
+
+        $this->assertSame($expectedSpec, $result);
+    }
+
+    public function testGetMatomoOpenApiSpecThrowsExceptionWhenFileMissing()
+    {
+        $api = $this->buildApiMock(false);
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('OpenAPI spec file was not found');
+
+        $api->getMatomoOpenApiSpec();
+    }
+
+    public function testGetMatomoOpenApiSpecThrowsExceptionWhenJsonIsInvalid()
+    {
+        $api = $this->buildApiMock(true, '{invalid json}');
+
+        $this->expectException(\Exception::class);
+        $this->expectExceptionMessage('OpenAPI spec file contains invalid JSON');
+
+        $api->getMatomoOpenApiSpec();
+    }
+
+    private function buildApiMock(bool $isReadable, $fileContents = false): API
+    {
+        $api = $this->getMockBuilder(API::class)
+            ->onlyMethods(['getMatomoSpecFilePath', 'isSpecFileReadable', 'readSpecFile'])
+            ->getMock();
+
+        $api->method('getMatomoSpecFilePath')->willReturn('/tmp/matomo_openapi_spec_v1.0.0.json');
+        $api->method('isSpecFileReadable')->willReturn($isReadable);
+        $api->method('readSpecFile')->willReturn($fileContents);
+
+        return $api;
+    }
+}