Split testsuite for unit and inspector based tests (#82)

.github/workflows/pipeline.yaml

@@ -6,7 +6,7 @@ permissions:
   pull-requests: write
 
 jobs:
-  tests:
+  unit:
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -22,16 +22,36 @@ jobs:
           php-version: ${{ matrix.php }}
           coverage: "none"
 
-      - name: Composer Validation
-        run: composer validate --strict
-
       - name: Install Composer
         uses: "ramsey/composer-install@v3"
         with:
           dependency-versions: "${{ matrix.dependencies }}"
 
       - name: Tests
-        run: vendor/bin/phpunit --exclude-group inspector
+        run: vendor/bin/phpunit --testsuite=unit
+
+  inspector:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: "none"
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Install Composer
+        uses: "ramsey/composer-install@v3"
+
+      - name: Tests
+        run: vendor/bin/phpunit --testsuite=inspector
 
   qa:
     runs-on: ubuntu-latest

.gitignore

@@ -1,6 +1,7 @@
 .phpunit.cache
 .php-cs-fixer.cache
 composer.lock
+coverage
 vendor
 examples/**/dev.log
 examples/**/sessions

Makefile

@@ -15,8 +15,14 @@ phpstan:
 tests:
 	vendor/bin/phpunit
 
+unit-tests:
+	vendor/bin/phpunit --testsuite=unit
+
+inspector-tests:
+	vendor/bin/phpunit --testsuite=inspector
+
 coverage:
-	XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html=coverage
+	XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite=unit --coverage-html=coverage
 
 ci: ci-stable
 

phpstan.dist.neon

@@ -9,8 +9,8 @@ parameters:
         - tests/
     excludePaths:
         - examples/cli/vendor/* (?)
-        - tests/Capability/Discovery/Fixtures/
-        - tests/Capability/Discovery/SchemaGeneratorFixture.php
+        - tests/Unit/Capability/Discovery/Fixtures/
+        - tests/Unit/Capability/Discovery/SchemaGeneratorFixture.php
     treatPhpDocTypesAsCertain: false
     ignoreErrors:
         -

phpunit.xml.dist

@@ -9,8 +9,11 @@
          failOnWarning="true">
 
     <testsuites>
-        <testsuite name="default">
-            <directory>tests</directory>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="inspector">
+            <directory>tests/Inspector</directory>
         </testsuite>
     </testsuites>
 

tests/Inspector/InspectorSnapshotTestCase.php

@@ -0,0 +1,68 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Inspector;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Process\Process;
+
+abstract class InspectorSnapshotTestCase extends TestCase
+{
+    #[DataProvider('provideMethods')]
+    public function testResourcesListOutputMatchesSnapshot(string $method): void
+    {
+        $process = Process::fromShellCommandline(
+            \sprintf('npx @modelcontextprotocol/inspector --cli php %s --method %s', $this->getServerScript(), $method)
+        )->mustRun();
+
+        $output = $process->getOutput();
+        $snapshotFile = $this->getSnapshotFilePath($method);
+
+        if (!file_exists($snapshotFile)) {
+            file_put_contents($snapshotFile, $output.\PHP_EOL);
+            $this->markTestIncomplete("Snapshot created at $snapshotFile, please re-run tests.");
+        }
+
+        $expected = file_get_contents($snapshotFile);
+
+        $this->assertJsonStringEqualsJsonString($expected, $output);
+    }
+
+    /**
+     * List of methods to test.
+     *
+     * @return array<string, array{method: string}>
+     */
+    abstract public static function provideMethods(): array;
+
+    abstract protected function getServerScript(): string;
+
+    /**
+     * @return array<string, array{method: string}>
+     */
+    protected static function provideListMethods(): array
+    {
+        return [
+            'Prompt Listing' => ['method' => 'prompts/list'],
+            'Resource Listing' => ['method' => 'resources/list'],
+            // 'Resource Template Listing' => ['method' => 'resources/templates/list'],
+            'Tool Listing' => ['method' => 'tools/list'],
+        ];
+    }
+
+    private function getSnapshotFilePath(string $method): string
+    {
+        $className = substr(static::class, strrpos(static::class, '\\') + 1);
+
+        return __DIR__.'/snapshots/'.$className.'-'.str_replace('/', '_', $method).'.json';
+    }
+}

