ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
4bc41ebaab
TenantAtlas/specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/plan.md
Ahmed Darrazi 4bc41ebaab test: add spec 376 browser fixture coverage
2026-06-13 13:12:01 +02:00

15 KiB
Raw Blame History

Implementation Plan: Browser Audit Fixture Coverage for Evidence/System Surfaces v1

Branch: 376-browser-audit-fixture-coverage-evidence-system-surfaces | Date: 2026-06-13 | Spec: specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md Input: Feature specification from specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md

Summary

Create a bounded local/testing browser fixture coverage package for five surfaces that were blocked, unstable, or spread across follow-up evidence after Spec 368: Evidence Snapshot View, Required Permissions, System Dashboard, System Operations, and Provider Connection Detail. Reuse existing admin smoke-login, direct Browser actingAs()/workspace-session harnesses, Spec 353/372 browser evidence, browser fixture seeding, scoped URL helpers, system panel auth patterns, and Pest Browser support. Do not redesign product UI or weaken production auth.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0 Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Laravel Sail Storage: PostgreSQL locally via Sail; no new schema planned Testing: Pest 4 Feature tests and Pest Browser smoke Validation Lanes: fast-feedback/confidence for Feature tests, browser lane for screenshots Target Platform: Laravel monolith under apps/platform Project Type: Web app / Filament admin and system panels Performance Goals: Fixture setup remains deterministic and bounded; browser smoke covers only five target surfaces Constraints: No production-accessible fixture auth; no real customer data; no Graph calls during page render; no product UI refactor Scale/Scope: Five surfaces, one spec-local evidence package, minimal local/testing fixture glue only if existing patterns are insufficient

UI / Surface Guardrail Plan

  • Guardrail scope: browser fixture/auditability for existing pages plus possible local/testing-only route.
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces:
    • Evidence Snapshot View
    • Required Permissions
    • /system
    • /system/ops/runs
    • Provider Connection Detail
    • possible local/testing system smoke fixture route
  • No-impact class, if applicable: no production product UI material change.
  • Native vs custom classification summary: Existing pages remain native Filament/resource/page surfaces. Fixture route is tooling/test-only.
  • Shared-family relevance: evidence viewer, provider readiness, system platform auth, browser smoke.
  • State layers in scope: route, session/auth guard, workspace context, environment context, fixture data.
  • Audience modes in scope: operator-MSP/support-platform; no customer content changes.
  • Decision/diagnostic/raw hierarchy plan: document what the pages show; do not alter it.
  • Raw/support gating plan: unchanged; document any issue as follow-up.
  • One-primary-action / duplicate-truth control: N/A for implementation unless fixture code accidentally adds UI, which is forbidden.
  • Handling modes by drift class or surface: blocked reachability becomes document-in-feature; UI defects become follow-up candidates.
  • Repository-signal treatment: Specs 368 and 375 provide source signals; route/auth/test files provide repo truth.
  • Coverage registry plan: No docs/ui-ux-enterprise-audit update is required unless implementation materially changes a production surface. Spec-local reports and screenshots are required.
  • Required tests or manual smoke: targeted Feature tests for fixture auth safety and scoped route behavior; Pest Browser smoke for five surfaces where reachable.

Architecture / Surface Approach

Phase 1 - Source audit and route truth

Inspect and document:

  • Spec 368 blocked pages and screenshots.
  • Spec 353 Required Permissions / Provider Connection browser evidence and Spec 372 Evidence Snapshot browser evidence.
  • Spec 370-375 relevant artifacts and whether they are available.
  • Current Laravel route list for admin evidence, required permissions, system dashboard, system operations, provider connection detail, and existing smoke-login routes.
  • Existing admin smoke-login implementation in apps/platform/routes/web.php.
  • Existing review-output browser fixture command and tests.
  • Existing system panel auth model: SystemPanelProvider, PlatformUser, PlatformCapabilities, UseSystemSessionCookie, EnsurePlatformCapability, and related tests.
  • Existing resource/page route helpers:
    • EvidenceSnapshotResource
    • EnvironmentRequiredPermissions
    • RequiredPermissionsLinks
    • ProviderConnectionResource

Output: artifacts/source-audit-summary.md, artifacts/route-reachability-report.md.

Phase 2 - Fixture design

For each surface, decide one of:

  • repo-verified
  • browser-verified
  • fixture-backed
  • local-only
  • test-only
  • auth-blocked
  • scope-blocked
  • data-blocked
  • route-blocked
  • timeout-blocked
  • deferred
  • not available

