TenantAtlas/specs/207-shared-test-fixture-slimming/plan.md

Implementation Plan: Shared Test Fixture Slimming

Branch: 207-shared-test-fixture-slimming | Date: 2026-04-16 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/207-shared-test-fixture-slimming/spec.md Input: Feature specification from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/207-shared-test-fixture-slimming/spec.md

Summary

Complete the next stage of suite-cost reduction on top of Spec 206 by formalizing a repository-wide fixture-profile model, keeping minimal setup as the default in shared helpers and high-usage factories, auditing hidden cascades across the test support layer, migrating the highest-usage expensive callers in the fast-feedback and confidence lanes, and validating lane impact through the existing Spec 206 reporting and budget seams instead of introducing a new fixture framework.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Pest v4, PHPUnit 12, Filament v5, Livewire v4, Laravel Sail
Storage: SQLite :memory: for the default test environment, isolated PostgreSQL coverage via the existing dedicated suite, and lane-measurement artifacts under the app-root contract path storage/logs/test-lanes
Testing: Pest feature, unit, browser, architecture, and guard coverage run through Sail-wrapped artisan test; shared-fixture regressions should be protected by focused Pest tests plus existing lane-report tooling
Target Platform: Laravel monorepo application with the implementation scoped to apps/platform test support and factories
Project Type: Monorepo with a Laravel platform app and separate Astro website; this feature affects only platform test infrastructure
Performance Goals: Lower per-test cost for the dominant shared fixture paths, keep Spec 206 fast-feedback and confidence lanes stable or improved, and achieve at least one measured standard-lane improvement of 10% or more after the migration pack with no affected standard lane regressing by more than 5%
Constraints: Sail-first commands only; no new product persistence or runtime routes; no new dependencies; migration must be incremental and backwards-compatible for legacy heavy callers; avoid a broad suite rewrite; keep helper cost visible by naming rather than by hidden booleans alone
Scale/Scope: createUserWithTenant() is referenced by roughly 607 callers, existing fixture profiles already exist in apps/platform/tests/Pest.php, hidden cascade hotspots include TenantFactory, Tenant model boot hooks, OperationRunFactory, ProviderConnectionFactory, BackupSetFactory, and multi-record builder traits under apps/platform/tests/Feature/Concerns

Filament v5 Implementation Notes

• Livewire v4.0+ compliance: Preserved. This feature changes no runtime Filament or Livewire behavior.
• Provider registration location: Unchanged. Existing panel providers remain registered in bootstrap/providers.php.
• Global search rule: No globally searchable resources are added or changed.
• Destructive actions: No runtime destructive actions are introduced. Any new tests added by this feature continue to validate existing confirmation and authorization behavior rather than creating new action surfaces.
• Asset strategy: No panel or shared asset changes. Existing filament:assets deployment behavior remains unchanged.
• Testing plan: Add Pest coverage for fixture-profile semantics, hidden-cascade regression, legacy transition behavior, migrated high-usage caller packs, and lane impact against the Spec 206 budgets.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: PASS. No inventory, snapshot, or backup truth is changed.
• Read/write separation: PASS. The feature governs repository test support behavior only and introduces no end-user write path.
• Graph contract path: PASS. No Graph calls or config/graph_contracts.php changes are introduced.
• Deterministic capabilities: PASS. No capability registry or runtime authorization behavior changes.
• RBAC-UX, workspace isolation, tenant isolation: PASS. No runtime routes, policies, or cross-plane semantics are changed.
• Run observability and Ops-UX: PASS. Lane measurements reuse Spec 206 filesystem artifacts and do not introduce OperationRun behavior.
• Data minimization: PASS. Fixture audits and lane measurements remain repository-local and contain no secrets.
• Proportionality and bloat control: PASS WITH LIMITS. The only new abstraction is a narrow fixture-profile and cascade-audit vocabulary for test support behavior; the plan explicitly rejects a generalized fixture framework.
• TEST-TRUTH-001: PASS. The feature improves test honesty by making hidden setup and heavy defaults more visible and verifiable.
• Filament/UI constitutions: PASS / NOT APPLICABLE. No operator-facing UI, asset, badge, or action-surface behavior is changed.

