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)

```text
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)

```text
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](./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](./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](./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](./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](./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.