Phpunit Wrappers Laravel Package

Getting Started

• Install as a dev dependency: composer require --dev way/phpunit-wrappers. It is a test-only utility, so never put it in require.
• Read the source before the README. The whole package is only a handful of classes (a Should/Assert wrapper plus, depending on version, a trait or global helper functions). Skim src/ so you know exactly which entry point you are using — $this->should(...), $this->assert(...), or the global should()/assert() helpers.
• Wire it into your base TestCase (or a shared test trait) rather than individual tests, so every test in the suite gets the expressive API. In a Laravel app that is tests/TestCase.php; in a plain PHPUnit project it is your abstract base test class.
• First use case: take a noisy assertion and collapse it. Instead of $this->assertSame('Jeffrey', $user->name); write the wrapper equivalent (should($user->name)->equal('Jeffrey') or the assert(...) variant). Do this for one or two assertions, run vendor/bin/phpunit, and confirm the failure messages still point at the right line.
• Verify behavior in a throwaway test that is supposed to fail. Wrappers can swallow or reshape assertion output, and you want to see the failure diff before you trust them across a suite.

Implementation Patterns

• Centralize in the base test class. Add the package's trait to tests/TestCase.php (and any abstract unit-test base class). One use statement gives the whole suite the wrapper API, and new tests inherit it automatically.
• Use wrappers for readability, raw PHPUnit for precision. Wrappers excel at value comparisons and boolean expectations in feature/integration tests. Keep native assertSame, assertInstanceOf, assertJsonStructure, mocks, and data-provider plumbing as-is — the wrapper does not replace them.
• Treat it as a DSL layer, not a new assertion engine. Everything ultimately calls a base PHPUnit assertion, so don't expect new capabilities (no snapshotting, no HTTP helpers, no mocking sugar). The value is purely syntactic.
• Pair with data providers. Wrapping per-iteration assertions inside a @dataProvider-driven test reads well: should($result)->equal($expected) inside the loop is clearer than a stack of assertSame calls with the same shape.
• Extract project-specific helpers. Put domain assertions (shouldBeActive(), assertHasRole()) in your base class alongside the wrappers. This keeps the readable style consistent while letting you add semantics the package doesn't ship.
• Adopt incrementally. Convert one test file at a time in a long-lived suite. Mixing native and wrapped assertions in the same file is fine and lowers migration risk.
• In Laravel projects, use it in tests/Feature and tests/Unit alike. It has no service provider or auto-discovery, so nothing to register in config/app.php — it is framework-agnostic and works in any PHPUnit setup.

Gotchas and Tips

• Low-maintenance, low-signal package. 45 stars, no known dependents. Pin the version in composer.json and treat it as an internal utility you could fork or vendor if it stalls. Do not build critical suite infrastructure on top of it without a copy.
• Not a Pest replacement. If you use Pest, its expect() API conflicts conceptually and may collide with global helper names. Don't mix Pest expectations with this package's globals in the same project without checking for name clashes.
• Magic __call wrappers hide type information. IDE autocompletion and Psalm/PHPStan will often see mixed. Add @method docblocks on your base TestCase for the wrapper methods you actually use, or static analysis will complain.
• Debugging failures: assertion messages usually come from the underlying PHPUnit assertion, so the stack trace points at the wrapper frame first. Read one frame deeper to find your test line, and if a message looks generic, temporarily swap in the raw assertSame to confirm what is being compared.
• Don't let wrappers blur type strictness. If a wrapper uses loose comparison where you expected strict, you can get green tests on subtly wrong values. For anything correctness-critical, keep assertSame / assertTrue explicitly.
• Extension point: because it is just a trait/helpers, the cleanest extension is a thin project-level wrapper trait that composes the package trait and adds your own named assertions. Avoid editing vendor/.
• No service provider, no config file, no artisan command. If you are expecting Laravel-style publishable config, there isn't any. Setup is purely composer require plus the trait import.
• Failure output formatting depends on the PHPUnit version you are running. If output looks odd after a PHPUnit major upgrade, first confirm the wrapper is still delegating correctly by running a single failing test.