Phase 0 Gate Result: PASS

• The feature stays inside repository test infrastructure, factories, and documentation.
• No new runtime persistence, product routes, panels, or Graph seams are introduced.
• The chosen design narrows and documents existing behavior rather than layering a new meta-framework on top of the test support layer.

Project Structure

Documentation (this feature)

specs/207-shared-test-fixture-slimming/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── shared-fixture-profile.schema.json
│   └── shared-test-fixture-slimming.logical.openapi.yaml
└── tasks.md

Source Code (repository root)

apps/
├── platform/
│   ├── app/
│   │   └── Models/
│   │       └── Tenant.php
│   ├── database/
│   │   └── factories/
│   │       ├── BackupSetFactory.php
│   │       ├── OperationRunFactory.php
│   │       ├── ProviderConnectionFactory.php
│   │       ├── RestoreRunFactory.php
│   │       └── TenantFactory.php
│   ├── tests/
│   │   ├── Pest.php
│   │   ├── Feature/
│   │   │   ├── Concerns/
│   │   │   ├── Console/
│   │   │   ├── Guards/
│   │   │   ├── Navigation/
│   │   │   └── Spec080WorkspaceManagedTenantAdminMigrationTest.php
│   │   ├── Support/
│   │   │   ├── TestLaneManifest.php
│   │   │   ├── TestLaneBudget.php
│   │   │   └── TestLaneReport.php
│   │   └── Unit/
│   └── storage/logs/test-lanes/
├── website/
└── ...
scripts/
├── platform-sail
├── platform-test-lane
└── platform-test-report

Structure Decision: Keep the feature concentrated in apps/platform/tests/Pest.php, the dominant cascading factories under apps/platform/database/factories, the hidden test-only model hook in apps/platform/app/Models/Tenant.php, selected high-usage caller files under apps/platform/tests/Feature, and guard or support coverage that validates fixture semantics and lane impact. Planning artifacts stay in the specs/207-shared-test-fixture-slimming directory.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	Not applicable	Not applicable

Proportionality Review

• Current operator problem: Contributors and reviewers still pay hidden full-context setup cost in ordinary tests, which blunts the value of Spec 206 lane governance.
• Existing structure is insufficient because: Shared helpers, factory callbacks, and model boot hooks still create extra workspace, provider, credential, session, and related graph state without always making that cost visible.
• Narrowest correct implementation: Extend the existing helper-profile seam, audit the key cascading factories and builder traits, add lean and explicit heavy states, keep a transition path for legacy callers, and reuse the Spec 206 lane-report contract for measurement.
• Ownership cost created: The repo must maintain documented profile names, a small set of guard tests, and a cascade-audit vocabulary for touched factories and helpers.
• Alternative intentionally rejected: A brand-new generic fixture DSL or registry, because the repo already has concrete seams in tests/Pest.php and the current problem is hidden cost, not missing framework flexibility.
• Release truth: Current-release repository truth and a direct prerequisite for sharper heavy-suite segmentation in Spec 208.

Phase 0 — Research (complete)

• Output: research.md
• Resolved key decisions:
  • Reuse the existing createUserWithTenant() profile seam in apps/platform/tests/Pest.php as the foundation instead of introducing a new fixture framework.
  • Normalize the feature around the spec-facing model of minimal, standard, and full or integration-heavy, while preserving current explicit variants such as provider-enabled, credential-enabled, and ui-context as named heavy add-ons or temporary transition aliases with declared removal triggers.
  • Audit tenant workspace provisioning at both the factory layer and the Tenant model boot hook because lean tenant creation is incomplete if only one layer is slimmed.
  • Treat OperationRunFactory, ProviderConnectionFactory, ProviderCredentialFactory, and BackupSetFactory as first-class cascade-audit targets because they still create extra workspace or relationship context by default.
  • Keep multi-record concern builders such as BuildsBaselineCompareMatrixFixtures explicit and heavy by intent; expose their cost rather than forcing them into the minimal path.
  • Reuse Spec 206 lane artifacts and budgets in storage/logs/test-lanes for before and after measurement rather than creating a separate performance harness.
  • Prefer a backwards-compatible transition path with explicit legacy aliases, removal triggers, and guard coverage over a mass rewrite of all callers.
  • Protect the rollout with fixture guard tests that assert both absence of hidden heavy context on minimal paths and presence of promised context on explicit heavy paths.

