Vendra Testing Laravel Package

Technical Evaluation

Architecture fit

• This is not a standalone third-party library. It is a read-only subtree split of the misaf/vendra monorepo, which changes the governance model entirely: issues, PRs, CI, and release tagging all live upstream. A TPM must treat misaf/vendra-testing as a published artifact, not a project with its own backlog. Any contribution or bugfix we need goes through the parent repo.
• The package's real role is broader than the description suggests. The description sells it as storefront/checkout test helpers (carts, totals, order state), but the source of truth describes shared, module-agnostic test infrastructure for the entire Vendra package graph: owning namespace Misaf\VendraTesting, reusable Pest expectations (Expectations, TranslationParity, TableSorting), provider-agnostic helpers in src/Helpers.php (tenant and user fixtures, Pennant feature state, Filament admin panel bootstrap), and architecture tests that enforce module boundaries.
• That means it is load-bearing for architectural integrity, not just convenience. The PackageManifestConsistencyTest and arch()->expect('Misaf\VendraTesting')->not->toUse('Misaf\VendraTenant') rule are the mechanism that stops domain modules from reaching into the concrete tenant provider. If this package rots, the boundary enforcement rots with it.
• Declared dependency surface is intentionally narrow: misaf/vendra-support is the one sanctioned dependency (via the TenantResolver / TenantAwareness contracts), and the skill explicitly forbids concrete provider imports. self.version alignment across the Vendra package graph is a hard compatibility axis.

Integration feasibility

• Mechanically it is a require-dev line and a composer update. Helpers are files-autoloaded, so there is no provider to register or config to publish in the common path.
• The real feasibility question is environmental, not procedural: the helpers assume optional providers. setUpFilamentAdminTestContext() needs a Filament panel; makeCurrentTestTenantWithFeatures() needs Pennant; tenant helpers need a TenantResolver binding. The package degrades correctly — tenant helpers no-op and return null when tenancy is disabled — but that graceful degradation is itself a hazard: a suite can pass with tenancy off and behave differently in a tenancy-enabled configuration.
• Because it is a dev dependency, there is no production runtime, no migration, no data path. Blast radius is CI, not customers.

Technical risk

• Information risk dominates. Three published versions carry only a compare/v1.11.0...v1.12.3 link. No changelog, no deprecations, no constraint-change notes. Minor bumps in test-support packages routinely alter assertion defaults, fixture shapes, and mock behaviour — "non-breaking" to the package API, outcome-flipping for our suite.
• Contract-by-convention. Helper signatures are declared a public contract that should be deprecated rather than broken, but that is a written convention, not an enforced one. There is no SemVer tooling guaranteeing it.
• Bus factor of one. One star, single maintainer, no visible issue history. No community to absorb abandonment.
• Split/tag skew. A subtree split tag can lag or diverge from the upstream monorepo commit. The tag alone does not prove what shipped.
• Accidental production inclusion. Small but non-zero: the package has real require entries (misaf/vendra-support), so a transitive path into a non-dev requirement is possible and must be checked with composer why.

Key questions