tests/Inspector/ManualStdioExampleTest.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Inspector;
+
+use Mcp\Tests\Inspector\InspectorSnapshotTestCase;
+
+final class ManualStdioExampleTest extends InspectorSnapshotTestCase
+{
+    public static function provideMethods(): array
+    {
+        return [
+            ...parent::provideListMethods(),
+        ];
+    }
+
+    protected function getServerScript(): string
+    {
+        return \dirname(__DIR__, 2).'/examples/03-manual-registration-stdio/server.php';
+    }
+}

tests/Inspector/StdioCalculatorExampleTest.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Inspector;
+
+final class StdioCalculatorExampleTest extends InspectorSnapshotTestCase
+{
+    public static function provideMethods(): array
+    {
+        return [
+            ...parent::provideListMethods(),
+        ];
+    }
+
+    protected function getServerScript(): string
+    {
+        return \dirname(__DIR__, 2).'/examples/01-discovery-stdio-calculator/server.php';
+    }
+}

tests/Inspector/snapshots/ManualStdioExampleTest-prompts_list.json

@@ -0,0 +1,15 @@
+{
+  "prompts": [
+    {
+      "name": "personalized_greeting",
+      "description": "A manually registered prompt template.",
+      "arguments": [
+        {
+          "name": "userName",
+          "description": "the name of the user",
+          "required": true
+        }
+      ]
+    }
+  ]
+}

tests/Inspector/snapshots/ManualStdioExampleTest-resources_list.json

@@ -0,0 +1,10 @@
+{
+  "resources": [
+    {
+      "name": "application_version",
+      "uri": "app://version",
+      "description": "A manually registered resource providing app version.",
+      "mimeType": "text/plain"
+    }
+  ]
+}

tests/Inspector/snapshots/ManualStdioExampleTest-tools_list.json

@@ -0,0 +1,20 @@
+{
+  "tools": [
+    {
+      "name": "echo_text",
+      "description": "A manually registered tool to echo input.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "the text to echo"
+          }
+        },
+        "required": [
+          "text"
+        ]
+      }
+    }
+  ]
+}

tests/Inspector/snapshots/StdioCalculatorExampleTest-prompts_list.json

@@ -0,0 +1,4 @@
+{
+  "prompts": []
+}
+

tests/Inspector/snapshots/StdioCalculatorExampleTest-resources_list.json

@@ -0,0 +1,11 @@
+{
+  "resources": [
+    {
+      "name": "calculator_config",
+      "uri": "config://calculator/settings",
+      "description": "Current settings for the calculator tool (precision, allow_negative).",
+      "mimeType": "application/json"
+    }
+  ]
+}
+

tests/Inspector/snapshots/StdioCalculatorExampleTest-tools_list.json

@@ -0,0 +1,51 @@
+{
+  "tools": [
+    {
+      "name": "calculate",
+      "description": "Performs a calculation based on the operation.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "a": {
+            "type": "number",
+            "description": "the first operand"
+          },
+          "b": {
+            "type": "number",
+            "description": "the second operand"
+          },
+          "operation": {
+            "type": "string",
+            "description": "the operation ('add', 'subtract', 'multiply', 'divide')"
+          }
+        },
+        "required": [
+          "a",
+          "b",
+          "operation"
+        ]
+      }
+    },
+    {
+      "name": "update_setting",
+      "description": "Updates a specific configuration setting.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "setting": {
+            "type": "string",
+            "description": "the setting key ('precision' or 'allow_negative')"
+          },
+          "value": {
+            "description": "the new value (int for precision, bool for allow_negative)"
+          }
+        },
+        "required": [
+          "setting",
+          "value"
+        ]
+      }
+    }
+  ]
+}
+

tests/Unit/Capability/Attribute/CompletionProviderFixture.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Prompt\Completion\ProviderInterface;
+
+class CompletionProviderFixture implements ProviderInterface
+{
+    /**
+     * @var string[]
+     */
+    public static array $completions = ['alpha', 'beta', 'gamma'];
+    public static string $lastCurrentValue = '';
+
+    public function getCompletions(string $currentValue): array
+    {
+        self::$lastCurrentValue = $currentValue;
+
+        return array_filter(self::$completions, fn ($item) => str_starts_with($item, $currentValue));
+    }
+}