Admin-plane surfaces should first reuse:

  • /admin/local/smoke-login
  • direct Browser actingAs() with explicit workspace/environment session context
  • Spec 353 and Spec 372 browser fixture/test patterns where they already prove current repo truth
  • SeedReviewOutputBrowserFixture
  • existing factories and test helpers
  • existing scoped URL helpers

System-plane surfaces should first reuse:

  • PlatformUser::factory()
  • PlatformCapabilities::ACCESS_SYSTEM_PANEL
  • existing system-panel Browser actingAs($platformUser, 'platform') pattern
  • existing system panel auth tests
  • Pest Browser actingAs($platformUser, 'platform') style if sufficient

Only add a system local/testing smoke-login route if the source audit proves existing Pest Browser platform-guard authentication cannot produce the required evidence and the route can be protected by environment checks, platform guard separation, and redirect allowlist validation.

Output: artifacts/fixture-design.md, artifacts/fixture-coverage-matrix.md.

Phase 3 - Safe implementation

Allowed implementation areas only if necessary:

  • apps/platform/routes/web.php for a local/testing-only system smoke fixture route only after existing Browser actingAs(..., 'platform') patterns prove insufficient.
  • apps/platform/config/... only for fixture config if an existing fixture config pattern is reused.
  • apps/platform/app/Console/Commands/... only if extending an existing local/testing fixture seed command is narrower than adding a new helper.
  • apps/platform/tests/Feature/Auth/... for fixture route safety.
  • apps/platform/tests/Feature/... for scoped fixture behavior.
  • apps/platform/tests/Browser/... for Spec 376 smoke coverage.

Forbidden implementation areas unless a later explicit spec changes scope:

  • migrations, models, policies, product services, jobs, Filament resources/pages, Livewire components, views, Graph contracts, OperationRun services, UI action logic, production auth behavior.

Phase 4 - Browser verification

Use Pest Browser per Pest 4 docs and existing repo browser tests:

  • visit() to open each resolved fixture URL.
  • assertNoJavaScriptErrors() and assertNoConsoleLogs() where page reaches the intended surface.
  • Capture screenshots for reachable pages.
  • If blocked, capture a blocked screenshot when the browser reaches a login/error page and document final URL/status.

Required screenshot names:

  • artifacts/screenshots/001-evidence-snapshot-view.png or 001-evidence-snapshot-view-blocked.png
  • artifacts/screenshots/002-required-permissions.png or 002-required-permissions-blocked.png
  • artifacts/screenshots/003-system-dashboard.png or 003-system-dashboard-blocked.png
  • artifacts/screenshots/004-system-operations.png or 004-system-operations-blocked.png
  • artifacts/screenshots/005-provider-connection-detail.png or 005-provider-connection-detail-blocked.png

Output: artifacts/browser-verification-report.md, artifacts/screenshot-index.md.

Phase 5 - Validation and close-out

Record:

  • Branch, HEAD, dirty status before/after implementation.
  • Changed files and production impact.
  • Commands run, test lane, browser result, screenshots.
  • Known limitations and follow-up candidates.

Output: artifacts/affected-files.md, artifacts/validation-report.md, artifacts/follow-up-recommendations.md.

