Novaunit Laravel Package

Product Decisions This Supports

• Where to spend quality budget on the admin surface. Nova panels concentrate the highest-blast-radius operations in the product — deletes, bulk edits, impersonation, refunds, permission changes — yet are typically the least tested code a team owns. This package makes it economically viable to put custom Nova components under PHPUnit coverage without standing up Dusk or browser infrastructure, giving product a cheap quality gate exactly where a mistake is most expensive.
• Coverage prioritization by primitive. Because assertions target Nova primitives individually (Resources, Fields, Actions, Filters, Lenses, Cards, Metrics), product can set a differentiated policy rather than an undifferentiated coverage number nobody trusts: every Action with a destructive side effect is non-negotiable; presentational Cards are best-effort. That is a policy product can actually defend in a review.
• Build vs. buy for custom Nova components. Custom Fields, Filters, Actions, and Resource Tools are code you own and must carry across Nova majors. Making them unit-testable in isolation lowers their total cost of ownership and shifts the calculus toward building the workflow-specific component instead of contorting a config-only Nova resource to avoid engineering work.
• Nova major-upgrade roadmap. A Nova upgrade is the single largest recurring risk to an admin panel. A component-level regression net turns that from an unquantified gamble into a scheduled, reversible project — you upgrade on your cadence, and you can size the blast radius before committing. Treat "upgrade Nova → upgrade NovaUnit → repair component tests → run suite" as an explicit runbook line item, not an afterthought.
• Release confidence and CI economics. Component tests run in seconds versus minutes for browser suites. That supports a concrete delivery decision: gate pull requests on the fast suite and reserve slow end-to-end runs for release candidates — a scheduling and headcount argument as much as a technical one.
• Internal and vendor Nova package strategy. If you ship an internal Nova package, this is the missing harness: assert field behavior, action responses, and card calculations without booting a host application. It also informs vendor-vs-fork calls — forking a third-party Nova package is only defensible if you can test the fork.

When to Consider This Package

Adopt when:

• You maintain non-trivial custom Nova components — reactive Fields, Actions with authorization and side effects, Filters with real query logic — and currently have zero or browser-only coverage on them.
• You are planning or mid-flight on a Nova major upgrade and need a regression net faster than Dusk can provide.
• Your team already standardizes on PHPUnit; this extends the existing paradigm rather than introducing a new runner or DSL.
• You ship an internal Nova package and want component-level tests that don't require a host application.
• You want the harness in-repo under MIT, with no per-seat or per-CI-minute commercial cost.

Look elsewhere or defer when:

• Adoption signal is thin. Nine stars, zero dependents, single maintainer. Treat this as code you are adopting, not a product you are buying: pin an exact version (no caret — it reaches into Nova internals, which sit outside Nova's BC promise), name a fork trigger in advance (e.g. two blocking issues open for 30 days, or no release within N weeks of a Nova major), and budget a fallback to hand-rolled helpers. The low opportunity score reflects precisely this risk, not the idea's merit.
• You need end-to-end confidence. This is component behavior in isolation. Authorization middleware, navigation, route protection, and full request lifecycles still need Dusk, Pest browser, or feature tests. Overclaiming here is the fastest way to lose stakeholder trust in the suite when an integration bug slips through.
• Your Nova usage is config-only. If you mostly register resources and declare fields without writing custom component classes, there is little at this layer to test and the dependency earns nothing.
• You are not on Laravel Nova. Meaningless outside Nova; for plain Livewire, use Livewire's own testing utilities.
• Internal-API coupling is unacceptable. If you cannot tolerate a suite that may break on a Nova minor release, prefer thin self-owned abstractions you can test yourself.
• Pest-first team culture. Pest runs on PHPUnit so interop may exist, but first-class Pest ergonomics aren't what this package advertises. Spike one real Pest test before standardizing, or you'll end up with two testing idioms and contributors guessing which to use.

Resolve before committing: the canonical Composer name (quotevelocity/novaunit vs. the qvelocity repository owner — a namespace mismatch is an immediate install failure or, worse, a silent fork), the supported Nova / PHP / PHPUnit matrix (read composer.json, not the README), and whether every CI runner can authenticate to the credential-gated Nova repository. Confirm Nova credentials in CI before the spike — discovering it at rollout turns a one-day task into a procurement ticket. Also treat the stated 2026-03-27 release date as unverified until confirmed against Packagist.

Sequencing recommendation: don't schedule a big-bang conversion. Start with the cheapest possible smoke test (a Resource test asserting a custom field registers) to confirm the harness boots, then immediately target the highest-blast-radius Action you already own — one with authorization and a destructive side effect — because that single test proves the entire value proposition. From there, retrofit opportunistically: when you're already touching an HTTP-driven Nova test, rewrite that one into a component test. Existing feature tests remain a valid safety net and shouldn't be deleted on faith. Keep the base test case thin (tests/Nova/TestCase.php with only app-wide setup) so that abandoning the package means rewriting one parent class, not 200 tests.

How to Pitch It (Stakeholders)

One line: a small, MIT-licensed dev dependency that lets us unit-test our Laravel Nova admin customizations in seconds instead of browser suites in minutes — putting a cheap quality gate on the code where mistakes cost the most.

For executives: our Nova admin panel is where refunds, deletions, bulk edits, and permission changes happen, and it's the part of the product with the least automated coverage. Today we validate it manually or not at all. This gives us automated checks on the exact operations that produce incidents, at a CI cost measured in seconds, so it can run on every pull request rather than once before a release. It also converts our next Nova upgrade from an open-ended risk into a scheduled project with a bounded, measurable blast radius. Cost: zero license spend, roughly a day of engineering to adopt. The honest caveat: it's a nine-star package with one maintainer, so we adopt it pinned and with a written fork plan — which is cheap, because it's dev-only and MIT.

For engineering: it extends PHPUnit rather than replacing it, so it fits how we already test. Fluent assertions for Resources, Fields, Actions, Filters, Lenses, and Cards mean no bespoke harness to maintain. Two conditions on adoption: pin the exact version (it touches Nova internals, outside Nova's BC promise, so a floating constraint means a Nova minor bump can silently rewrite our failure modes), and confirm Nova repository credentials on every CI runner first. We'll wire it into its own tests/Nova suite with a thin local base class as the migration seam, and we'll keep coverage scoped — component behavior only, with feature and browser tests still owning middleware, routing, and request lifecycles. On a Nova upgrade, expect the NovaUnit suite to need repair first; that's a planned line item, not a surprise.