tests/Unit/Capability/Attribute/CompletionProviderTest.php

@@ -0,0 +1,85 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Attribute\CompletionProvider;
+use Mcp\Tests\Unit\Fixtures\Enum\StatusEnum;
+use PHPUnit\Framework\TestCase;
+
+class CompletionProviderTest extends TestCase
+{
+    public function testCanBeConstructedWithProviderClass(): void
+    {
+        $attribute = new CompletionProvider(provider: CompletionProviderFixture::class);
+
+        $this->assertSame(CompletionProviderFixture::class, $attribute->provider);
+        $this->assertNull($attribute->values);
+        $this->assertNull($attribute->enum);
+    }
+
+    public function testCanBeConstructedWithProviderInstance(): void
+    {
+        $instance = new CompletionProviderFixture();
+        $attribute = new CompletionProvider(provider: $instance);
+
+        $this->assertSame($instance, $attribute->provider);
+        $this->assertNull($attribute->values);
+        $this->assertNull($attribute->enum);
+    }
+
+    public function testCanBeConstructedWithValuesArray(): void
+    {
+        $values = ['draft', 'published', 'archived'];
+        $attribute = new CompletionProvider(values: $values);
+
+        $this->assertNull($attribute->provider);
+        $this->assertSame($values, $attribute->values);
+        $this->assertNull($attribute->enum);
+    }
+
+    public function testCanBeConstructedWithEnumClass(): void
+    {
+        $attribute = new CompletionProvider(enum: StatusEnum::class);
+
+        $this->assertNull($attribute->provider);
+        $this->assertNull($attribute->values);
+        $this->assertSame(StatusEnum::class, $attribute->enum);
+    }
+
+    public function testThrowsExceptionWhenNoParametersProvided(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only one of provider, values, or enum can be set');
+        new CompletionProvider();
+    }
+
+    public function testThrowsExceptionWhenMultipleParametersProvided(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only one of provider, values, or enum can be set');
+        new CompletionProvider(
+            provider: CompletionProviderFixture::class,
+            values: ['test']
+        );
+    }
+
+    public function testThrowsExceptionWhenAllParametersProvided(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Only one of provider, values, or enum can be set');
+        new CompletionProvider(
+            provider: CompletionProviderFixture::class,
+            values: ['test'],
+            enum: StatusEnum::class
+        );
+    }
+}

tests/Unit/Capability/Attribute/McpPromptTest.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Attribute\McpPrompt;
+use PHPUnit\Framework\TestCase;
+
+class McpPromptTest extends TestCase
+{
+    public function testInstantiatesWithNameAndDescription(): void
+    {
+        // Arrange
+        $name = 'test-prompt-name';
+        $description = 'This is a test prompt description.';
+
+        // Act
+        $attribute = new McpPrompt(name: $name, description: $description);
+
+        // Assert
+        $this->assertSame($name, $attribute->name);
+        $this->assertSame($description, $attribute->description);
+    }
+
+    public function testInstantiatesWithNullValuesForNameAndDescription(): void
+    {
+        // Arrange & Act
+        $attribute = new McpPrompt(name: null, description: null);
+
+        // Assert
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+    }
+
+    public function testInstantiatesWithMissingOptionalArguments(): void
+    {
+        // Arrange & Act
+        $attribute = new McpPrompt(); // Use default constructor values
+
+        // Assert
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+    }
+}

tests/Unit/Capability/Attribute/McpResourceTemplateTest.php

