phpcs-aaa

phpcs-aaa

PHP_CodeSniffer standard that enforces the Arrange-Act-Assert pattern in PHP test methods.

Heads up: if you are reading this on the babu-ch/phpcs-aaa repo, that is a read-only split mirror distributed via Packagist. Source, issues, and pull requests live in the parent monorepo: https://github.com/babu-ch/aaa-lint.

Install

composer require --dev babu-ch/phpcs-aaa

If you are not using the phpcodesniffer-composer-installer, point PHPCS at the standard manually:

vendor/bin/phpcs --config-set installed_paths vendor/babu-ch/phpcs-aaa

Usage

Add to your phpcs.xml.dist:

<?xml version="1.0"?>
<ruleset name="Project">
    <file>tests</file>
    <rule ref="AAA"/>
</ruleset>

Or run directly:

vendor/bin/phpcs --standard=AAA tests/

What it checks

Every test method (name starting with test by default, per PHPUnit convention) must contain three marker comments in order:

public function testAdds(): void
{
    // arrange
    $a = 1;
    $b = 2;

    // act
    $sum = $a + $b;

    // assert
    $this->assertSame(3, $sum);
}

Configuration

Override properties in your ruleset:

<rule ref="AAA.Tests.Pattern">
    <properties>
        <property name="caseSensitive" value="false"/>
        <property name="allowEmptySection" value="true"/>
        <property name="testFunctionPrefixes" type="array">
            <element value="test"/>
            <element value="it"/>
        </property>
        <property name="labels" type="array">
            <element key="arrange" value="arrange"/>
            <element key="act"     value="act"/>
            <element key="assert"  value="assert"/>
        </property>
    </properties>
</rule>

Note: the labels property via XML only accepts scalar values per key. For multiple synonyms (e.g. Japanese 準備 / 前準備), configure via a custom sniff subclass or a PHP-based ruleset at the moment.

Given / When / Then

<property name="labels" type="array">
    <element key="arrange" value="given"/>
    <element key="act"     value="when"/>
    <element key="assert"  value="then"/>
</property>

Auto-fix

When all three section comments are missing, vendor/bin/phpcbf (the auto-fixer that ships with PHP_CodeSniffer) inserts a // arrange / // act / // assert template at the top of the test method. You then move each comment above the code that belongs to it.

Other cases — one or two sections missing, wrong order, empty section — are reported with explicit hints in the error message but are not auto-fixed, because the correct insertion point depends on the test's intent.

Development

composer install
composer test

Tests use PHPUnit against the PHPCS Ruleset/DummyFile API directly (no fixture file dance).

License

MIT