Phase 1 — Design & Contracts (complete)

• Output: data-model.md formalizes fixture profiles, helper entry points, factory cascade findings, transition paths, migration packs, guard contracts, and lane-impact measurements.
• Output: contracts/shared-fixture-profile.schema.json defines the logical contract for a checked-in fixture profile catalog, helper bindings, audited factories, and migration packs.
• Output: contracts/shared-test-fixture-slimming.logical.openapi.yaml captures the logical contract for resolving helper profiles, reading cascade audits, and comparing lane impact without implying a new runtime service.
• Output: quickstart.md provides the planned implementation order, focused validation commands, and rollout checkpoints.

Post-design Constitution Re-check

• PASS: No runtime routes, panels, authorization planes, or Graph seams are introduced.
• PASS: The fixture-profile vocabulary is directly justified by current suite cost and does not become a generalized platform abstraction.
• PASS: The design favors extending concrete existing seams in tests/Pest.php and the touched factories over adding new registries or a new DSL.
• PASS WITH WORK: Legacy aliases must remain visible, temporary, and tied to explicit removal triggers so the transition layer does not become a permanent second system.
• PASS WITH WORK: Lane validation must use the existing Spec 206 budgets and reporting outputs so performance claims remain evidence-backed.

Phase 2 — Implementation Planning

tasks.md should cover:

• Inventorying the current shared helper surface, high-usage caller patterns, and hidden cascade hotspots touched by this rollout.
• Capturing the pre-migration fast-feedback and confidence baseline with the existing Spec 206 wrappers before fixture edits begin.
• Inventorying and classifying the current shared helper surface, high-usage caller patterns, and hidden cascade hotspots touched by this rollout.
• Finalizing the canonical fixture-profile vocabulary of minimal, standard, and full or integration-heavy, including how existing explicit variants map into that model and how temporary aliases retire.
• Refining createUserWithTenant() and createMinimalUserWithTenant() so the default semantics remain lean and the heavier variants announce themselves clearly.
• Auditing and slimming TenantFactory, the Tenant model test-only workspace provisioning hook, OperationRunFactory, ProviderConnectionFactory, ProviderCredentialFactory, and BackupSetFactory, plus any direct shared-helper user-side effect that proves equally costly during implementation.
• Designing explicit lean and heavy states for the touched factories instead of leaving workspace or provider graph inflation hidden in callbacks or attribute resolvers.
• Adding a visible transition path for legacy heavy callers so existing tests can migrate incrementally without obscuring cost, while keeping every temporary alias on a declared retirement path.
• Migrating the first high-usage caller packs in the fast-feedback and confidence lanes, prioritizing console, authorization, navigation, and narrow finding or baseline tests that do not need provider-heavy setup.
• Reviewing heavy-by-intent concern builders and making their cost explicit through naming or parameterization rather than forcing them into default minimal semantics.
• Adding guard coverage for fixture-profile semantics, hidden cascade regression, and stable legacy-path behavior.
• Measuring post-migration lane impact with the existing Spec 206 wrappers and report artifacts, then documenting the comparison against the recorded pre-migration baseline and current budgets.
• Publishing concise contributor guidance for choosing the cheapest valid fixture path and recognizing when heavy integration context is being requested.

Contract Implementation Note

• The fixture-profile schema is schema-first and intentionally repo-tooling-oriented. It defines what a checked-in fixture catalog must express even if the first implementation remains PHP arrays and guard tests rather than a new parser.
• The OpenAPI file is logical rather than transport-prescriptive. It documents the expected semantics of helper-profile resolution, cascade-audit inspection, and lane-impact comparison for commands, tests, or wrappers that remain in-process repository tooling.
• The plan intentionally avoids introducing a new runtime service, new database table, or new filesystem artifact family outside the existing Spec 206 lane-report directory.

Deployment Sequencing Note

• No database migration is planned.
• No asset publish step changes.
• The rollout should start with audited helper and factory seams, then move to high-usage caller migration, then stabilize guard coverage, and finally validate lane impact against the existing Spec 206 budgets.