1. Who owns this package internally, and is the upstream misaf/vendra monorepo the tracked source with a defined release cadence — or are we consuming an artifact nobody is steering?
2. What changed across v1.11.0 → v1.12.3 in assertion defaults, fixture shapes, and composer.json constraints (PHP floor, illuminate/* range, Pest/PHPUnit major, misaf/vendra-support version)?
3. Does our host app run with tenancy enabled in CI? If not, are we silently exercising only the no-op path of every tenant helper?
4. Do we need Filament and Pennant in the test environment, and are those providers guaranteed present across all modules under test?
5. Is this package dev-only in our graph, and does composer why misaf/vendra-testing return anything outside require-dev?
6. Which of our own bespoke fixtures/expectations are duplicates of helpers here — and what is the consolidation value versus the coupling cost?
7. Does our fork-or-pin escape hatch work, given the repo is read-only and patches must flow upstream?

Integration Approach

Stack fit

• Native to Laravel + Composer + Pest/PHPUnit, and explicitly aware of Filament, Pennant, and multi-tenancy through misaf/vendra-support contracts. No infrastructure change, no new service, no deployment artifact.
• The value proposition for a TPM is test-code deduplication across modules, plus a machine-enforced module boundary. That is a maintainability win with a coupling cost, and it should be adopted as a deliberate platform decision rather than a convenience import.

Migration path

• Keep the lockfile pinned and adopt incrementally, module by module, not as a big-bang refactor.
• First move: run the upstream architecture presets (php, security, laravel) plus the not->toUse('Misaf\VendraTenant') expectation in one module. This proves the boundary rule works before anyone depends on it.
• Second move: replace bespoke tenant/user fixtures with createTestTenant() / createTestUser() in a single module, and delete the local duplicates. Measure diff size — if deletion is trivial, the helpers are not earning their place.
• Third move: adopt setUpFilamentAdminTestContext() and makeCurrentTestTenantWithFeatures() only in modules that genuinely need Filament/Pennant, since those carry the heaviest bootstrap cost.
• Hold Expectations and TranslationParity adoption until after the first CI timing comparison; custom expectations are the highest-value, lowest-risk surface and should go last only because they are the easiest to add later.

Compatibility

• Pin 1.11.x until the diff is read and an internal changelog entry is written. Do not float to ^1.12 in main first.
• Diff composer.json between tags before running anything: PHP floor, illuminate/* range, Pest/PHPUnit major, misaf/vendra-support constraint, self.version.
• Verify the self.version alignment rule holds across the whole Vendra package graph — a split tag that advances vendra-testing without matching siblings is the failure mode to catch early.
• Confirm the tenant provider remains optional and that the no-op path still exists in the target version. If a bump makes tenancy mandatory, that is a CI-environment change disguised as a patch.

Sequencing

1. Read the actual v1.11.0...v1.12.3 diff and tag annotations; author the missing changelog as an internal artifact.
2. Confirm dev-only status with composer why; capture the result in the dependency register.
3. Branch the upgrade, run the full PHP/Laravel matrix, and compare test counts, coverage delta, and wall-clock against the 1.11.x baseline.
4. Run one suite with tenancy enabled and one with it disabled; diff the results.
5. Land the arch-test boundary rule in one module as a pilot before broad helper adoption.
6. Consolidate fixtures module by module, deleting local duplicates in the same PR so the coupling is visible in review.
7. Decide pinning policy: exact pin for a low-cadence package with no changelog is defensible; open-ended caret is not.

Operational Impact

Maintenance

• Zero production on-call burden, no runtime monitoring, no upgrade windows. The recurring cost is the constraint-bump tax at each Laravel/PHP major, plus keeping self.version aligned across the package graph.
• The hidden cost is test-suite coupling. Once hundreds of tests depend on createTestTenant() or toSortByEverySortableColumn(), every helper change is a migration of our test code, invisible in planning until CI goes red.
• Because the repo is read-only, "just patch it" is not an option. Budget for upstream contribution latency, or maintain a documented fork.

Support

• Assume no SLA. One star, one maintainer, no changelog discipline visible from the artifact, no community to escalate to. The internal owner must be named before adoption, not after.
• Mitigation is cheap and should be explicit: an internal changelog we write ourselves, a documented fork/pin escape hatch, and the knowledge that exit cost is low — swapping this out only touches tests.

Scaling

• CI wall-clock is the only scaling axis. Filament panel bootstrap, Pennant state setup, and tenant creation all compound across parallel shards; setUpFilamentAdminTestContext() in particular does a lot per test if not scoped to admin suites.
• Measure suite duration before and after, and per-shard, rather than assuming neutrality. If tenancy is disabled in CI, scaling is near-zero — but so is coverage of the real code path.
• No throughput or horizontal-scaling concerns in production.

Failure modes

• Silent assertion relaxation — tests pass that should fail. Highest severity; detect via coverage delta plus a spot-check of newly-passing tests. This is the mode that damages trust in the whole suite.
• Tenancy-path divergence — the suite is green because every tenant helper returned null. Detect by running one job with tenancy enabled.
• Missing-provider hard failure — helpers fail loudly by design when required providers are absent, which is correct but produces opaque errors for engineers unfamiliar with the package. Detect via a documented prerequisites list.
• Helper contract break in a minor bump — deprecate-don't-break is convention, not enforcement.
• Subtree split drift — tag diverges from upstream monorepo; we ship code nobody reviewed upstream.
• Resolver conflict blocking a Laravel upgrade at the worst moment. Detect by bumping this package before framework upgrades, never after.
• Abandonment — constraint rots, eventually blocks a PHP major. Bounded by the low exit cost.

Ramp-up

• Roughly one to two days for a senior engineer to absorb the helper conventions, the tenant/no-op semantics, and the prerequisite providers. Then an hour per module for the team.
• No runbook, no on-call surface. The ramp-up is cultural: the team must internalize that bumping a test-support package is a code review event with a coverage check, not a routine automated update — and that this particular package is also an architecture enforcement mechanism, so a green CI without the arch test running means the boundary is unguarded.