Existing Repository Surfaces Likely Affected

  • apps/platform/routes/web.php
  • apps/platform/app/Console/Commands/SeedReviewOutputBrowserFixture.php
  • apps/platform/app/Filament/Resources/EvidenceSnapshotResource.php (read-only context unless fixture bug proves otherwise)
  • apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php (read-only context)
  • apps/platform/app/Support/Links/RequiredPermissionsLinks.php (read-only context)
  • apps/platform/app/Filament/Resources/ProviderConnectionResource.php (read-only context)
  • apps/platform/app/Providers/Filament/SystemPanelProvider.php (read-only context)
  • apps/platform/app/Filament/System/Pages/Ops/Runs.php (read-only context)
  • apps/platform/app/Models/PlatformUser.php (read-only context)
  • apps/platform/tests/Feature/Auth/AdminLocalSmokeLoginTest.php
  • apps/platform/tests/Feature/Auth/SystemPanelAuthTest.php
  • apps/platform/tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php
  • apps/platform/tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
  • apps/platform/tests/Feature/RequiredPermissions/*
  • apps/platform/tests/Feature/ProviderConnections/*
  • apps/platform/tests/Browser/*

Domain / Model Implications

  • No new domain model is planned.
  • Evidence snapshots, provider connections, managed environments, workspaces, users, and platform users are existing repo truth.
  • Fixture creation must use existing factories/services and remain deterministic.
  • No existing source-of-truth semantics are changed.

UI / Filament Implications

  • Livewire v4.0+ compliance is required and already satisfied by the project stack.
  • Filament v5 code must remain v5-only.
  • Panel provider registration remains in apps/platform/bootstrap/providers.php; no new panel provider is planned.
  • EvidenceSnapshotResource global search is disabled and remains disabled.
  • ProviderConnectionResource is treated as sensitive/provider-scoped and should not have global search enabled by this spec.
  • Required Permissions and System pages are Filament pages, not globally searchable resources.
  • No destructive product action is added or changed. Existing dangerous actions remain governed by current confirmation/authorization/audit rules.
  • No Filament assets are added. filament:assets is not newly required by this spec unless later implementation registers assets, which is out of scope.

Livewire Implications

  • Browser tests may exercise Livewire-rendered Filament pages.
  • No Livewire component behavior should be changed.
  • If a fixture route is added, it must prepare session/auth state before the Livewire page renders.

OperationRun / Monitoring Implications

  • The spec does not create, update, or transition OperationRun.
  • System Operations may display existing OperationRun data or an empty state only.
  • No OperationRun notification, lifecycle, summary count, queue, or start UX behavior changes are allowed.

RBAC / Policy Implications

  • Admin surfaces must keep workspace/environment membership and capability checks.
  • Non-members remain deny-as-not-found.
  • Members missing capability remain forbidden where existing policy semantics require 403.
  • System panel uses platform guard and PlatformUser capabilities.
  • Any fixture route must have tests proving it is unavailable outside local and testing.
  • Any fixture route must validate redirects and reject arbitrary external destinations.

Audit / Logging / Evidence Implications

  • Fixture routes must not log secrets, tokens, raw credential payloads, or raw Graph payloads.
  • System panel normal login auditing remains existing behavior; a local/testing fixture route or Artisan fixture command must document whether it writes audit logs or why it intentionally does not.
  • Browser reports and screenshots are spec-local audit evidence, not product evidence.

Data / Migration Implications

  • No migrations.
  • No production data.
  • No backfills.
  • Fixture data may be created through factories, seed commands, or existing local/testing fixture commands.

Test Strategy

  • Feature tests:
    • admin smoke-login still sets workspace/environment context and debugbar suppression.
    • any new system smoke fixture authenticates only platform users, requires capabilities, validates redirects, and returns 404 outside local/testing.
    • any new or extended Artisan fixture command fails closed outside local/testing.
    • Evidence/Required Permissions/Provider fixture resolvers select only scoped records.
    • Provider Connection Detail fixture URLs carry explicit environment_id or record-derived managed-environment authority and do not rely on stale remembered environment state.
  • Browser tests:
    • one bounded Spec 376 browser smoke covering the five target surfaces.
    • use assertNoJavaScriptErrors() and assertNoConsoleLogs() for reachable pages.
    • create screenshots or blocked evidence.
  • Validation:
    • git diff --check
    • Pint dirty only if PHP files change
    • targeted Feature tests and browser command

Rollout Considerations

  • Local development and testing use Sail-first commands.
  • Staging/production should see no fixture route availability if implementation is correct.
  • No environment variables are required unless implementation reuses an existing fixture config pattern; any new env/config must default safe and be documented.
  • No queue, scheduler, storage volume, or Dokploy runtime change is expected.

Risk Controls

  • Auth fixture weakens security: environment guard, route tests, platform/admin guard separation, redirect allowlist.
  • Fixture data brittle: stable factory/config identifiers; no raw hardcoded local IDs without resolver.
  • Scope creep into UI fixes: reports only; follow-up candidates for productization.
  • System panel auth separation: use PlatformUser and platform guard only.
  • Timeouts persist: classify timeout-blocked, document final URL/console state, and avoid speculative UI fixes.

Implementation Phases

  1. Preparation/source audit artifacts.
  2. Fixture design and matrix.
  3. Tests-first for fixture safety.
  4. Minimal local/testing fixture implementation if needed.
  5. Browser smoke and screenshots.
  6. Reports, validation, and follow-up recommendations.

Constitution Check

  • Inventory-first / snapshots-second: no snapshot semantics change; only evidence fixture reachability.
  • Read/write separation: no production write flow; fixture setup only local/testing.
  • Single Graph contract path: no Graph calls are added.
  • Workspace/Tenant isolation: central concern; must be proven in fixture tests.
  • RBAC/server truth: fixture routes cannot become security boundary bypasses.
  • OperationRun truth: unchanged.
  • UI-COV-001: local/testing route impact is classified; existing product pages are audited only.
  • TEST-GOV-001: browser and fixture test cost is explicit and opt-in.
  • BLOAT-001: proportionality review exists because fixture support may add narrow support code.