Skip to content

testing.md

Latest commit

 

History

History
167 lines (113 loc) · 5.05 KB

testing.md

File metadata and controls

167 lines (113 loc) · 5.05 KB
Raw

Testing the MCP Adapter

This guide explains how to run and write tests for the MCP Adapter using wp-env.

Prerequisites

  • Node.js 22.x (NVM recommended)
  • Docker
  • Git

See CONTRIBUTING.md for full setup requirements.

Test Layout

  • tests/phpunit/Unit/*: fast unit tests for pure PHP logic and MCP handlers
  • tests/phpunit/Integration/*: WordPress-integration tests that exercise filters, permissions, routing, and transport layers
  • tests/phpunit/Fixtures/*: test doubles (dummy error/observability handlers, abilities, transport)

Running Tests

The MCP Adapter uses wp-env to provide a containerized WordPress environment with all dependencies. This eliminates the need for manual database setup or WordPress installation.

Starting the Test Environment

First, ensure the wp-env environment is running:

npm run wp-env:test start

This starts a WordPress instance at http://localhost:8889 with all required dependencies.

Running All Tests

Run the full PHPUnit test suite:

npm run test:php

This executes both unit and integration tests in the wp-env container.

Running Specific Tests

You can pass PHPUnit arguments to the test script using --:

# Run a specific test by name
npm run test:php -- --filter test_execute_with_public_mcp_filtering

# Run a specific test file
npm run test:php -- tests/phpunit/Unit/Handlers/ToolsHandlerCallTest.php

# Run tests matching a pattern
npm run test:php -- --filter "Tools.*"

Test Coverage

To generate code coverage reports, restart the environment with Xdebug coverage mode enabled:

# Enable coverage mode
npm run wp-env:test start -- --xdebug=coverage

# Run tests (coverage will be generated)
npm run test:php

Coverage reports will be generated:

  • HTML report: tests/_output/html/index.html (open in your browser)
  • Clover XML: tests/_output/php-coverage.xml (for CI/CD tools)

Observability and Error Handling

The test suite includes fixtures for verifying observability and error handling:

DummyObservabilityHandler (tests/phpunit/Fixtures/DummyObservabilityHandler.php)

  • Captures record_event() calls with event names, tags, and optional timing data
  • Stores events in $events array for test assertions
  • Used to verify that requests, successes, errors, and timings are properly tracked

DummyErrorHandler (tests/phpunit/Fixtures/DummyErrorHandler.php)

  • Captures log() calls with messages, context, and error types
  • Stores logs in $logs array for test assertions
  • Used to verify error handling and logging behavior

Tests verify that error responses adhere to JSON-RPC 2.0 format: { jsonrpc, id, error: { code, message, data? } }

Writing New Tests

  • Place unit tests under tests/phpunit/Unit/.../*Test.php
  • Place integration tests under tests/phpunit/Integration/.../*Test.php
  • Use fixtures in tests/phpunit/Fixtures or create your own test doubles
  • Follow the Arrange-Act-Assert (AAA) pattern
  • Mock external dependencies using PHPUnit mocks
  • Test files should mirror the source structure with a Test.php suffix

Example test structure:

<?php
namespace WP\MCP\Tests\Unit\Handlers;

use PHPUnit\Framework\TestCase;

class MyHandlerTest extends TestCase {
    public function test_something(): void {
        // Arrange
        $handler = new MyHandler();

        // Act
        $result = $handler->handle($request, $server);

        // Assert
        $this->assertSame($expected, $result);
    }
}

Troubleshooting

Environment Issues

If wp-env fails to start:

# Stop and clean the environment
npm run wp-env:test stop
npm run wp-env:test clean

# Restart
npm run wp-env:test start

Test Failures

  • Class not found: This typically occurs after adding new classes, pulling changes, or switching branches. Regenerate the Composer autoloader to resolve:

    npm run wp-env:test -- run cli --env-cwd=wp-content/plugins/mcp-adapter/ composer dump-autoload

    The --env-cwd flag sets the working directory inside the Docker container to ensure Composer operates on the plugin's composer.json.

  • Permission errors: Ensure Docker has the necessary permissions to mount volumes

  • Port conflicts: wp-env uses ports 8888 and 8889 by default. If these are in use, stop other services or configure different ports in .wp-env.json

Accessing the Test Environment

Continuous Integration

The repository has comprehensive CI testing via GitHub Actions (.github/workflows/test.yml):

Test Matrix:

  • PHP versions: 8.4, 8.3, 8.2, 8.1, 8.0, 7.4
  • WordPress versions: latest, trunk
  • Coverage: Enabled for PHP 8.4 + WordPress latest (uploaded to Codecov)

Automated Checks:

  • PHPUnit tests via npm run test:php
  • PHPCS coding standards
  • PHPStan static analysis (Level 8)

All tests run automatically on pull requests and pushes to trunk.