Nova Assertions Laravel Package

Getting Started

Require the package as a dev dependency and let Laravel's package discovery register the service provider:

composer require --dev dillingham/nova-assertions

Start by reading the package README.md in vendor/dillingham/nova-assertions, then the tests/ directory — it is the most reliable reference for exact assertion signatures and expected argument order.

Add the assertion trait to a test case (base TestCase or a dedicated NovaTestCase) and point it at a Nova resource:

use Dillingham\NovaAssertions\NovaAssertions;

class UserResourceTest extends TestCase
{
    use NovaAssertions;

    public function test_user_resource_fields()
    {
        $this->assertFields(User::class, [
            'name',
            'email',
            'posts', // relationship field
        ]);
    }
}

The first practical use case is smoke-testing that a Nova resource exposes the fields, relationships, and cards you expect — without booting a browser or hitting the Nova HTTP endpoints. This catches accidental regressions when refactoring fields() / cards() on a resource, and runs comfortably in CI.

Implementation Patterns

Field assertions as a resource contract test. Treat the field list as an API contract. Add one test per resource asserting the exact field set, so renames and removals fail loudly:

public function test_post_resource_fields()
{
    $this->assertFields(Post::class, [
        'title',
        'body',
        'author',   // BelongsTo
        'comments', // HasMany
    ]);
}

Because 1.2.0 adds support for additional relationship types, relationship fields can now be asserted for more than just the originally supported relation — include BelongsTo, HasMany, BelongsToMany, and morph relations in your contract tests rather than only has-one/has-many.

Count assertions on fields now read from the first row. The 1.2.0 change means field count assertions derive their expected totals from the first row of the underlying result set rather than an aggregate. Write field-count tests against a fixture where row one is representative, and seed data deliberately so the first row is stable:

// Seed deterministically — the count is derived from the first row.
Post::factory()->count(3)->create(['user_id' => $user->id]);

$this->assertFields(User::class, ['posts']);

If a test previously assumed a full-table aggregate, re-verify it after upgrading.

Card assertions. Card assertions were broken prior to 1.2.0 and are fixed in this release. Add coverage for dashboard/resource cards:

public function test_user_resource_cards()
{
    $this->assertCards(User::class, [
        'UserMetrics',
    ]);
}

Wire into CI as a fast unit-style suite. These assertions don't need a running Nova front end, so run them in the standard phpunit job. Keep them in a tests/Nova/ directory and run them on every push to catch resource drift early.

Pair with Nova's own resource tests. Use these assertions for structural checks (fields/cards/relationships) and keep HTTP-level Nova::actingAs() request tests for authorization and endpoint behaviour. The two layers complement rather than replace each other.

Upgrade pattern for 1.2.0. Bump the constraint, run composer update dillingham/nova-assertions, then run the Nova test suite. Fix any assert imports flagged by the namespace change (see Gotchas) and re-baseline any count-based field assertions affected by the first-row change.

Gotchas and Tips

• Namespace change on assert. PR #9 fixed a namespace issue with assert. If you previously referenced the assertion helper through an incorrect/legacy namespace, update your use statements — stale imports will fatal at test bootstrap rather than fail gracefully.
• Card assertions were silently unreliable. PR #5 fixed card assertions. If you had commented-out or skipped card tests, re-enable them; assertions that "passed" on earlier versions may not have been checking what you thought.
• First-row count semantics is a behaviour change. Field counts are now derived from the first row, not an aggregate over the full result set. Tests with fixture ordering that differs from production (e.g. seeded via factories without explicit ordering) can produce surprising counts. Pin ordering in fixtures or assert the field list rather than counts where ordering is not guaranteed.
• Expanded relationship support changes expected-shape assumptions. PR #13 adds support for other relationship types. If your assertions previously errored or were skipped for unsupported relations, they may now execute — and fail — for legitimate reasons. Run the suite after upgrading before merging.
• Pin the version in composer.json. This is a dev-only package with a fast-moving assertion API; a caret constraint is fine, but commit composer.lock so CI and local runs agree on the exact assertion behaviour.
• Debugging failing assertions. Dump the actual field/card list returned by the resource's fields() / cards() request before assuming the package is wrong — most failures are a field added without updating the contract test, or a relation class resolving differently under the test's auth context.
• Extension point: subclass your base test case. Centralise the trait, a nova.php-aware setup, and any shared fixtures in an abstract NovaTestCase so per-resource tests stay tiny and the upgrade surface for this package is one file.
• Check the package's tests directory for signature drift. Argument order and available assertion methods have changed across releases; the vendored tests are the authoritative reference when the README lags.