测试 MCP Adapter

本指南解释如何使用 wp-env 运行和编写 MCP Adapter 的测试。

先决条件

• Node.js 20.x（推荐使用 NVM）
• Docker
• Git

有关完整的设置要求，请参阅 CONTRIBUTING.md。

测试布局

• tests/Unit/*：纯 PHP 逻辑和 MCP 处理程序的快速单元测试
• tests/Integration/*：WordPress 集成测试，用于测试过滤器、权限、路由和传输层
• tests/Fixtures/*：测试双（虚拟错误/可观测性处理程序、能力、传输）

运行测试

MCP Adapter 使用 wp-env 提供一个包含所有依赖项的容器化 WordPress 环境。这消除了手动数据库设置或 WordPress 安装的需要。

启动测试环境

首先，确保 wp-env 环境正在运行：

npm run wp-env start

这会在 http://localhost:8888 上启动一个 WordPress 实例，包含所有必需的依赖项。

运行所有测试

运行完整的 PHPUnit 测试套件：

npm run test:php

这会在 wp-env 容器中执行单元测试和集成测试。

运行特定测试

您可以使用 -- 向测试脚本传递 PHPUnit 参数：

# 按名称运行特定测试
npm run test:php -- --filter test_execute_with_public_mcp_filtering

# 运行特定测试文件
npm run test:php -- tests/Unit/Handlers/ToolsHandlerCallTest.php

# 运行匹配模式的测试
npm run test:php -- --filter "Tools.*"

测试覆盖

要生成代码覆盖报告，请使用 Xdebug 覆盖模式重启环境：

# 启用覆盖模式
npm run wp-env start -- --xdebug=coverage

# 运行测试（将生成覆盖报告）
npm run test:php

将生成覆盖报告：

• HTML 报告：tests/_output/html/index.html（在浏览器中打开）
• Clover XML：tests/_output/php-coverage.xml（用于 CI/CD 工具）

可观测性和错误处理

测试套件包含用于验证可观测性和错误处理的 fixtures：

DummyObservabilityHandler（tests/Fixtures/DummyObservabilityHandler.php）

• 捕获带有事件名称、标签和可选计时数据的 record_event() 调用
• 将事件存储在 $events 数组中，用于测试断言
• 用于验证请求、成功、错误和计时是否被正确跟踪

DummyErrorHandler（tests/Fixtures/DummyErrorHandler.php）

• 捕获带有消息、上下文和错误类型的 log() 调用
• 将日志存储在 $logs 数组中，用于测试断言
• 用于验证错误处理和日志记录行为

测试验证错误响应是否符合 JSON-RPC 2.0 格式：{ jsonrpc, id, error: { code, message, data? } }

编写新测试

• 将单元测试放在 tests/Unit/.../*Test.php 下
• 将集成测试放在 tests/Integration/.../*Test.php 下
• 使用 tests/Fixtures 中的 fixtures 或创建自己的测试双
• 遵循 Arrange-Act-Assert（AAA）模式
• 使用 PHPUnit 模拟外部依赖
• 测试文件应镜像源代码结构，并带有 Test.php 后缀

示例测试结构：

<?php
namespace WPMCPTestsUnitHandlers;

use PHPUnitFrameworkTestCase;

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

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

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

故障排除

环境问题

如果 wp-env 无法启动：

# 停止并清理环境
npm run wp-env stop
npm run wp-env clean

# 重启
npm run wp-env start

测试失败

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

• 类未找到：这种情况通常发生在添加新类、拉取更改或切换分支之后。重新生成 Composer 自动加载器来解决：

--env-cwd 标志设置 Docker 容器内的工作目录，确保 Composer 在插件的 composer.json 上运行。

• 权限错误：确保 Docker 具有挂载卷的必要权限
• 端口冲突：wp-env 默认使用端口 8888 和 8889。如果这些端口正在使用中，停止其他服务或在 .wp-env.json 中配置不同的端口

访问测试环境

• WordPress 网站：http://localhost:8888
• 管理仪表板：http://localhost:8888/wp-admin/（admin/password）
• 运行 WP-CLI 命令：npm run wp-env run tests-cli YOUR_COMMAND

持续集成

仓库通过 GitHub Actions（.github/workflows/test.yml）进行全面的 CI 测试：

测试矩阵：

• PHP 版本：8.4、8.3、8.2、8.1、8.0、7.4
• WordPress 版本：latest、trunk
• 覆盖：为 PHP 8.4 + WordPress 最新版本启用（上传到 Codecov）

自动化检查：

• 通过 npm run test:php 进行 PHPUnit 测试
• PHPCS 编码标准
• PHPStan 静态分析（Level 8）

所有测试在拉取请求和推送到 trunk 时自动运行。