PHPackages                             blackwell-systems/phpunit-mcp-assert - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. blackwell-systems/phpunit-mcp-assert

ActiveLibrary[Testing & Quality](/categories/testing)

blackwell-systems/phpunit-mcp-assert
====================================

PHPUnit integration for mcp-assert: run MCP server assertion YAML files as PHPUnit tests

00PHP

Since May 1Pushed 1mo agoCompare

[ Source](https://github.com/blackwell-systems/phpunit-mcp-assert)[ Packagist](https://packagist.org/packages/blackwell-systems/phpunit-mcp-assert)[ RSS](/packages/blackwell-systems-phpunit-mcp-assert/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

phpunit-mcp-assert
==================

[](#phpunit-mcp-assert)

PHPUnit integration for [mcp-assert](https://github.com/blackwell-systems/mcp-assert). Run MCP server assertion YAML files as PHPUnit tests.

Same YAML files work across PHPUnit, Bun, Jest, Vitest, pytest, Go test, and the CLI.

Install
-------

[](#install)

```
composer require --dev blackwell-systems/phpunit-mcp-assert
```

Also install the mcp-assert binary:

```
brew install blackwell-systems/tap/mcp-assert
# or: pip install mcp-assert
# or: npm install @blackwell-systems/mcp-assert
```

Usage
-----

[](#usage)

### Single assertion

[](#single-assertion)

```
use BlackwellSystems\McpAssert\McpAssertRunner;
use PHPUnit\Framework\TestCase;

class McpServerTest extends TestCase
{
    public function testEchoTool(): void
    {
        McpAssertRunner::assertYaml('evals/echo.yaml');
    }

    public function testWithOptions(): void
    {
        McpAssertRunner::assertYaml('evals/search.yaml', [
            'timeout' => '60s',
            'fixture' => 'tests/fixtures',
            'server' => 'php artisan mcp:serve',
        ]);
    }
}
```

### Suite (all YAML files in a directory)

[](#suite-all-yaml-files-in-a-directory)

```
public function testAllAssertions(): void
{
    $results = McpAssertRunner::suite('evals/');
    foreach ($results as $name => $result) {
        $this->assertTrue($result->isPassed(), "{$name}: {$result->detail}");
    }
}
```

### Data provider pattern

[](#data-provider-pattern)

```
public static function assertionProvider(): array
{
    $files = glob('evals/*.yaml') ?: [];
    $cases = [];
    foreach ($files as $file) {
        $name = pathinfo($file, PATHINFO_FILENAME);
        $cases[$name] = [$file];
    }
    return $cases;
}

#[DataProvider('assertionProvider')]
public function testAssertion(string $yamlPath): void
{
    McpAssertRunner::assertYaml($yamlPath);
}
```

How it works
------------

[](#how-it-works)

phpunit-mcp-assert shells out to the mcp-assert Go binary with `--json`, parses the result, and maps it to PHPUnit assertions. The Go binary handles all MCP protocol logic.

Binary resolution (in order):

1. Explicit `binary` option
2. `which mcp-assert` (PATH lookup)
3. Common install locations (`~/go/bin`, `/usr/local/bin`, Homebrew)

License
-------

[](#license)

MIT

###  Health Score

19

—

LowBetter than 10% of packages

Maintenance61

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/93607d2ee4e752086a29a860a1ddeada1221d05efc2ccceb1fe2e08ee8c8377a?d=identicon)[blackwell-systems](/maintainers/blackwell-systems)

---

Top Contributors

[![blackwell-systems](https://avatars.githubusercontent.com/u/236632453?v=4)](https://github.com/blackwell-systems "blackwell-systems (2 commits)")

---

Tags

assertionsmcpmodel-context-protocolphpphpunittesting

### Embed Badge

![Health badge](/badges/blackwell-systems-phpunit-mcp-assert/health.svg)

```
[![Health](https://phpackages.com/badges/blackwell-systems-phpunit-mcp-assert/health.svg)](https://phpackages.com/packages/blackwell-systems-phpunit-mcp-assert)
```

###  Alternatives

[szepeviktor/phpstan-wordpress

WordPress extensions for PHPStan

3309.4M1.2k](/packages/szepeviktor-phpstan-wordpress)[dms/phpunit-arraysubset-asserts

This package provides ArraySubset and related asserts once deprecated in PHPUnit 8

14228.7M340](/packages/dms-phpunit-arraysubset-asserts)[jasonmccreary/laravel-test-assertions

A set of helpful assertions when testing Laravel applications.

3524.1M38](/packages/jasonmccreary-laravel-test-assertions)[orchestra/workbench

Workbench Companion for Laravel Packages Development

8219.1M67](/packages/orchestra-workbench)[soyuka/contexts

Behatch contexts

282.2M21](/packages/soyuka-contexts)[roquie/laravel-dusk-select2

Select2.js support for the Laravel Dusk testing.

41356.2k5](/packages/roquie-laravel-dusk-select2)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)