ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a2fdca43fd
TenantAtlas/specs/208-heavy-suite-segmentation/quickstart.md
ahmido 0d5d1fc9f4 Spec 208: finalize heavy suite segmentation (#241) 
## Summary
- add the checked-in Spec 208 heavy-suite classification and family manifest with config-driven lane generation, attribution, and budget reporting
- update Pest grouping, guard coverage, wrapper/report contracts, and spec artifacts for the segmented lane model
- complete the targeted follow-up pass that re-homes the remaining in-scope confidence hotspots into explicit heavy-governance families

## Acceptance
- confidence is repaired and now measures 389.613832s, down from 587.446894s and below the 450s lane budget
- confidence is also slightly below the post-Spec-207 baseline of 394.383441s (delta -4.769609s)
- this closes the central Spec 208 acceptance issue that had kept the spec open

## Intentionally Re-homed Families
- finding-bulk-actions-workflow
- drift-bulk-triage-all-matching
- baseline-profile-start-surfaces
- workspace-settings-slice-management
- findings-workflow-surfaces
- workspace-only-admin-surface-independence

## Explicit Residual Risk
- heavy-governance now measures 318.296962s, above its documented 300s threshold
- the cost was not removed; it was moved into the correct lane and made visible on clearly named heavy families
- this is documented residual debt, not an open Spec 208 failure

## Validation
- focused guard/support validation: 206 passed (3607 assertions)
- lane wrapper/report validation completed for confidence and heavy-governance
- no full-suite run was performed in this pass by request

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #241
2026-04-17 09:53:55 +00:00

140 lines
11 KiB
Markdown
Raw Blame History

# Quickstart: Filament/Livewire Heavy Suite Segmentation
## Goal
Segment the current heavy Filament, Livewire, surface, discovery, and browser families so Fast Feedback stays lean, Confidence retains meaningful UI trust, Heavy Governance becomes the deliberate home for broad governance scans, and heavy cost is attributable by class and family rather than only by lane total.
## Implementation Order
1. Inventory the current heavy families already visible in `tests/Feature/Filament`, `tests/Feature/Rbac`, `tests/Feature/Baselines`, `tests/Feature/Concerns`, and `tests/Browser`.
2. Finalize the checked-in heavy class catalog: `ui-light`, `ui-workflow`, `surface-guard`, `discovery-heavy`, and `browser`.
3. Extend `TestLaneManifest` with the heavy-classification catalog, explicit heavy-family inventory, and budget targets for the first seeded heavy families.
4. Add or refine Pest groups and manifest selectors so the seeded heavy families are technically separable without broad directory churn.
5. Move the broadest Surface-Guard and Discovery-Heavy families out of Fast Feedback and Confidence into explicit `heavy-governance` ownership.
6. Add or expand guard tests so class-to-lane drift fails clearly for Browser, Discovery-Heavy, and broad Surface-Guard families.
7. Extend `TestLaneReport` so heavy-lane output attributes cost by heavy class and named family.
8. Validate Fast Feedback, Confidence, and Heavy Governance against the existing post-Spec 207 baselines and current heavy-lane thresholds.
9. Publish concise author and reviewer guidance explaining how to classify new heavy UI tests.
## Suggested Code Touches
```text
apps/platform/composer.json
apps/platform/tests/Pest.php
apps/platform/tests/Support/TestLaneManifest.php
apps/platform/tests/Support/TestLaneBudget.php
apps/platform/tests/Support/TestLaneReport.php
apps/platform/tests/Feature/Guards/*
apps/platform/tests/Feature/Filament/*
apps/platform/tests/Feature/Rbac/*
apps/platform/tests/Feature/Baselines/*
apps/platform/tests/Feature/Concerns/*
apps/platform/tests/Browser/*
scripts/platform-test-lane
scripts/platform-test-report
```
## Validation Flow
Validate the segmented end-state through the existing checked-in lane wrappers first:
```bash
./scripts/platform-test-lane fast-feedback
./scripts/platform-test-lane confidence
./scripts/platform-test-lane heavy-governance
./scripts/platform-test-lane browser
./scripts/platform-test-lane profiling
./scripts/platform-test-report fast-feedback
./scripts/platform-test-report confidence
./scripts/platform-test-report heavy-governance
./scripts/platform-test-report profiling
cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
```
Keep the implementation loop tight with the most relevant focused suites first:
```bash
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Guards
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament --filter=PolicyResourceAdminSearchParityTest
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Baselines --filter=BaselineCompareMatrixPageTest
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Rbac --filter=UiEnforcement
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser
```
## Recorded Baselines
Use the existing Spec 206/207 evidence as the starting comparison point for this rollout.
| Scope | Current reference | Budget / note |
|-------|-------------------|---------------|
| `fast-feedback` | `176.74s` post-Spec 207 comparison baseline | Must stay stable or improve while excluding Discovery-Heavy and broad Surface-Guard families |
| `confidence` | `394.38s` post-Spec 207 comparison baseline | Must stay stable or improve while retaining documented UI-Light and selected UI-Workflow coverage |
| `heavy-governance` | Existing documented heavy-lane threshold `300s`; refresh measured baseline during rollout | Needs updated family attribution after segmentation |
| `browser` | Existing isolated lane with dedicated budget | Remains separate and must not diffuse into other lanes |
## Classification Rules
- `ui-light`: localized component, page, or narrow action tests with limited mounts, limited reflection, and no broad discovery.
- `ui-workflow`: bounded multi-step or multi-surface workflows that still represent real product trust and normally belong in Confidence.
- `surface-guard`: broad action-surface, header-action, navigation-discipline, or relation-manager governance tests whose breadth makes them intentional heavy checks.
- `discovery-heavy`: tests that scan resources, pages, relation managers, global-search behavior, or reflection-heavy registries across a broad surface.
- `browser`: real end-to-end browser interaction and smoke coverage; always separate.
## Seeded Family Examples
Use the manifest catalog as the source of truth. The first checked-in families should stay aligned with these examples:
| Family | Classification | Target lane | Representative hotspots |
|-------|----------------|-------------|--------------------------|
| `backup-set-admin-tenant-parity` | `ui-light` | `confidence` | `tests/Feature/Filament/BackupSetAdminTenantParityTest.php` |
| `baseline-compare-matrix-workflow` | `ui-workflow` | `confidence` | `tests/Feature/Baselines/BaselineCompareMatrixCompareAllActionTest.php`, `tests/Feature/Baselines/BaselineCompareMatrixBuilderTest.php` |
| `onboarding-wizard-enforcement` | `ui-workflow` | `confidence` | `tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php` |
| `finding-bulk-actions-workflow` | `ui-workflow` | `heavy-governance` | `tests/Feature/Findings/FindingBulkActionsTest.php` |
| `findings-workflow-surfaces` | `ui-workflow` | `heavy-governance` | `tests/Feature/Findings/FindingWorkflowRowActionsTest.php`, `tests/Feature/Findings/FindingWorkflowViewActionsTest.php`, `tests/Feature/Findings/FindingsListFiltersTest.php`, `tests/Feature/Findings/FindingExceptionRenewalTest.php` |
| `drift-bulk-triage-all-matching` | `ui-workflow` | `heavy-governance` | `tests/Feature/Drift/DriftBulkAcknowledgeAllMatchingConfirmationTest.php` |
| `baseline-profile-start-surfaces` | `ui-workflow` | `heavy-governance` | `tests/Feature/Filament/BaselineProfileCompareStartSurfaceTest.php`, `tests/Feature/Filament/BaselineProfileCaptureStartSurfaceTest.php`, `tests/Feature/Filament/BaselineActionAuthorizationTest.php` |
| `workspace-settings-slice-management` | `ui-workflow` | `heavy-governance` | `tests/Feature/SettingsFoundation/WorkspaceSettingsManageTest.php` |
| `workspace-only-admin-surface-independence` | `surface-guard` | `heavy-governance` | `tests/Feature/Filament/WorkspaceOnlySurfaceTenantIndependenceTest.php` |
| `action-surface-contract` | `surface-guard` | `heavy-governance` | `tests/Feature/Guards/ActionSurfaceContractTest.php` |
| `backup-items-relation-manager-enforcement` | `surface-guard` | `heavy-governance` | `tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php` |
| `workspace-memberships-relation-manager-enforcement` | `surface-guard` | `heavy-governance` | `tests/Feature/Rbac/WorkspaceMembershipsRelationManagerUiEnforcementTest.php` |
| `tenant-review-header-discipline` | `surface-guard` | `heavy-governance` | `tests/Feature/Filament/TenantReviewHeaderDisciplineTest.php` |
| `panel-navigation-segregation` | `surface-guard` | `heavy-governance` | `tests/Feature/Filament/PanelNavigationSegregationTest.php` |
| `ops-ux-governance` | `surface-guard` | `heavy-governance` | `tests/Feature/Filament/Alerts/AlertsKpiHeaderTest.php`, `tests/Feature/Guards/OperationLifecycleOpsUxGuardTest.php`, `tests/Feature/ProviderConnections/CredentialLeakGuardTest.php` |
| `policy-resource-admin-search-parity` | `discovery-heavy` | `heavy-governance` | `tests/Feature/Filament/PolicyResourceAdminSearchParityTest.php` |
| `policy-version-admin-search-parity` | `discovery-heavy` | `heavy-governance` | `tests/Feature/Filament/PolicyVersionAdminSearchParityTest.php` |
| `browser-smoke` | `browser` | `browser` | `tests/Browser/Spec190BaselineCompareMatrixSmokeTest.php` |
Mixed-file fallback remains explicit for `PolicyVersionAdminSearchParityTest.php`, `BaselineCompareMatrixBuilderTest.php`, `BuildsBaselineCompareMatrixFixtures.php`, and `BuildsPortfolioTriageFixtures.php`; reviewers should treat the manifest record as authoritative until those files are further split.
## Reviewer Guidance
1. Default new localized Filament assertions to `ui-light` only when the test stays scoped to one page or action surface and does not enumerate broad registries.
2. Keep a test in `confidence` only if the manifest can justify it as `ui-light` or selected `ui-workflow` with a clear confidence rationale.
3. Move any test that scans resources, global search, relation-manager registries, or broad action inventories into `discovery-heavy` or `surface-guard` even if it still lives under `tests/Feature/Filament`.
4. Treat relation-manager enforcement, header-discipline, navigation-discipline, and action-surface governance as `heavy-governance` by default unless the scope is materially narrowed.
5. When a file mixes confidence-worthy workflow checks and heavier fixture or discovery setup, record the dominant cost driver in the manifest and let the guard output explain the fallback.
6. Keep browser smoke and end-to-end interaction isolated in the `browser` class and lane; no browser file should be justified into Fast Feedback or Confidence.
7. Review heavy attribution reports by family first, then by classification, so lane-total regressions are traced back to a named hotspot family instead of a generic heavy bucket.
## Manual Review Checklist
1. Confirm every seeded heavy family has a checked-in class, current lane, target lane, selectors, and hotspot files.
2. Confirm Fast Feedback contains no Discovery-Heavy families and no broad Surface-Guard families.
3. Confirm Confidence retains only documented `ui-light` families and explicitly selected `ui-workflow` families.
4. Confirm Browser remains isolated by suite, group, and guard tests.
5. Confirm mixed files are either split or explicitly classified by their broadest cost driver.
6. Confirm heavy-lane reporting attributes slowest cost by heavy class and family, not only by lane total.
7. Confirm new drift guards fail with actionable output that names the violating file or family.
8. Confirm author guidance makes it obvious when a new test is too heavy for Fast Feedback or Confidence.
## Exit Criteria
1. The repository has a checked-in heavy classification catalog and seeded heavy family inventory.
2. Fast Feedback and Confidence exclude the families they are no longer supposed to carry.
3. Heavy Governance owns the broad Surface-Guard and Discovery-Heavy families targeted by the rollout.
4. Browser remains a separate class and lane.
5. Drift guards prevent wrong-lane placement for Browser and seeded heavy governance families.
6. Heavy-lane reporting exposes class- and family-level attribution.
7. Fast Feedback and Confidence remain stable or improved against the recorded post-Spec 207 baselines.
Reference in New Issue View Git Blame Copy Permalink