phpunit
π―SkillInstallation
npx skills add g1joshi/agent-skills --skill phpunitRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh Β· Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/phpunitInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder β- This project
.claude/skills/phpunit/ - All projects
~/.claude/skills/phpunit/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
SKILL.md
View on GitHub βExpert PHPUnit testing assistance covering PHP assertions, data providers, and test doubles. Use when writing unit and functional tests for PHP, Laravel, Symfony, or WordPress.
PHPUnit
PHPUnit is the standard unit testing framework for the PHP ecosystem. Examples include usage in Laravel, Symfony, and WordPress.
When to Use
- PHP Standard Testing Framework: The official, universal testing framework for Laravel, Symfony, and modern PHP applications.
- Unit and Integration Testing: Testing PHP domain models, services, controllers, and database interactions.
- Data Providers for Parameterized Tests: Running tests against multi-dimensional test datasets using
@dataProvider. - Mocking & Test Doubles: Generating mock objects and verifying invocation expectations natively without external libraries.
Quick Start
<?php
use PHPUnit\Framework\TestCase;
final class StackTest extends TestCase
{
public function testPushAndPop(): void
{
$stack = [];
$this->assertEmpty($stack);
array_push($stack, 'foo');
$this->assertNotEmpty($stack);
$this->assertEquals('foo', array_pop($stack));
}
}
Core Concepts
PHPUnit Test Case Structure
Extends TestCase and leverages modern PHP 8 attributes:
<?php
use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;
use PHPUnit\Framework\Attributes\DataProvider;
final class CurrencyConverterTest extends TestCase
{
#[Test]
#[DataProvider('currencyProvider')]
public function it_converts_usd_to_eur(float $usd, float $expectedEur): void
{
$converter = new CurrencyConverter(exchangeRate: 0.92);
$this->assertEqualsWithDelta($expectedEur, $converter->toEur($usd), 0.01);
}
public static function currencyProvider(): array
{
return [
'zero value' => [0.0, 0.0],
'standard transaction' => [100.0, 92.0],
'fractional amount' => [10.50, 9.66],
];
}
}
Native Mock Objects
Stubs methods and asserts on invocation parameters:
public function testPaymentServiceSendsNotification(): void
{
$mailerMock = $this->createMock(MailerInterface::class);
$mailerMock->expects($this->once())
->method('send')
->with($this->equalTo('user@example.com'));
$service = new PaymentService($mailerMock);
$service->processPayment('user@example.com', 50);
}
Declarative phpunit.xml Configuration
Configures test suites, environment variables, and coverage enforcement:
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="vendor/autoload.php"
colors="true"
cacheDirectory=".phpunit.cache">
<testsuites>
<testsuite name="Unit">
<directory>tests/Unit</directory>
</testsuite>
</testsuites>
<source>
<include><directory>src</directory></include>
</source>
</phpunit>
Common Patterns
Data Providers for Clean Test Matrices
Problem: Writing multiple separate test methods to validate email formatting regex rules.
Solution: Use PHPUnit Data Providers:
use PHPUnit\Framework\TestCase;
class ValidatorTest extends TestCase
{
/**
* @dataProvider emailProvider
*/
public function testEmailValidation(string $email, bool $expected): void
{
$validator = new EmailValidator();
$this->assertSame($expected, $validator->isValid($email));
}
public static function emailProvider(): array
{
return [
['test@example.com', true],
['invalid-email', false],
['user@sub.domain.org', true],
['', false],
];
}
}
Best Practices
Do:
- Adopt PHP 8 Attributes: Use
#[Test]and#[DataProvider]instead of legacy docblock annotations (@test). - Use Static Data Providers: Ensure all data provider methods are declared as
public static. - Run with
--colors=always --testdox: Produce clean, human-readable test output in local terminals and CI. - Enforce Strict Types in Tests: Add
declare(strict_types=1);at the top of all test files.
Don't:
- Use
@runInSeparateProcessunless strictly necessary: Process isolation adds severe performance overhead. - Use
assertEqualson floats: UseassertEqualsWithDeltato avoid floating point precision failures. - Catch exceptions manually: Use
$this->expectException(CustomException::class)to assert on thrown errors.
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
Class 'PHPUnit\Framework\TestCase' not found | Composer autoload missing or PHPUnit not installed via Composer. | Run composer dump-autoload and execute via ./vendor/bin/phpunit. |
Failed asserting that false is true | Method assertion failed. | Add custom failure message: $this->assertTrue($val, 'Custom message'). |
Risky Test: This test did not perform any assertions | Test executed code without performing explicit $this->assert*. | Add assertion or mark with @doesNotPerformAssertions annotation. |
References
More from this repository10
A template skill providing a starter framework for creating new agent skills with structured sections for triggers, quick start examples, and capability descriptions.
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill
Skill