Phpunit Assertions Laravel Package

Getting Started

Install the package as a dev dependency:

composer require --dev astrotomic/phpunit-assertions

The package is framework-agnostic and is consumed as static assertion helpers inside your existing PHPUnit/Pest tests. You do not need to register a service provider — just import the assertion class you need:

use Astrotomic\PhpunitAssertions\GeographicAssertions;

For a first use case, start with the 0.15.0 addition: geographic distance assertions. They are useful anywhere you store coordinates (store locators, delivery zones, check-in features, geo search results) and want to assert that two points are the expected distance apart without hard-coding a full geo calculation in every test. The new logic lives in src/GeographicAssertions.php — read that file first to confirm the exact parameter order and units for your version.

GeographicAssertions::assertDistance(
    expected: 1000.0,          // metres
    fromLatitude: 52.5200,
    fromLongitude: 13.4050,
    toLatitude: 52.5290,
    toLongitude: 13.4100,
    delta: 50.0                // tolerance in metres
);

Implementation Patterns

Assert distances, not raw maths. Instead of recalculating Haversine inside a test (and duplicating the production bug), express the expectation declaratively:

public function test_order_is_deliverable_from_warehouse(): void
{
    $warehouse = Warehouse::factory()->create(['lat' => 52.5200, 'lng' => 13.4050]);
    $order = Order::factory()->create(['lat' => 52.5290, 'lng' => 13.4100]);

    GeographicAssertions::assertDistance(
        expected: 1000.0,
        fromLatitude: $warehouse->lat,
        fromLongitude: $warehouse->lng,
        toLatitude: $order->lat,
        toLongitude: $order->lng,
        delta: 50.0
    );
}

Use a delta for every real-world assertion. Coordinates coming from APIs, geocoders, or factories are rarely exact. A tolerance of tens of metres keeps tests stable while still catching genuine regressions (e.g. swapped latitude/longitude).

Pair with database/query assertions. Use the distance assertion to validate a specific pair of records, and use Laravel's own assertDatabaseHas/assertCount to prove that a radius query returned the right set of rows. The package asserts values; it does not replace spatial SQL.

Wrap in your own test helper. If several tests assert geo distances, add a small helper on your base TestCase so the coordinate argument order is enforced in one place:

protected function assertGeoDistance(float $expected, array $from, array $to, float $delta = 50.0): void
{
    GeographicAssertions::assertDistance(
        expected: $expected,
        fromLatitude: $from[0],
        fromLongitude: $from[1],
        toLatitude: $to[0],
        toLongitude: $to[1],
        delta: $delta
    );
}

Integrate with factories and fixtures. Add named states such as ->atCoordinates(52.52, 13.405) to your model factories so geo tests read consistently and you avoid scattering literal floats.

Gotchas and Tips

• Coordinate order is the classic failure mode. Latitude/longitude swaps often produce a plausible-looking but wrong distance. Add one deliberately obvious test case (e.g. two points on the equator) to catch this.
• Units matter. The new assertion works in metres with a $delta tolerance; do not mix kilometres into expected without converting. Confirm units against the source before upgrading existing tests.
• Floating-point tolerance is not optional. Even with mathematically identical inputs, rounding in storage (decimal columns, casts) will cause failures without a sensible delta.
• 0.x versioning. This is pre-1.0, so pin the version ("astrotomic/phpunit-assertions": "^0.15") and read the changelog on each minor bump. Static helper signatures can change between minors.
• Static calls, no container. These helpers do not resolve anything from Laravel's container, so they work identically in unit tests, feature tests, and Pest. That also means they cannot see app config — pass values explicitly.
• Not a spatial query engine. The assertion is a test-time calculator. Keep production radius filtering in your database or a geo library, and use this package only to verify the outcome.
• Debugging failures. When a distance assertion fails, the most useful extra context is usually the pair of coordinate values and the computed vs. expected distance; wrap the call or add dump() on the models when investigating.
• Extension point. The package is organised as focused assertion classes. If you need a domain-specific check (e.g. "within delivery radius"), compose the provided distance assertion in your own assertion class rather than forking the package.