@@ -0,0 +1,71 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Attribute\McpResourceTemplate;
+use PHPUnit\Framework\TestCase;
+
+class McpResourceTemplateTest extends TestCase
+{
+    public function testInstantiatesWithCorrectProperties(): void
+    {
+        // Arrange
+        $uriTemplate = 'file:///{path}/data';
+        $name = 'test-template-name';
+        $description = 'This is a test template description.';
+        $mimeType = 'application/json';
+
+        // Act
+        $attribute = new McpResourceTemplate(
+            uriTemplate: $uriTemplate,
+            name: $name,
+            description: $description,
+            mimeType: $mimeType,
+        );
+
+        // Assert
+        $this->assertSame($uriTemplate, $attribute->uriTemplate);
+        $this->assertSame($name, $attribute->name);
+        $this->assertSame($description, $attribute->description);
+        $this->assertSame($mimeType, $attribute->mimeType);
+    }
+
+    public function testInstantiatesWithNullValuesForNameAndDescription(): void
+    {
+        // Arrange & Act
+        $attribute = new McpResourceTemplate(
+            uriTemplate: 'test://{id}', // uriTemplate is required
+            name: null,
+            description: null,
+            mimeType: null,
+        );
+
+        // Assert
+        $this->assertSame('test://{id}', $attribute->uriTemplate);
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+        $this->assertNull($attribute->mimeType);
+    }
+
+    public function testInstantiatesWithMissingOptionalArguments(): void
+    {
+        // Arrange & Act
+        $uriTemplate = 'tmpl://{key}';
+        $attribute = new McpResourceTemplate(uriTemplate: $uriTemplate);
+
+        // Assert
+        $this->assertSame($uriTemplate, $attribute->uriTemplate);
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+        $this->assertNull($attribute->mimeType);
+    }
+}

tests/Unit/Capability/Attribute/McpResourceTest.php

@@ -0,0 +1,77 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Attribute\McpResource;
+use PHPUnit\Framework\TestCase;
+
+class McpResourceTest extends TestCase
+{
+    public function testInstantiatesWithCorrectProperties(): void
+    {
+        // Arrange
+        $uri = 'file:///test/resource';
+        $name = 'test-resource-name';
+        $description = 'This is a test resource description.';
+        $mimeType = 'text/plain';
+        $size = 1024;
+
+        // Act
+        $attribute = new McpResource(
+            uri: $uri,
+            name: $name,
+            description: $description,
+            mimeType: $mimeType,
+            size: $size,
+        );
+
+        // Assert
+        $this->assertSame($uri, $attribute->uri);
+        $this->assertSame($name, $attribute->name);
+        $this->assertSame($description, $attribute->description);
+        $this->assertSame($mimeType, $attribute->mimeType);
+        $this->assertSame($size, $attribute->size);
+    }
+
+    public function testInstantiatesWithNullValuesForNameAndDescription(): void
+    {
+        // Arrange & Act
+        $attribute = new McpResource(
+            uri: 'file:///test', // URI is required
+            name: null,
+            description: null,
+            mimeType: null,
+            size: null,
+        );
+
+        // Assert
+        $this->assertSame('file:///test', $attribute->uri);
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+        $this->assertNull($attribute->mimeType);
+        $this->assertNull($attribute->size);
+    }
+
+    public function testInstantiatesWithMissingOptionalArguments(): void
+    {
+        // Arrange & Act
+        $uri = 'file:///only-uri';
+        $attribute = new McpResource(uri: $uri);
+
+        // Assert
+        $this->assertSame($uri, $attribute->uri);
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+        $this->assertNull($attribute->mimeType);
+        $this->assertNull($attribute->size);
+    }
+}

tests/Unit/Capability/Attribute/McpToolTest.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Capability\Attribute;
+
+use Mcp\Capability\Attribute\McpTool;
+use PHPUnit\Framework\TestCase;
+
+class McpToolTest extends TestCase
+{
+    public function testInstantiatesWithCorrectProperties(): void
+    {
+        // Arrange
+        $name = 'test-tool-name';
+        $description = 'This is a test description.';
+
+        // Act
+        $attribute = new McpTool(name: $name, description: $description);
+
+        // Assert
+        $this->assertSame($name, $attribute->name);
+        $this->assertSame($description, $attribute->description);
+    }
+
+    public function testInstantiatesWithNullValuesForNameAndDescription(): void
+    {
+        // Arrange & Act
+        $attribute = new McpTool(name: null, description: null);
+
+        // Assert
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+    }
+
+    public function testInstantiatesWithMissingOptionalArguments(): void
+    {
+        // Arrange & Act
+        $attribute = new McpTool(); // Use default constructor values
+
+        // Assert
+        $this->assertNull($attribute->name);
+        $this->assertNull($attribute->description);
+    }
+}