Nova Dusk Suite Laravel Package

Getting Started

This is a testing helper package for teams who already run Laravel Nova (the paid admin panel) and want browser-level (Dusk) coverage of their admin UI. If you don't have a Nova license, this package is irrelevant to you.

Minimal steps:

1. composer require --dev laravel/dusk (if not already installed), run php artisan dusk:install, then add this package.
2. Publish whatever config it ships with (php artisan vendor:publish --tag=nova-dusk-suite) and skim the keys — most control test-user credentials, the Nova path, and selector overrides.
3. Have your tests/DuskTestCase.php extend the suite's base case (or use its trait). This wires in Nova-aware helpers (login-as-Nova-user, resource navigation, form fill) so you don't re-write them per project.
4. Set up .env.dusk.local (or .env.dusk) with a dedicated testing database and a Nova-authorized user.

First use case — a smoke test: log in as an admin, hit /nova, assert the dashboard renders, navigate to one resource's index, assert a known record appears. That single test catches the highest-value breakage (auth, routing, Nova bootstrapping) in ~10 lines.

Where to look first: the package's src/ for the base test case and any page-object/traits, then tests/ in the repo for real examples. With ~100 stars, treat the source as the documentation — it's small enough to read in one sitting.

Implementation Patterns

One test class per Nova resource. Keep each class focused: index, create, edit, delete, plus one test per custom action. This keeps failures obvious and lets you tag/skip slow suites.

Use the suite's fluent helpers instead of raw Dusk selectors. Typical shape:

$this->novaLogin($admin)
     ->visitResource('users')
     ->assertResourceIndexShows($user->email)
     ->createResource(['name' => 'New User', 'email' => '...'])
     ->assertResourceIndexShows('New User');

Wrap these in your own thin page objects per resource so selector churn is isolated.

Seed with factories, verify with Dusk. Business logic belongs in feature tests; reserve Dusk for the "does the admin actually work end-to-end" layer. A RefreshDatabase + factory seed, then a handful of browser assertions, is the sweet spot.

Cover Nova-specific surfaces explicitly: actions (select rows → open action modal → confirm → assert result), filters, search, lenses, and metrics. These are the parts that break silently on Nova upgrades and are exactly what this suite abstracts.

CI: run headless, one DB per worker (don't parallelize Dusk against a shared MySQL DB), upload tests/Browser/screenshots on failure. Tag E2E tests (e.g. @nova) so they run nightly rather than on every push.

Auth: create a dedicated nova-admin test user via factory with the right policies/gates. The suite's login helper assumes that user can reach Nova; without it you get 403s that masquerade as broken selectors.

Gotchas and Tips

• Nova is Vue; everything is async. Always waitFor / waitUntilMissing before asserting. Most "flaky" failures are racing the modal or table render.
• Selectors are version-coupled. Nova 3, 4, and 5 use different DOM/CSS. Pin your Nova version and re-run this suite on every Nova upgrade — that's half its value. If selectors break, override them in config/published stubs rather than forking.
• Modals and overlays. Action modals, delete confirmations, and field pickers stack; use the suite's modal-dismiss helpers and pause sparingly. Clicking through an overlay silently does nothing.
• BelongsTo / searchable selects need type-then-pick (async option loading), not select(). The suite usually exposes a helper; if not, model it on its select implementation.
• File/image fields use Dusk's attach() — but Nova uploads are async, so assert on the resulting preview or a subsequent save, not on the input.
• Don't mix RefreshDatabase with Dusk casually. Dusk runs in a separate process; use a dedicated DB (.env.dusk) and migrate:fresh in setup, or you'll get "database locked" / phantom-row failures.
• Debugging: $browser->dump(), ->screenshot(), and check tests/Browser/console for JS errors. A Vue error usually explains a missing element better than the assertion does.
• Extension points: subclassing the base test case, overriding selector config, and adding your own page-object methods for custom Nova fields/actions are the intended escape hatches. Given the package size, expect to extend rather than configure your way out of problems.
• CI flake budget: set --retry on Dusk for the network-heavy suites, but investigate retries >1% — persistent flake usually means an un-awaited async assertion, not a slow machine.