Download the PHP package dpt/mcp-phpunit-warm without Composer

mcp-phpunit-warm

Stop paying PHPUnit's bootstrap tax on every test call. A warm-process MCP server that keeps PHPUnit bootstrapped across calls. ~6× faster per call vs cold CLI. Works with every MCP client.

v0.2.0: results captured in-memory via EventFacade subscribers — no more JUnit XML round-trip.

Credits

Why

PHPUnit is the standard testing framework for PHP. It is also slow to start.

Every phpunit invocation pays the same toll: autoloader bootstrap, XML config parsing, test suite construction, extension bootstrapping. For agents and validators that run PHPUnit after every edit or after every MCP tool call, that cold-start cost adds up fast.

mcp-phpunit-warm runs PHPUnit inside a long-lived PHP process. First call pays the boot once. Every subsequent call reuses the warm autoloader and skips re-parsing.

Install

Makes mcp-phpunit-warm available on $PATH.

Requires PHP 8.2+. Pulls PHPUnit ^10 || ^11 || ^12 as a real Composer dep.

Use it

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Restart Claude. Ask: "Run the tests for UserServiceTest".

Cline / Continue / Cursor / Zed / any MCP client

Same command + args shape. The server speaks plain MCP over stdio — no client-specific glue.

Standalone

Reads MCP JSON-RPC on stdin, writes responses on stdout.

Benchmark

Measured on a real DVSI codebase, single-test invocations:

First call into a fresh daemon pays the boot once (~1400ms). All subsequent calls reuse the warm autoloader and singletons.

Results are captured in-memory via PHPUnit\Event\Facade subscribers — no JUnit XML temp file, no per-call printer setup.

The win is cold-start amortization: autoloader bootstrap, XML config parsing, and test suite construction happen once. Subsequent calls skip all of it. Smaller win than mcp-rector-warm (~14× per edit) because PHPUnit cold is already faster than Rector cold.

Compatibility

Tools exposed

phpunit_run

Run PHPUnit tests.

Returns:

warm_boot: true ⇒ autoloader reused. false ⇒ first call (cold boot just finished).

output is a JSON string with {tests, assertions, failures: [{class, method, file, line, message}], errors: […], skipped: […], time}. Captured in-process via PHPUnit\Event\Facade subscribers — no temp file, no XML parse.

How it works

Three decisions worth knowing:

1. One daemon per project, not per call. Config + working dir pin at server startup via --config and --working-dir. The autoloader stays loaded across every call.

2. Static singleton reset between calls. PHPUnit 10/11/12 uses sealed singletons (EventFacade, Registry, OutputFacade, CodeCoverage) that are reset via Reflection before each run. This lets Application::run() be called repeatedly in the same process without hitting EventFacadeIsSealedException.

3. In-memory results via EventFacade subscribers. PHPUnit's DefaultPrinter writes to php://stdout using fwrite(), which bypasses PHP's output buffer and would corrupt the MCP stdio transport. We force --no-output to silence the printer, then register subscribers on PHPUnit\Event\Facade (PreparedSubscriber, FailedSubscriber, ErroredSubscriber, …) that collect results in memory during the run. No temp file. No XML round-trip.

FAQ

Does this replace vendor/bin/phpunit? No. Use it from MCP clients (Claude Desktop, agents). For one-off CLI runs the regular binary is simpler.

Why JSON output instead of JUnit XML? v0.1 used JUnit XML via --log-junit to a temp file. v0.2 captures results in-memory via EventFacade subscribers and serializes to JSON — no file I/O, no XML parse, smaller payload. The shape mirrors what JUnit XML had, just easier for agents to consume.

Does it support --filter? Yes — pass filter: "testMyMethod" as an argument to the tool.

--prewarm flag? Opt-in (off by default). When enabled, runs --list-tests at daemon startup to trigger the project's phpunit.xml bootstrap so the first real call is already warm. Caveat: projects with large test suites dump thousands of test names to php://stdout, which bypasses ob_start and corrupts the MCP stdio transport. Only enable if your project's --list-tests output is small.

Memory? The daemon sets memory_limit = -1. Idle daemon ≈ 30–60 MB resident depending on project bootstrap.

Does it survive PHPUnit version updates? The static reset targets known property names. If PHPUnit renames a singleton property in a future version, the reset skips it silently (caught via ReflectionException) and the run may fail with a sealed-facade error. Pin PHPUnit in your own composer.json if you need determinism.

Alpha status? The warm_boot: true guarantee is verified by the integration test suite. That said, PHPUnit internals (@internal) can change — treat this as beta until PHPUnit 11/12 compatibility is confirmed in CI.

Credits

• PHPUnit by Sebastian Bergmann and contributors — the engine doing all the real work. If you ship PHP, sponsor him.
• Model Context Protocol by Anthropic — the protocol that makes this kind of tool integration possible.
• mcp/sdk — official PHP SDK, used here for stdio transport + tool discovery.

Related

• PHPUnit docs — configuration, assertions, extensions.
• PHPUnit on Packagist — the upstream package.
• mcp-rector-warm — same warm-process pattern for Rector refactoring.
• claude-supertool — DPT's batched-ops Claude Code companion.

License

Community License — see Digital Process Tools.