Phpunit Enum Laravel Package

Getting Started

This is a PHPUnit helper for enum-aware testing. Install via Composer alongside PHPUnit:

composer require --dev tourze/phpunit-enum

There is no service provider or config to publish — it is a pure testing utility composed of traits and assertion helpers. Look first at the package's src/ for the exposed trait (typically something like EnumAssertionsTrait or a base TestCase) and the README for the exact trait name in 1.0.0, since naming conventions have not yet stabilised.

Your first concrete use case is verifying that every enum case is handled somewhere it matters — for example, a Status enum cast onto an Eloquent model:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

final class OrderStatusTest extends TestCase
{
    use EnumAssertionsTrait;

    public function test_every_case_is_covered(): void
    {
        $this->assertEnumCases(OrderStatus::cases(), OrderStatus::class);
    }
}

Start by writing a single test for your most business-critical enum and confirm the trait is autoloaded before expanding usage.

Implementation Patterns

Exhaustiveness assertions in unit tests. The strongest day-to-day value is failing fast when a new enum case is added but a match expression, state machine, or mapping table does not handle it. Pair the package's assertion with a match on the enum so adding a case breaks the test rather than silently falling through.

Data providers. Use the package's case-provider helper to drive PHPUnit data providers directly from enum cases, so each case runs as an isolated test:

/**
 * @dataProvider statusProvider
 */
public function test_status_transitions(OrderStatus $status): void
{
    // ...
}

public function statusProvider(): array
{
    return $this->enumDataProvider(OrderStatus::class);
}

This keeps coverage granular — a broken PaymentFailed transition is reported separately from Paid.

Model cast integration. In Laravel tests, assert that an Eloquent attribute is cast to the correct enum and round-trips through the database:

$order = Order::factory()->create(['status' => OrderStatus::Paid]);

$this->assertEnumEquals(OrderStatus::Paid, $order->fresh()->status);
$this->assertDatabaseHas('orders', ['status' => 'paid']);

Backed-value contracts. Where enums are serialised to JSON, APIs, or queue payloads, assert the backing values explicitly. This catches accidental renaming of a case's value, which is a silent breaking change for consumers.

Workflow tip: add the exhaustiveness test to CI alongside existing coverage. It is cheap (no DB) and runs on every push, so it becomes a guardrail rather than a periodic audit.

Gotchas and Tips

Version 1.0.0 is a first stable release. Expect API churn in the trait names, assertion method signatures, and provider return shapes before/at 1.x stabilises. Pin the version in composer.json ("tourze/phpunit-enum": "^1.0") and watch the changelog rather than relying on dev-main.

PHP and PHPUnit compatibility. The package targets native enums (PHP 8.1+). Verify your PHPUnit version matches what the package expects — assertion-helper packages frequently depend on specific PHPUnit internals (e.g. TestCase extension points) that change between majors. Check composer.json in the package for the phpunit/phpunit constraint before upgrading either side.

Traits vs. inheritance. Prefer the trait over extending a package-provided TestCase base class. Laravel's Tests\TestCase already has a class hierarchy, and PHP is single-inheritance — composing via trait avoids conflicts.

Debugging failures. Exhaustiveness failures are usually reported as a set difference between expected cases and covered ones. If the message is opaque, dump Enum::cases() and the actual list in the failing test to compare manually; do not assume the package is wrong before checking you passed the fully-qualified enum class name.

Extension points. If the built-in assertions don't match your domain (e.g. you need to assert enum descriptions or translations), wrap them in your own Tests\Support\EnumAssertions trait rather than forking — that keeps upgrades straightforward. Similarly, put any custom providers in a shared base test case so the enum-handling logic lives in one place.

Config quirks. Do not assume a config file exists. Testing-only packages of this shape typically configure via trait properties or method arguments. If you need global behaviour (e.g. a default strictness flag), set it once in your base TestCase in setUp().

Integration tip: enums combined with Laravel's in: validation rule will throw on unknown values — assert this explicitly so a backing-value typo surfaces as a validation test failure rather than a 500 in production.