test: add spec 376 browser fixture coverage

This commit is contained in:
Ahmed Darrazi 2026-06-13 13:12:01 +02:00
parent 8efc8981a4
commit 4bc41ebaab
19 changed files with 1326 additions and 0 deletions

View File

@ -0,0 +1,240 @@
<?php
declare(strict_types=1);
use App\Filament\Resources\EvidenceSnapshotResource;
use App\Models\ManagedEnvironment;
use App\Models\ManagedEnvironmentPermission;
use App\Models\PlatformUser;
use App\Models\ProviderConnection;
use App\Models\User;
use App\Models\Workspace;
use App\Support\Auth\PlatformCapabilities;
use App\Support\ManagedEnvironmentLinks;
use App\Support\Providers\ProviderVerificationStatus;
use Illuminate\Foundation\Testing\RefreshDatabase;
pest()->browser()->timeout(60_000);
uses(RefreshDatabase::class);
beforeEach(function (): void {
config()->set('graph.client_id', 'spec376-platform-client');
config()->set('graph.client_secret', 'spec376-platform-secret');
config()->set('graph.managed_environment_id', 'organizations');
});
it('Spec376 smokes admin evidence, required permissions, and provider connection detail fixtures', function (): void {
$fixture = spec376AdminFixture();
$evidencePath = spec376BrowserPath(EvidenceSnapshotResource::getUrl(
'view',
['record' => $fixture['snapshot']],
tenant: $fixture['environment'],
panel: 'admin',
));
$requiredPermissionsPath = spec376BrowserPath(ManagedEnvironmentLinks::requiredPermissionsUrl($fixture['environment']));
$providerConnectionPath = spec376BrowserPath(ManagedEnvironmentLinks::providerConnectionUrl(
$fixture['connection'],
'view',
$fixture['environment'],
));
visit(spec376BrowserLoginUrl($fixture['user'], $fixture['environment'], $evidencePath))
->resize(1440, 1100)
->waitForText('Outcome summary')
->assertSee('Evidence basis and readiness')
->assertSee('Evidence dimensions')
->assertNoJavaScriptErrors()
->assertNoConsoleLogs()
->screenshot(true, spec376BrowserScreenshot('001-evidence-snapshot-view'));
spec376BrowserCopyScreenshot('001-evidence-snapshot-view');
visit($requiredPermissionsPath)
->resize(1440, 1100)
->waitForText(__('localization.provider_guidance.required_permissions_missing_title'))
->assertSee(__('localization.provider_guidance.action_open_admin_consent'))
->assertNoJavaScriptErrors()
->assertNoConsoleLogs()
->screenshot(true, spec376BrowserScreenshot('002-required-permissions'));
spec376BrowserCopyScreenshot('002-required-permissions');
visit($providerConnectionPath)
->resize(1440, 1100)
->waitForText(__('localization.provider_guidance.provider_readiness_blocked_title'))
->assertSee($fixture['connection']->display_name)
->assertNoJavaScriptErrors()
->assertNoConsoleLogs()
->screenshot(true, spec376BrowserScreenshot('005-provider-connection-detail'));
spec376BrowserCopyScreenshot('005-provider-connection-detail');
});
it('Spec376 smokes system dashboard and operations through platform guard fixtures', function (): void {
$platformUser = PlatformUser::factory()->create([
'capabilities' => [
PlatformCapabilities::ACCESS_SYSTEM_PANEL,
PlatformCapabilities::CONSOLE_VIEW,
PlatformCapabilities::OPERATIONS_VIEW,
],
'is_active' => true,
]);
auth('web')->logout();
$this->flushSession();
$this->actingAs($platformUser, 'platform');
visit('/system')
->resize(1440, 1100)
->waitForText(__('localization.dashboard.system_title'))
->assertNoJavaScriptErrors()
->assertNoConsoleLogs()
->screenshot(true, spec376BrowserScreenshot('003-system-dashboard'));
spec376BrowserCopyScreenshot('003-system-dashboard');
visit('/system/ops/runs')
->resize(1440, 1100)
->waitForText('Operations')
->assertSee('No operations yet')
->assertNoJavaScriptErrors()
->assertNoConsoleLogs()
->screenshot(true, spec376BrowserScreenshot('004-system-operations'));
spec376BrowserCopyScreenshot('004-system-operations');
});
/**
* @return array{
* user: User,
* workspace: Workspace,
* environment: ManagedEnvironment,
* snapshot: \App\Models\EvidenceSnapshot,
* connection: ProviderConnection,
* }
*/
function spec376AdminFixture(): array
{
[$user, $environment] = createUserWithTenant(
role: 'owner',
workspaceRole: 'owner',
ensureDefaultMicrosoftProviderConnection: false,
);
$environment->forceFill([
'name' => 'Spec376 Browser Evidence Environment',
])->save();
$workspace = $environment->workspace()->firstOrFail();
$snapshot = seedEnvironmentReviewEvidence($environment, findingCount: 1, driftCount: 0);
$missingPermissionKey = spec376FirstApplicationPermissionKey();
spec376SeedPermissionRows($environment, missingKeys: [$missingPermissionKey]);
$connection = ProviderConnection::factory()->platform()->verifiedHealthy()->create([
'managed_environment_id' => (int) $environment->getKey(),
'workspace_id' => (int) $workspace->getKey(),
'display_name' => 'Spec376 Provider Connection Detail',
'is_default' => true,
'verification_status' => ProviderVerificationStatus::Healthy->value,
]);
return [
'user' => $user,
'workspace' => $workspace,
'environment' => $environment,
'snapshot' => $snapshot,
'connection' => $connection,
];
}
function spec376FirstApplicationPermissionKey(): string
{
$permission = collect(spec283ConfiguredPermissionRows())
->first(static fn (mixed $row): bool => is_array($row) && ($row['type'] ?? null) === 'application');
expect($permission)->not->toBeNull();
return (string) $permission['key'];
}
/**
* @param array<int, string> $missingKeys
* @param array<int, string> $errorKeys
*/
function spec376SeedPermissionRows(
ManagedEnvironment $environment,
array $missingKeys = [],
array $errorKeys = [],
): void {
foreach (spec283ConfiguredPermissionRows() as $permission) {
if (! is_array($permission)) {
continue;
}
$permissionKey = (string) ($permission['key'] ?? '');
if ($permissionKey === '') {
continue;
}
ManagedEnvironmentPermission::query()->updateOrCreate(
[
'managed_environment_id' => (int) $environment->getKey(),
'permission_key' => $permissionKey,
'workspace_id' => (int) $environment->workspace_id,
],
[
'status' => in_array($permissionKey, $errorKeys, true)
? 'error'
: (in_array($permissionKey, $missingKeys, true) ? 'missing' : 'granted'),
'details' => ['source' => 'spec-376-browser-fixture'],
'last_checked_at' => now(),
],
);
}
}
function spec376BrowserLoginUrl(User $user, ManagedEnvironment $environment, string $redirect): string
{
return route('admin.local.smoke-login', [
'email' => $user->email,
'tenant' => $environment->external_id,
'workspace' => $environment->workspace->slug,
'redirect' => $redirect,
]);
}
function spec376BrowserPath(string $url): string
{
$path = parse_url($url, PHP_URL_PATH) ?: '/admin';
$query = parse_url($url, PHP_URL_QUERY);
return is_string($query) && $query !== '' ? $path.'?'.$query : $path;
}
function spec376BrowserScreenshot(string $name): string
{
return $name;
}
function spec376BrowserCopyScreenshot(string $name): void
{
$filename = spec376BrowserScreenshot($name).'.png';
$source = base_path('tests/Browser/Screenshots/'.$filename);
$targetDirectory = repo_path('specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/screenshots');
if (! is_dir($targetDirectory)) {
@mkdir($targetDirectory, 0755, true);
}
if (! is_file($source)) {
$source = \Pest\Browser\Support\Screenshot::path($filename);
}
for ($attempt = 0; $attempt < 10 && ! is_file($source); $attempt++) {
usleep(100_000);
clearstatcache(true, $source);
}
if (is_file($source) && is_dir($targetDirectory) && is_writable($targetDirectory)) {
@copy($source, $targetDirectory.DIRECTORY_SEPARATOR.$filename);
}
}

View File

@ -0,0 +1,27 @@
# Affected Files
## Planned vs Actual
| File | Purpose | Change type | Runtime/test/spec classification | Surface | Verification level | Risk | Production impact |
|---|---|---|---|---|---|---|---|
| `apps/platform/tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php` | Bounded five-surface browser smoke and screenshot capture | added | Browser test | Evidence, Required Permissions, System Dashboard, System Operations, Provider Connection Detail | `browser-verified` | Browser lane cost only | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/source-audit-summary.md` | Source and blocker audit | added | spec artifact | all in-scope surfaces | `repo-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/route-reachability-report.md` | Route/auth/browser outcome report | added | spec artifact | all in-scope surfaces | `browser-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/fixture-design.md` | Fixture contract | added | spec artifact | all in-scope surfaces | `repo-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/fixture-coverage-matrix.md` | Per-surface fixture matrix | added | spec artifact | all in-scope surfaces | `browser-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/browser-verification-report.md` | Browser pass result | added | spec artifact | all in-scope surfaces | `browser-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/screenshot-index.md` | Screenshot index | added | spec artifact | all in-scope surfaces | `browser-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/validation-report.md` | Validation and lane report | added | spec artifact | all in-scope surfaces | `test-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/follow-up-recommendations.md` | Follow-up candidate list | added | spec artifact | all in-scope surfaces | `repo-verified` | none | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/screenshots/*.png` | Browser screenshots | generated | spec artifact | all in-scope surfaces | `browser-verified` | screenshot upkeep | none |
| `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/tasks.md` | Mark actual completion and N/A conditional tasks | updated | spec artifact | all in-scope surfaces | `repo-verified` | none | none |
## Product Runtime Impact
No product runtime file was changed:
- no routes changed
- no panel provider changed
- no Filament resource/page changed
- no models, migrations, policies, jobs, services, Graph contracts, or OperationRun behavior changed
- no assets registered

View File

@ -0,0 +1,33 @@
# Browser Verification Report
Status: PASS.
## Browser Harness
- Command: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php`
- Result: pass, 2 tests, 21 assertions.
- Fixture family: `apps/platform/tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php`
- Assertions: target text visible, no JavaScript errors, no console logs, screenshots captured.
## URLs Tested
| Page | URL pattern | Result |
|---|---|---|
| Evidence Snapshot View | `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | pass |
| Required Permissions | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | pass |
| System Dashboard | `/system` | pass |
| System Operations | `/system/ops/runs` | pass |
| Provider Connection Detail | `/admin/provider-connections/{record}?environment_id={environment}` | pass |
## Screenshot Outputs
- `artifacts/screenshots/001-evidence-snapshot-view.png`
- `artifacts/screenshots/002-required-permissions.png`
- `artifacts/screenshots/003-system-dashboard.png`
- `artifacts/screenshots/004-system-operations.png`
- `artifacts/screenshots/005-provider-connection-detail.png`
## Notes
- First browser run failed because the Provider Connection detail assertion expected the more specific Required Permissions title. Repo truth from existing Spec 353 feature coverage shows the detail page uses the broader provider-readiness blocked heading. The assertion was corrected; product code was not changed.
- Sail saved screenshots under `apps/platform/tests/Browser/Screenshots/`. Because the Sail container is rooted at `apps/platform`, the spec-copy helper could not resolve host-level `specs/` without an explicit repo-root environment variable. The generated screenshots were copied into this spec artifact directory from the host workspace after the passing run.

View File

@ -0,0 +1,9 @@
# Fixture Coverage Matrix
| Surface | Previous status | Required fixture | Implemented fixture | Reachability result | Screenshot | Verification level | Remaining limitation |
|---|---|---|---|---|---|---|---|
| Evidence Snapshot View | Spec 368 `auth-blocked`; Spec 372 later browser-proved in customer/auditor flow | admin user, workspace context, environment context, evidence snapshot | existing smoke-login + seeded evidence snapshot | reached | `artifacts/screenshots/001-evidence-snapshot-view.png` | `browser-verified` | Screenshot is a fixture proof, not a redesign audit. |
| Required Permissions | Spec 368 `auth-blocked`; Spec 353 later browser-proved provider guidance | admin user, workspace/environment context, permission rows | existing smoke-login + deterministic permission rows | reached | `artifacts/screenshots/002-required-permissions.png` | `browser-verified` | Uses configured permission registry; no live Graph permission check. |
| System Dashboard | Spec 368 `auth-blocked` via `/system/login` redirect | platform user with system dashboard capabilities | Pest Browser `actingAs(..., 'platform')` | reached | `artifacts/screenshots/003-system-dashboard.png` | `browser-verified` | Does not add a reusable manual system smoke-login URL. |
| System Operations | Spec 368 `auth-blocked` via `/system/login` redirect | platform user with operations capability | Pest Browser `actingAs(..., 'platform')` | reached with empty state | `artifacts/screenshots/004-system-operations.png` | `browser-verified` | Empty state is intentional; no operation run was created. |
| Provider Connection Detail | Spec 368 detail attempt timed out/was unstable; Spec 353 proved provider guidance | admin user, workspace context, provider connection, explicit environment authority | existing admin session + scoped provider connection fixture | reached | `artifacts/screenshots/005-provider-connection-detail.png` | `browser-verified` | Fixture uses fake provider identifiers and no live provider calls. |

View File

@ -0,0 +1,36 @@
# Fixture Design
## Design Decision
No new fixture route or command is needed. Existing repo-native patterns are sufficient:
- Admin-plane surfaces use `GET /admin/local/smoke-login` in `local`/`testing`.
- System-plane surfaces use Pest Browser `actingAs($platformUser, 'platform')`.
- Data is created with existing factories and test helpers.
## Per-Surface Fixture Contract
| Surface | Auth | Scope | Data source | Existing fixture source | New fixture source | Local/testing guarantee | Browser URL | Failure mode if regressed |
|---|---|---|---|---|---|---|---|---|
| Evidence Snapshot View | `web` guard through `admin.local.smoke-login` | workspace + environment | `seedEnvironmentReviewEvidence()` | Spec 372 smoke pattern | Spec 376 local test fixture | smoke-login route is local/testing-only | `EvidenceSnapshotResource::getUrl('view', ...)` | `auth-blocked`, `scope-blocked`, or `data-blocked` |
| Required Permissions | `web` guard through `admin.local.smoke-login` | workspace + environment | `ManagedEnvironmentPermission` rows from configured permission registry | Spec 353/283 patterns | Spec 376 local permission seed helper | smoke-login route is local/testing-only | `ManagedEnvironmentLinks::requiredPermissionsUrl()` | `auth-blocked`, `scope-blocked`, or `data-blocked` |
| System Dashboard | `platform` guard via Pest Browser `actingAs` | platform plane | `PlatformUser` capabilities | Spec 276 pattern | Spec 376 platform user fixture | no HTTP fixture route added | `/system` | `auth-blocked` or `capability-blocked` |
| System Operations | `platform` guard via Pest Browser `actingAs` | platform plane | same `PlatformUser`; empty-state data allowed | Spec 276 pattern | Spec 376 platform user fixture | no HTTP fixture route added | `/system/ops/runs` | `auth-blocked` or `capability-blocked` |
| Provider Connection Detail | `web` guard through existing admin session | workspace + record-derived environment authority | `ProviderConnection::factory()->platform()->verifiedHealthy()` plus explicit `environment_id` | Spec 353/281 patterns | Spec 376 local provider connection fixture | no new route added | `ManagedEnvironmentLinks::providerConnectionUrl(..., 'view', $environment)` | `scope-blocked`, `data-blocked`, or `timeout-blocked` |
## Route Safety
- No system smoke-login route was added.
- No admin smoke-login behavior was changed.
- No redirect validation behavior was changed.
- No production route or product UI route was added.
## Browser Screenshot Contract
Screenshots are saved under `artifacts/screenshots/`:
- `001-evidence-snapshot-view.png`
- `002-required-permissions.png`
- `003-system-dashboard.png`
- `004-system-operations.png`
- `005-provider-connection-detail.png`

View File

@ -0,0 +1,21 @@
# Follow-Up Recommendations
## Recommended Next Spec
Spec 377 - Post-Productization Browser Re-Audit & Closeout Gate v1.
Rationale: Spec 376 now provides fixture-backed browser access and screenshots for the evidence/system/provider surfaces that blocked a credible closeout pass. The next useful slice is a productization closeout audit, not more fixture plumbing.
## Contained Notes
- If future Sail browser runs need to copy screenshots directly into root-level `specs/`, set or document an explicit repo-root path for Pest Browser artifact copying. This is tooling ergonomics, not product behavior.
- System panel manual browser login remains separate from Pest Browser platform-guard proof. Add a local/testing system smoke-login route only if a future spec requires manual system screenshots outside Pest Browser.
## Not In Scope For Spec 376
- Evidence Snapshot UI productization.
- Required Permissions redesign.
- System panel redesign.
- Provider Connection readiness/detail redesign.
- Browser scorecard integration with the UI bloat guard.
- Any production auth route or fixture route.

View File

@ -0,0 +1,28 @@
# Route Reachability Report
## Final Browser Outcomes
| Surface | Route/path | Panel | Auth guard | Required parameters | Fixture parameters | HTTP/browser outcome | Final URL pattern | Verification label |
|---|---|---|---|---|---|---|---|---|
| Evidence Snapshot View | `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | admin | `web` | workspace slug, environment slug, evidence snapshot id | `Test Workspace`, `Spec376 Browser Evidence Environment`, seeded snapshot | Rendered in browser, no JS errors, no console logs, screenshot captured | `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | `browser-verified` |
| Required Permissions | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | admin | `web` | workspace slug, environment slug | same workspace/environment, seeded permission rows | Rendered in browser, no JS errors, no console logs, screenshot captured | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | `browser-verified` |
| System Dashboard | `/system` | system | `platform` | platform user with `platform.access_system_panel` plus dashboard capability | `PlatformUser` with `ACCESS_SYSTEM_PANEL`, `CONSOLE_VIEW`, `OPERATIONS_VIEW` | Rendered in browser, no JS errors, no console logs, screenshot captured | `/system` | `browser-verified` |
| System Operations | `/system/ops/runs` | system | `platform` | platform user with operations capability | same `PlatformUser` | Rendered empty state in browser, no JS errors, no console logs, screenshot captured | `/system/ops/runs` | `browser-verified` |
| Provider Connection Detail | `/admin/provider-connections/{record}?environment_id={environment}` | admin | `web` | provider connection id, explicit `environment_id`, workspace session | `Spec376 Provider Connection Detail` for the selected environment | Rendered in browser, no JS errors, no console logs, screenshot captured | `/admin/provider-connections/{record}?environment_id={environment}` | `browser-verified` |
## Route Inventory Sources
- Laravel Boost `list_routes(path: admin)` confirmed:
- `admin/local/smoke-login`
- `admin/workspaces/{workspace}/environments/{environment}/evidence/{record}`
- `admin/workspaces/{workspace}/environments/{environment}/required-permissions`
- `admin/provider-connections/{record}`
- Laravel Boost `list_routes(path: system)` confirmed:
- `system`
- `system/ops/runs`
## Redirect/Login Behavior
- Admin surfaces used `admin.local.smoke-login` once, with redirect to Evidence Snapshot View. Subsequent admin surface visits used the same authenticated browser session.
- System surfaces did not use a smoke-login route. They used Pest Browser `actingAs($platformUser, 'platform')`, preserving platform-plane separation.
- No tested surface redirected to `/admin/login` or `/system/login`.

View File

@ -0,0 +1,19 @@
# Screenshot Index
| Screenshot | Surface | Reachable | Blocked reason | Notes |
|---|---|---:|---|---|
| `artifacts/screenshots/001-evidence-snapshot-view.png` | Evidence Snapshot View | yes | N/A | Captured via admin smoke-login redirect to environment-scoped evidence view. |
| `artifacts/screenshots/002-required-permissions.png` | Required Permissions | yes | N/A | Captured with deterministic missing application permission fixture. |
| `artifacts/screenshots/003-system-dashboard.png` | System Dashboard | yes | N/A | Captured with platform user on `platform` guard. |
| `artifacts/screenshots/004-system-operations.png` | System Operations | yes | N/A | Captured empty state with platform user on `platform` guard. |
| `artifacts/screenshots/005-provider-connection-detail.png` | Provider Connection Detail | yes | N/A | Captured with scoped provider connection and explicit `environment_id`. |
## File Sanity
All screenshots are PNG files:
- Evidence Snapshot View: 1440 x 4691
- Required Permissions: 1440 x 2371
- System Dashboard: 1440 x 1584
- System Operations: 1440 x 1100
- Provider Connection Detail: 1440 x 1675

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

View File

@ -0,0 +1,61 @@
# Source Audit Summary
## Scope
Spec 376 covers browser fixture reachability and evidence for these existing surfaces only:
| Surface | Current repo path | Spec 376 handling |
|---|---|---|
| Evidence Snapshot View | `EvidenceSnapshotResource::getUrl('view', ...)` under `/admin/workspaces/{workspace}/environments/{environment}/evidence/{record}` | Fresh browser-verified screenshot using existing admin smoke-login fixture. |
| Required Permissions | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | Fresh browser-verified screenshot using existing admin smoke-login fixture and deterministic permission rows. |
| System Dashboard | `/system` | Fresh browser-verified screenshot using `PlatformUser` on the `platform` guard. |
| System Operations | `/system/ops/runs` | Fresh browser-verified screenshot using `PlatformUser` on the `platform` guard. |
| Provider Connection Detail | `/admin/provider-connections/{record}?environment_id={environment}` | Fresh browser-verified screenshot using scoped provider connection data and explicit environment authority. |
## Input Evidence
| Source | Relevant signal | Handling |
|---|---|---|
| Spec 368 `findings.md` | Evidence Snapshot detail redirected to `/admin/login`; System Dashboard/Ops redirected to `/system/login`. | Treated as the original blocker this spec closes. |
| Spec 368 `audit.md` | Required Permissions, Evidence Snapshot, and System pages were blocked by auth/fixture reachability. | Route/auth/data/browser truth is separated in Spec 376 reports. |
| Spec 353 | Required Permissions and Provider Connection browser screenshots exist under the Spec 353 package. | Used as completed context; not rewritten. |
| Spec 372 | Evidence Snapshot View browser pass exists with customer/auditor fixture. | Used as completed context; Spec 376 adds a consolidated fresh screenshot. |
| Spec 375 | Evidence/system browser fixture coverage remained a deferred follow-up. | Spec 376 implements that follow-up. |
## Related Completed Specs 370-375
| Spec | Relevant status | Handling |
|---|---|---|
| 370 | Source audit named Evidence Snapshot, Required Permissions, System Dashboard, and System Operations as `not available` source limitations. | Spec 376 adds browser fixture evidence for these limitations. |
| 371 | Backup Set browser verification passed and is outside the five-surface Spec 376 scope. | Read-only context. |
| 372 | Evidence Snapshot View browser verification passed in customer/auditor safety flow. | Read-only context plus fresh Spec 376 consolidated screenshot. |
| 373 | Diagnostic surfaces passed browser verification and explicitly did not recapture Provider Connections or Required Permissions. | Read-only context. |
| 374 | Diagnostic entrypoint browser verification passed and remained scoped to diagnostic/support handoff surfaces. | Read-only context. |
| 375 | Deferred evidence/system browser fixtures as a follow-up. | Implemented by this package. |
## Repo Truth
- Existing admin smoke-login route: `GET /admin/local/smoke-login`, local/testing-only, covered by `AdminLocalSmokeLoginTest`.
- Existing system auth route and panel: `SystemPanelProvider` uses `authGuard('platform')`, `UseSystemSessionCookie`, and `ensure-platform-capability:platform.access_system_panel`.
- Existing Pest Browser system proof: `Spec276SupportAccessGovernanceSmokeTest` authenticates with `$this->actingAs($platformUser, 'platform')`.
- `EvidenceSnapshotResource` has `protected static bool $isGloballySearchable = false`.
- `ProviderConnectionResource` has `protected static bool $isGloballySearchable = false`.
- Required Permissions and System surfaces are Filament pages, not globally searchable resources.
## Implementation Option Selected
Reuse existing fixtures and add one bounded browser smoke file:
- No new admin smoke route.
- No new system smoke route.
- No new Artisan fixture command.
- No production auth, policy, resource, panel, model, migration, Graph, or OperationRun behavior change.
## Fixture Gaps Closed
| Gap | Result |
|---|---|
| Evidence Snapshot auth fixture unclear | Closed by smoke-login redirect to environment-scoped evidence URL. |
| Required Permissions auth/data fixture unclear | Closed by smoke-login plus deterministic `ManagedEnvironmentPermission` rows. |
| System panel browser fixture absent | Closed by direct Pest Browser platform-guard `actingAs`. |
| Provider Connection detail timeout vs real defect unclear | Closed by scoped browser screenshot with explicit `environment_id`. |

View File

@ -0,0 +1,63 @@
# Validation Report
## Starting State
- Branch before session: `376-browser-audit-fixture-coverage-evidence-system-surfaces`
- Session branch: `376-browser-audit-fixture-coverage-evidence-system-surfaces-session-1781347251`
- Baseline HEAD: `8efc8981 feat(guard): implement ui bloat regression guard (#446)`
- Initial dirty state: untracked active spec directory `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/`
- Scope decision: no product UI refactor; no production auth change; no new route.
## Commands Run
| Command | Result |
|---|---|
| `php -l apps/platform/tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php` | pass |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/AdminLocalSmokeLoginTest.php tests/Feature/Auth/SystemPanelAuthTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php tests/Feature/RequiredPermissions/RequiredPermissionsAccessTest.php tests/Feature/ProviderConnections/Spec353ProviderConnectionGuidanceTest.php` | pass, 32 tests, 178 assertions |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php` | first run failed on over-specific Provider Connection copy assertion |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php` | pass, 2 tests, 21 assertions |
| `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` | pass |
| `git diff --check` | pass |
| `git add -N ... && git diff --check` against new/untracked files, then clear intent-to-add markers | pass after markdown EOF/trailing-space cleanup |
| `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec376BrowserAuditFixtureCoverageSmokeTest.php` | final rerun pass, 2 tests, 21 assertions |
## Browser Result
PASS. All five in-scope surfaces were reached in a real Pest Browser run:
- Evidence Snapshot View
- Required Permissions
- System Dashboard
- System Operations
- Provider Connection Detail
All reachable pages asserted:
- target surface text visible
- no JavaScript errors
- no console logs
- screenshot captured
## Screenshot Result
Pest Browser saved screenshots under `apps/platform/tests/Browser/Screenshots/`. The generated files were copied into:
`specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/artifacts/screenshots/`
## Lane / Runtime Impact
- Browser lane: one new bounded Spec 376 browser family.
- Feature lane: existing fixture/auth/surface Feature tests passed and remain the proof for route safety.
- Product runtime: no runtime behavior changed.
- Browser cost: material but explicit and bounded to five surfaces.
- Escalation outcome: `document-in-feature`.
## Limitations
- System surfaces are browser-auditable through Pest Browser platform-guard `actingAs`, not through a manual browser smoke-login URL.
- Screenshot helper copy into host-level `specs/` requires either host-side copy after Sail runs or a future explicit `TENANTATLAS_REPO_ROOT` environment path when running inside Sail.
- This is reachability and fixture proof, not a full UI redesign audit.
## Closeout Audit Readiness
Spec 376 closes the fixture/evidence gap needed before a later post-productization browser re-audit can proceed.

View File

@ -0,0 +1,66 @@
# Requirements Checklist: Browser Audit Fixture Coverage for Evidence/System Surfaces v1
**Purpose**: Validate that Spec 376 is preparation-ready, bounded to browser fixture coverage, and safe against production auth or UI scope creep.
**Created**: 2026-06-13
**Feature**: `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md`
## Applicability And Scope
- [x] CHK001 The spec states this is browser fixture coverage/auditability, not UI productization.
- [x] CHK002 The five in-scope surfaces are named explicitly.
- [x] CHK003 The out-of-scope list forbids product UI refactors, production auth changes, migrations, models, policies, Graph changes, and OperationRun changes.
- [x] CHK004 Close alternatives are deferred instead of hidden inside the primary scope.
- [x] CHK005 Related completed specs are read-only context and are not refresh targets.
## Candidate Gate
- [x] CHK006 The selected candidate is directly supplied by the user and supported by Spec 368/375 repo artifacts.
- [x] CHK007 The candidate is not already covered by an active or completed spec package.
- [x] CHK008 The Spec Candidate Check includes problem, today's failure, smallest version, complexity, why now, approval class, red flags, score, and decision.
- [x] CHK009 The selected slice is small enough for a bounded implementation loop.
## UI / Surface Guardrail
- [x] CHK010 UI Surface Impact records the local/testing route impact without claiming production product UI changes.
- [x] CHK011 UI/Productization Coverage classifies the existing pages as browser-audit targets, not refactor targets.
- [x] CHK012 The plan states `docs/ui-ux-enterprise-audit` updates are unnecessary unless implementation materially changes a production surface.
- [x] CHK013 Screenshot/report expectations are proportional and limited to the five target surfaces.
## Auth, RBAC, And Isolation
- [x] CHK014 Admin fixture work preserves workspace/environment context and capability requirements.
- [x] CHK015 System fixture work preserves `PlatformUser`, `platform` guard, and platform capability separation.
- [x] CHK016 Any new fixture route must be local/testing-only and 404 outside those environments.
- [x] CHK017 Redirect validation and arbitrary URL rejection are required for fixture auth routes.
- [x] CHK018 Non-member 404 and member-without-capability 403 semantics are preserved where applicable.
## Data And Truth
- [x] CHK019 Fixture data is deterministic, minimal, and local/testing-only.
- [x] CHK020 No production data dependency or hardcoded fragile IDs are accepted.
- [x] CHK021 Reports distinguish route truth, auth truth, data truth, browser screenshot truth, and follow-up truth.
- [x] CHK022 Verification labels are report classifications, not product states.
## OperationRun And Provider Boundary
- [x] CHK023 OperationRun start/completion/link UX is explicitly N/A.
- [x] CHK024 System Operations may be opened but no OperationRun lifecycle behavior may change.
- [x] CHK025 Provider boundary impact is classified as mixed and limited to fixture reachability.
- [x] CHK026 Provider-specific semantics are not generalized into platform-core truth.
## Testing And Validation
- [x] CHK027 Test lanes are explicit: Feature tests for fixture/auth safety, Browser lane for reachability/screenshots.
- [x] CHK028 Pest Browser assertions include no JS errors and no console logs for reachable pages.
- [x] CHK029 The planned validation commands include `git diff --check`, Pint if PHP changed, targeted Feature tests, and targeted browser smoke.
- [x] CHK030 Heavy/browser cost is explicit and not silently folded into broad fast-feedback.
## Preparation Review Classification
- [x] CHK031 Review outcome class: `acceptable-special-case`.
- [x] CHK032 Workflow outcome: `keep`.
- [x] CHK033 Final note location: the later implementation should use Spec 376 `artifacts/validation-report.md` plus the PR close-out as Smoke Coverage / Fixture Coverage.
## Notes
Preparation status: ready for implementation-loop review after artifact consistency analysis. No application implementation was performed during preparation.

View File

@ -0,0 +1,272 @@
# 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.

View File

@ -0,0 +1,324 @@
# Feature Specification: Browser Audit Fixture Coverage for Evidence/System Surfaces v1
**Feature Branch**: `376-browser-audit-fixture-coverage-evidence-system-surfaces`
**Created**: 2026-06-13
**Status**: Draft
**Input**: User-provided Spec 376 candidate, Spec 368 browser audit findings, completed Spec 353/372 browser evidence, Spec 375 follow-up recommendation, current repo route/auth/test fixtures.
## Spec Candidate Check *(mandatory - SPEC-GATE-001)*
- **Problem**: Spec 368 could not browser-audit critical Evidence, Required Permissions, Provider Connection detail, and System panel surfaces because auth, scope, data, or screenshot fixtures were missing or unstable. Later specs proved parts of the admin-plane surface set, but no single Spec 376 evidence package records current route/auth/data/browser truth for all five surfaces, and system-panel browser proof remains a separate platform-auth gap.
- **Today's failure**: The product can claim these surfaces are repo-real, but a reviewer cannot reproducibly prove the full five-surface set in a browser without manually stitching together Spec 353/372 evidence, auth state, workspace/environment IDs, platform-user state, and fixture data.
- **User-visible improvement**: Maintainers and future audit agents can open the scoped surfaces through safe local/testing fixtures, capture screenshots, and classify any remaining block as auth-, data-, route-, scope-, or timeout-blocked with exact evidence.
- **Smallest enterprise-capable version**: A narrow browser fixture coverage slice for five surfaces: Evidence Snapshot View, Required Permissions, System Dashboard, System Operations, and Provider Connection Detail. Each surface is classified from current repo truth, then either fixture-backed and screenshot-captured in this package or documented with exact existing evidence, blocker, and follow-up.
- **Explicit non-goals**: No Evidence UI redesign, Required Permissions redesign, System panel redesign, Provider Connection UX refactor, production login backdoor, new product feature, migration, new product source of truth, RBAC weakening, or final platform-wide re-audit.
- **Permanent complexity imported**: Potentially one local/testing-only system smoke login path or fixture resolver only if existing Browser `actingAs(..., 'platform')` patterns are insufficient, fixture configuration entries, focused Feature/Browser tests, and spec-local audit artifacts. No new product table, product enum/status family, or reusable UI framework is approved by this spec.
- **Why now**: Specs 368-375 deliberately productized and guarded UI surfaces, but Spec 368 left a browser-proof gap for critical evidence/system/permission surfaces. Spec 375 explicitly deferred this candidate as the next fixture/auditability follow-up.
- **Why not local**: Manual browser login and ID lookup do not produce repeatable evidence, do not prove production safety of fixture routes, and cannot support future close-out audits.
- **Approval class**: Core Enterprise.
- **Red flags triggered**: New fixture/support path and multiple surfaces. Defense: all work is local/testing-only or test-owned, uses existing smoke-login/browser fixture patterns where possible, creates no product truth, and keeps UI/product behavior unchanged.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve as a narrow browser-fixture coverage and auditability slice.
## Candidate Selection And Completed-Spec Guardrail
- **Selected candidate**: Browser Audit Fixture Coverage for Evidence/System Surfaces v1.
- **Source**: User-provided Spec 376 attachment, Spec 368 `findings.md` / `audit.md` / `page-scorecard.csv`, Spec 353 provider readiness browser coverage, Spec 372 Evidence Snapshot browser coverage, and Spec 375 follow-up recommendations.
- **Roadmap relationship**: Supports the current UI/product maturity and auditability lane by closing browser-proof gaps after Specs 368-375.
- **Related completed specs**:
- Spec 368 is a completed browser audit input with blocked-page evidence; it is not modified.
- Specs 370-374 are completed UI IA/productization/safety/diagnostic inputs; they are read-only context.
- Spec 375 implemented or prepared the UI bloat guard and explicitly listed this fixture coverage candidate as deferred follow-up; it is not modified.
- **Guardrail result**: No existing spec package covers this exact consolidated five-surface fixture/evidence slice. Completed specs are current repo truth and context only; they must not be rewritten, normalized, reopened, or stripped of implementation history.
- **Close alternatives deferred**:
- Full post-productization browser re-audit and closeout gate.
- Provider Connections readiness redesign.
- Evidence Snapshot customer/auditor productization.
- System panel productization or ops workflow redesign.
- Browser scorecard integration into guard output.
- **Smallest viable slice**: Build or document safe local/testing fixture access for the five in-scope surfaces, then produce route/auth/data/screenshot evidence and a validation report.
## Spec Scope Fields *(mandatory)*
- **Scope**: canonical-view / browser-fixture auditability.
- **Primary Routes**:
- Evidence Snapshot View: `EvidenceSnapshotResource::getUrl('view', ...)`, currently slugged under environment-scoped `evidence/{record}`.
- Required Permissions: `/admin/workspaces/{workspace}/environments/{environment}/required-permissions`.
- System Dashboard: `/system`.
- System Operations: `/system/ops/runs`.
- Provider Connection Detail: `ProviderConnectionResource::getUrl('view', ...)`, currently `provider-connections/{record}` with workspace-hub authority and explicit `environment_id`/record-derived managed-environment authority.
- **Data Ownership**: Fixture data remains local/testing-only. Evidence snapshots are tenant-owned records requiring workspace and managed-environment entitlement. Provider connections are workspace-owned records with managed-environment authority for record actions and explicit environment context for scoped URLs. System panel actors are platform-plane `PlatformUser` records.
- **RBAC**: Admin surfaces require authenticated `User` membership plus the relevant capability. System surfaces require authenticated `PlatformUser`, `platform` guard, `platform.access_system_panel`, and any page-specific platform capability.
For canonical-view specs:
- **Default filter behavior when tenant-context is active**: Admin fixture URLs must establish workspace context and remembered environment context explicitly. They must not rely on arbitrary stale session state.
- **Explicit entitlement checks preventing cross-tenant leakage**: Fixture route/resolver work must use existing scoped resolvers, factories, policies, and capabilities. Non-member records remain 404/deny-as-not-found; member-without-capability remains 403 where the existing policy model says so.
## UI Surface Impact *(mandatory - UI-COV-001)*
Does this spec add, remove, rename, or materially change any reachable UI surface?
- [x] No UI surface impact
- [ ] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [ ] Status/evidence/review presentation changed
- [ ] Workspace/environment context presentation changed
No new route was needed during implementation. Browser coverage reuses the existing local/testing admin smoke-login route and Pest Browser platform-guard session support. The in-scope product pages already exist and were not redesigned or materially changed by this spec.
## UI/Productization Coverage *(mandatory when UI Surface Impact is not "No UI surface impact")*
- **Route/page/surface**: No new route. Browser-audit coverage applies to Evidence Snapshot View, Required Permissions, System Dashboard, System Operations, and Provider Connection Detail through existing test/session fixtures.
- **Current or new page archetype**:
- Evidence Snapshot View: History / Audit Surface, Tertiary Evidence / Diagnostics.
- Required Permissions: Utility / System diagnostic surface, Secondary Context.
- System Dashboard and System Operations: Utility / System, platform-admin surfaces.
- Provider Connection Detail: Record / Detail / Edit, configuration/readiness surface.
- Smoke auth/fixture route: test/tooling route, not product UI.
- **Design depth**: Existing product pages are `Manual Review Required` only for browser reachability proof; no design refactor in scope.
- **Repo-truth level**: repo-verified routes/classes; Spec 353, Spec 372, and Spec 283 already provide browser evidence for several admin-plane surfaces, while system-plane surfaces and any missing consolidated screenshots remain to be proven or documented by this spec.
- **Existing pattern reused**: `/admin/local/smoke-login`, direct Pest Browser `actingAs()`/workspace-session harnesses, `SeedReviewOutputBrowserFixture`, Spec 353 provider readiness browser smoke, Spec 372 Evidence Snapshot browser smoke, Spec 276 system-panel browser `actingAs(..., 'platform')` pattern, Pest Browser `visit()`, existing Feature tests for admin smoke login, system panel auth, EvidenceSnapshotResource, Required Permissions, and ProviderConnectionResource.
- **New pattern required**: None for production UI and none implemented. A local/testing-only system smoke fixture may be added only in a future spec if existing system browser auth patterns are insufficient and the new route preserves platform guard separation, environment gating, and redirect safety.
- **Screenshot required**: yes for every in-scope surface that is reachable; blocked screenshots or blocker notes are required when not reachable.
- **Page audit required**: no redesign audit in this spec; the browser verification report and screenshot index are required.
- **Customer-safe review required**: Evidence surfaces are audit/evidence-sensitive, but this spec does not change default customer/auditor content.
- **Dangerous-action review required**: no new destructive product action is allowed. If fixture routes authenticate users, production-safety and redirect validation are mandatory.
- **Coverage files updated or explicitly not needed**:
- [ ] `docs/ui-ux-enterprise-audit/route-inventory.md`
- [ ] `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
- [ ] `docs/ui-ux-enterprise-audit/page-reports/...`
- [ ] `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
- [ ] `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
- [ ] `docs/ui-ux-enterprise-audit/unresolved-pages.md`
- [x] `N/A - no production product UI surface material change`
- **No-impact rationale when applicable**: Product pages, panel navigation, product actions, product tables, forms, and rendered business copy are not changed. Fixture/audit artifacts live under this spec package unless implementation proves a durable UI audit registry update is required.
## Cross-Cutting / Shared Pattern Reuse
- **Cross-cutting feature?**: yes, as browser fixture infrastructure and audit evidence across admin and system planes.
- **Interaction class(es)**: auth/session fixture, browser smoke, evidence/report viewer reachability, system panel reachability.
- **Systems touched**: existing local smoke login route, fixture seed commands/config, Pest Browser tests, system panel auth, scoped route helpers.
- **Existing pattern(s) to extend**: existing admin smoke login, direct Browser `actingAs()`/workspace-session harnesses, review-output browser fixture patterns, Spec 353/372 admin browser coverage, existing system panel browser `actingAs(..., 'platform')`, system panel auth tests, and platform user capability model.
- **Shared contract / presenter / builder / renderer to reuse**: N/A for UI rendering. Reuse existing scoped URL helpers and auth/session middleware rather than inventing a product UI layer.
- **Why the existing shared path is sufficient or insufficient**: Admin smoke login and direct browser session fixtures now cover several admin-plane paths in completed follow-up specs, but the evidence is spread across packages. System panel has auth tests and browser smokes using `actingAs(..., 'platform')`; a separate smoke-login route is not justified unless those repo-native patterns cannot produce the required Spec 376 browser evidence.
- **Allowed deviation and why**: A system-specific local/testing smoke fixture is allowed only as a last resort when existing browser auth patterns are insufficient, and only if it preserves platform guard separation and production 404 behavior.
- **Consistency impact**: Auth fixtures must never become production access paths or alternate RBAC semantics.
- **Review focus**: Verify no production auth weakening, no arbitrary redirects, no shared tenant/platform identity shortcut, and no UI redesign slipped into fixture work.
## OperationRun UX Impact
- **Touches OperationRun start/completion/link UX?**: no. It may open existing OperationRun/System Operations pages but must not create, queue, deduplicate, resume, block, complete, or change OperationRun UX.
- **Shared OperationRun UX contract/layer reused**: N/A.
- **Delegated start/completion UX behaviors**: N/A.
- **Local surface-owned behavior that remains**: browser verification only.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception required?**: none.
## Provider Boundary / Platform Core Check
- **Shared provider/platform boundary touched?**: yes, narrowly for Provider Connection detail fixture reachability and Required Permissions URLs.
- **Boundary classification**: mixed; provider-owned records remain provider-specific, while workspace/environment scope and auth fixture behavior are platform-core safety boundaries.
- **Seams affected**: ProviderConnectionResource view URL, RequiredPermissionsLinks, provider connection fixture selection, managed-environment scope.
- **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, platform user, system panel.
- **Provider-specific semantics retained and why**: Microsoft permission/consent semantics remain in the existing Required Permissions surface; this spec only makes the page auditable.
- **Why this does not deepen provider coupling accidentally**: The fixture resolver must select existing provider records and URLs; it must not add a new provider framework, provider taxonomy, or Graph endpoint behavior.
- **Follow-up path**: Provider readiness or Required Permissions UX issues discovered during browser capture become follow-up recommendations, not in-scope refactors.
## UI / Surface Guardrail Impact
| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Local/testing smoke auth or fixture route | no production product surface change | N/A | auth fixture | session, route | no, if local/testing-only | test/tooling route only |
| Evidence Snapshot browser fixture | no rendered page change | Native Filament resource view | evidence viewer | route, auth, scope, data | no | browser reachability proof only |
| Required Permissions browser fixture | no rendered page change | Native Filament page/table | diagnostics/permissions | route, auth, scope, data | no | browser reachability proof only |
| System Dashboard/Ops browser fixture | no rendered page change | Native Filament system pages | system plane | route, auth guard, session | no | platform-auth proof only |
| Provider Connection Detail browser fixture | no rendered page change | Native Filament resource view | provider readiness/config | route, auth, scope, data | no | screenshot stability proof only |
## Decision-First Surface Role
No product surface is added or materially changed. The existing surfaces are classified only so browser coverage evidence is interpreted correctly:
| Surface | Decision Role | Human-in-the-loop Moment | Immediately Visible for First Decision | On-Demand Detail / Evidence | Why This Is Primary or Why Not | Workflow Alignment | Attention-load Reduction |
|---|---|---|---|---|---|---|---|
| Evidence Snapshot View | Tertiary Evidence / Diagnostics | Verify evidence backing a review/finding/report | Snapshot identity, status, scope, evidence basis | Raw payloads, related items, operation context | Not primary; supports proof and audit | Evidence verification | Removes manual ID hunting |
| Required Permissions | Secondary Context Surface | Decide what permission/readiness gap blocks provider-backed work | Missing/present permission status and guidance | Permission detail and admin consent links | Not primary; supports diagnostics | Provider readiness check | Makes blocked readiness inspectable |
| System Dashboard | Secondary Context Surface | Platform admin checks system health | System health and key platform status | Support diagnostics and raw ops context | System utility surface | Platform support workflow | Enables separate system audit path |
| System Operations | Tertiary Evidence / Diagnostics | Platform admin inspects system runs | Run list/status and filters | Run detail, logs, diagnostics | Audit/support evidence | Platform operations review | Proves system ops route separately |
| Provider Connection Detail | Secondary Context Surface | Operator/support checks provider readiness | Connection status, capability/readiness | Credentials/technical detail where authorized | Detail/config surface | Provider readiness | Stabilizes screenshot capture |
## Audience-Aware Disclosure
No rendered disclosure hierarchy is changed. Browser reports must still record whether any in-scope surface exposes unexpected raw/support detail by default, but implementation must not fix those issues inside this spec unless a blocker is caused by fixture-only code.
## UI/UX Surface Classification
| Surface | Action Surface Class | Surface Type | Likely Next Operator Action | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type / Justification |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Evidence Snapshot View | Record / Detail / Edit | History / Audit Surface | Verify evidence snapshot | Dedicated detail page | N/A | Related links/actions only | None expected | evidence list | evidence detail | Workspace + environment | Evidence Snapshot | Snapshot status, scope, evidence basis | none |
| Required Permissions | Utility / System | Diagnostic Surface | Review missing permissions | Page table/matrix | N/A | Body guidance/reset | No destructive action in scope | N/A | required permissions page | Workspace + environment | Required Permissions | Permission status and guidance | none |
| System Dashboard | Utility / System | Platform Support Surface | Inspect system health | Dedicated system page | N/A | System nav/actions | Existing system actions only | `/system` | `/system` | System plane | System Dashboard | Platform health/status | none |
| System Operations | Utility / System | Monitoring / Queue / Workbench | Inspect runs | List/detail navigation | Existing page behavior | Existing system nav/actions | Existing system actions only | `/system/ops/runs` | `/system/ops/runs/{run}` | System plane | System Operations | Run state and filters | none |
| Provider Connection Detail | Record / Detail / Edit | Config-lite / configuration detail | Check readiness | Clickable row to detail | existing list behavior | More/detail header | Existing dangerous actions remain unchanged | provider connections list | provider connection view | Workspace + optional environment filter | Provider Connection | Readiness/capability state | none |
## Operator Surface Contract
No new operator product page is added. The implementation must produce evidence that each existing in-scope surface can be opened or is explicitly blocked, with no requirement to change default-visible content.
## Proportionality Review
- **New source of truth?**: no product source of truth.
- **New persisted entity/table/artifact?**: no database table or product artifact. Spec-local Markdown reports and screenshots are implementation evidence only.
- **New abstraction?**: possibly, a narrow local/testing fixture resolver or config path if existing fixture commands cannot cover the surfaces.
- **New enum/state/reason family?**: no product status family. Verification labels are report classifications only.
- **New cross-domain UI framework/taxonomy?**: no.
- **Current operator problem**: Critical surfaces cannot be proven in browser audits without manual auth/data discovery, leaving false confidence gaps in evidence and system-plane readiness.
- **Existing structure is insufficient because**: Existing evidence is split across Spec 353, Spec 372, Spec 368, and route/auth tests; system panel auth remains separate and lacks a consolidated browser-audit fixture or procedure for this five-surface close-out slice.
- **Narrowest correct implementation**: Reuse existing fixtures first, add only local/testing-only fixture glue where necessary, and record exact blockers where not safely solvable.
- **Ownership cost**: Focused fixture tests, browser smoke upkeep, spec-local screenshot/report artifacts, and review of any local/testing route safety.
- **Alternative intentionally rejected**: Full UI redesign or final browser re-audit is too broad; manual-only browser notes do not create reproducible proof; production-accessible smoke login is forbidden.
- **Release truth**: Current-release truth; this is an auditability and safety proof gap now blocking a credible close-out browser audit.
### Compatibility posture
This feature assumes a pre-production environment. No legacy aliases, migration shims, production backfills, or compatibility-specific paths are needed. Any fixture route must be unavailable outside `local` and `testing`; any fixture command must fail closed outside approved environments.
## Testing / Lane / Runtime Impact
- **Test purpose / classification**: Feature tests for route/auth fixture safety, Browser tests/smoke for reachability and screenshot capture, targeted existing Feature tests for Evidence/Required Permissions/Provider/System behavior.
- **Validation lane(s)**: fast-feedback/confidence for Feature tests; browser lane for Pest Browser smoke; `git diff --check`; Pint only if PHP changes.
- **Why this classification and these lanes are sufficient**: The change is about HTTP/session/auth reachability and real browser proof, not domain calculation. Browser assertions must include `assertNoJavaScriptErrors()` and `assertNoConsoleLogs()` where pages are reachable.
- **New or expanded test families**: One bounded Spec 376 browser fixture coverage family; possibly one focused Feature test family for system smoke-login safety if a system local/testing route is added.
- **Fixture / helper cost impact**: Workspace, environment, membership/capability, evidence snapshot, provider connection, and platform-user fixtures may be required, but must stay explicit and opt-in.
- **Heavy-family visibility / justification**: Browser coverage is explicit because this spec exists to close browser-audit gaps. It must not silently broaden generic smoke coverage.
- **Special surface test profile**: browser-fixture-coverage / system-auth-boundary.
- **Standard-native relief or required special coverage**: No UI component contract tests are required unless fixture implementation changes rendered UI, which is out of scope.
- **Reviewer handoff**: Confirm local/testing-only route guards where routes are added, command environment fail-closed behavior where commands are added or changed, safe redirect validation, platform/admin guard separation, workspace/environment entitlement, no production data dependency, and screenshot/report completeness.
- **Budget / baseline / trend impact**: One bounded browser smoke family may add browser-lane cost; record runtime in `artifacts/validation-report.md`.
- **Escalation needed**: document-in-feature. Escalate to follow-up-spec only if system auth fixture work requires a broader platform support-access decision.
- **Active feature PR close-out entry**: Smoke Coverage / Fixture Coverage.
- **Planned validation commands**:
- `git diff --check`
- `cd apps/platform && ./vendor/bin/pint --dirty` if PHP files change
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=AdminLocalSmokeLogin`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SystemPanel`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EvidenceSnapshot`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=RequiredPermissions`
- `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProviderConnection`
- targeted Pest Browser command for the Spec 376 fixture coverage test, if added.
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Evidence And Permission Surfaces Are Browser-Auditable (Priority: P1)
As a maintainer preparing a productization close-out audit, I want fixture-backed browser URLs for Evidence Snapshot View and Required Permissions so that evidence/permission surfaces are not merely repo-verified.
**Why this priority**: Spec 368 marked both surfaces P1 because they redirected to admin login in the available smoke context.
**Independent Test**: Generate or resolve a local/testing workspace, environment, admin user, evidence snapshot, and provider readiness context; visit both URLs through the smoke fixture and capture screenshots or exact blockers.
**Acceptance Scenarios**:
1. **Given** a local/testing fixture with workspace/environment membership and evidence view capability, **When** the browser opens the Evidence Snapshot View, **Then** the page renders without redirecting to `/admin/login`, a screenshot is stored, and route/auth/data inputs are documented.
2. **Given** a local/testing fixture with workspace/environment membership and provider readiness data, **When** the browser opens Required Permissions, **Then** the page renders without redirecting to `/admin/login`, a screenshot is stored, and the fixture context is documented.
3. **Given** a surface cannot be reached safely, **When** the browser attempt is recorded, **Then** the report classifies the exact blocker as auth-, scope-, data-, route-, or timeout-blocked and names the follow-up.
### User Story 2 - System Panel Surfaces Are Browser-Auditable Without Weakening Auth (Priority: P1)
As a platform maintainer, I want system dashboard and system operations browser coverage to use platform-plane auth only, so system panel screenshots prove the separate `/system` surface without creating a tenant-user shortcut.
**Why this priority**: Spec 368 could not score the system panel because `/system` and `/system/ops/runs` redirected to `/system/login`.
**Independent Test**: Create or reuse a local/testing platform user fixture with `platform.access_system_panel`, authenticate through a safe fixture path or documented test harness, and visit `/system` plus `/system/ops/runs`.
**Acceptance Scenarios**:
1. **Given** a local/testing platform user with required capabilities, **When** the browser opens `/system`, **Then** the dashboard renders without using the admin `web` guard and a screenshot is stored.
2. **Given** a local/testing platform user with required capabilities, **When** the browser opens `/system/ops/runs`, **Then** system operations renders or shows a meaningful empty state and a screenshot is stored.
3. **Given** the same fixture route is requested outside `local` or `testing`, **When** the route is invoked, **Then** it returns not found and does not authenticate any user.
### User Story 3 - Provider Connection Detail Has Stable Browser Evidence (Priority: P2)
As a maintainer reviewing provider readiness, I want Provider Connection Detail to open and capture reliably so that timeouts are separated from real UI defects.
**Why this priority**: Spec 368 browser-audited the provider connections list but the detail screenshot attempt timed out.
**Independent Test**: Resolve or create a local/testing provider connection fixture, open its detail page through scoped admin auth, and capture either the detail screenshot or exact timeout/blocker evidence.
**Acceptance Scenarios**:
1. **Given** a valid local/testing provider connection and authorized user, **When** the browser opens the detail URL, **Then** the page screenshot is captured and route/auth/data inputs are documented.
2. **Given** the page still times out, **When** the browser attempt finishes, **Then** the verification report records timeout-blocked status, final URL if known, console/JS state if available, and a follow-up recommendation without refactoring the UI.
## Functional Requirements
- **FR-376-001**: The implementation MUST create `artifacts/source-audit-summary.md` documenting Spec 368 blocked pages, relevant Spec 353 and Spec 370-375 input status, current route/auth/data/browser-evidence status, and remaining non-browser-verified surfaces.
- **FR-376-002**: The implementation MUST create `artifacts/fixture-design.md` with surface, route, auth guard, scope, data, existing fixture source, new fixture source if any, local/testing guarantee, browser URL, and failure mode for each in-scope surface.
- **FR-376-003**: The implementation MUST create `artifacts/fixture-coverage-matrix.md` with one row per in-scope surface and classifications for previous status, required fixture, implemented fixture, reachability result, screenshot, verification level, and remaining limitation.
- **FR-376-004**: The implementation MUST create `artifacts/route-reachability-report.md` listing route name, path, panel, middleware, auth guard, parameters, resolved fixture parameters, HTTP result, redirect result, final URL, and browser outcome.
- **FR-376-005**: The implementation MUST use existing admin local smoke-login and review/browser fixture patterns before adding new fixture code.
- **FR-376-006**: Any new smoke-login or fixture HTTP route MUST be available only in `local` and `testing`, return not found in all other environments, validate redirects against local app paths, and avoid secrets or real customer data. Any new or extended Artisan fixture command MUST be available only in `local` and `testing`, fail closed with a non-zero result outside those environments, and avoid secrets or real customer data.
- **FR-376-007**: System panel fixture work MUST authenticate `PlatformUser` through the `platform` guard and MUST NOT authenticate ordinary tenant users into `/system`.
- **FR-376-008**: The Evidence Snapshot fixture MUST use existing Spec 372-compatible browser evidence where sufficient, or a workspace/environment-authorized user with evidence view capability and a deterministic local/testing evidence snapshot, or document the exact blocker.
- **FR-376-009**: The Required Permissions fixture MUST use existing Spec 353/Spec 283-compatible browser evidence where sufficient, or a workspace/environment-authorized user and deterministic provider readiness/permission context, or document the exact blocker.
- **FR-376-010**: Provider Connection Detail fixture work MUST use scoped provider connection data, explicit `environment_id`/record-derived managed-environment context, and existing ProviderConnectionResource routes or document the exact route/data/timeout blocker.
- **FR-376-011**: Browser verification MUST attempt all five in-scope surfaces and create screenshots for reachable pages under `artifacts/screenshots/`; blocked pages require blocked screenshots when possible or explicit blocker notes.
- **FR-376-012**: The implementation MUST create `artifacts/browser-verification-report.md`, `artifacts/screenshot-index.md`, `artifacts/affected-files.md`, `artifacts/validation-report.md`, and `artifacts/follow-up-recommendations.md`.
- **FR-376-013**: The implementation MUST NOT intentionally change product UI layout, copy, action hierarchy, policies, Graph contracts, OperationRun semantics, migrations, models, or production runtime behavior outside local/testing fixtures.
- **FR-376-014**: All verification claims MUST use explicit levels: `repo-verified`, `browser-verified`, `fixture-backed`, `local-only`, `test-only`, `auth-blocked`, `scope-blocked`, `data-blocked`, `route-blocked`, `timeout-blocked`, `deferred`, or `not available`.
## Non-Functional Requirements
- **NFR-376-001**: Fixture data must be deterministic, minimal, and safe to recreate.
- **NFR-376-002**: Browser coverage must avoid broad page/product assertions; it proves reachability, no JS/console errors where reachable, and screenshot evidence.
- **NFR-376-003**: Production auth posture must remain unchanged. No fixture route may be production-accessible.
- **NFR-376-004**: Test setup must keep heavy browser cost explicit and opt-in.
- **NFR-376-005**: Reports must distinguish route truth, auth truth, data truth, browser screenshot truth, and operator follow-up truth.
## Out Of Scope
- Evidence Snapshot UI productization or evidence-generation logic.
- Required Permissions UI productization or permission calculation changes.
- System Dashboard/System Operations redesign.
- Provider Connection list/detail redesign, provider auth flow changes, provider health logic changes, or new provider behavior.
- New migrations, backfills, production fixtures, production smoke-login, or real customer data.
- UI bloat guard rule changes, final platform-wide browser re-audit, or screenshot diff infrastructure.
- Customer Review Workspace, Environment Review, Review Pack, Stored Report, OperationRun View, Backup Set View, Restore Run View, Operations Hub, Environment Dashboard, Baseline Profile View, or diagnostic entrypoint productization.
## Acceptance Criteria
- **AC1**: Evidence Snapshot View is backed by current browser evidence or captured through a local/testing fixture with screenshot; otherwise it is documented with an exact blocker and follow-up.
- **AC2**: Required Permissions is backed by current browser evidence or captured through a local/testing fixture with screenshot; otherwise it is documented with an exact blocker and follow-up.
- **AC3**: System Dashboard is browser-reachable through platform-plane browser session/local-testing auth and screenshot, or deferred with the exact system-auth gap.
- **AC4**: System Operations is browser-reachable through platform-plane browser session/local-testing auth and screenshot or meaningful empty-state screenshot, or blocked/deferred with exact reason.
- **AC5**: Provider Connection Detail is backed by current browser evidence or captured through explicit `environment_id` / record-derived authority; otherwise timeout, route, or data limitation is documented with final URL/state where available.
- **AC6**: Any new/changed fixture/auth route is local/testing-only, any new/changed fixture command fails closed outside approved environments, and both are redirect-safe, secret-free, not production-accessible, and not an RBAC bypass.
- **AC7**: No product UI refactor, production auth change, migration, model change, policy weakening, Graph change, or OperationRun behavior change is performed.
- **AC8**: All required artifacts and screenshot directory exist, even if some pages are documented as blocked.
- **AC9**: `git diff --check` passes; Pint and targeted tests are run if code changes, or limitations are documented.
## Assumptions
- Existing admin local smoke-login behavior remains the preferred admin fixture path.
- Existing Pest Browser support is available in this repo and should be reused for browser smoke.
- The system panel must remain a separate platform-auth plane.
- Existing Spec 353/372 admin-plane browser evidence is current repo truth and must be recorded instead of rediscovered as if absent.
- If a surface is unavailable because a route or required fixture does not exist, documenting the exact blocker is a valid outcome for v1.
## Open Questions
- None blocking preparation. During implementation, the agent must verify whether a system local/testing smoke-login route already exists or must be added as a narrow fixture.
## Follow-Up Spec Candidates
- Spec 377 - Post-Productization Browser Re-Audit & Closeout Gate v1.
- Provider Connection readiness/detail productization if screenshots reveal a product-level readiness gap.
- Evidence Snapshot customer/auditor productization if reachability exposes customer-safety issues.
- Browser scorecard integration with the UI bloat guard if repeated audits need automated aggregation.

View File

@ -0,0 +1,127 @@
# Tasks: Spec 376 - Browser Audit Fixture Coverage for Evidence/System Surfaces v1
**Input**: `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md`, `plan.md`, Spec 368 audit artifacts, Spec 353/372 browser evidence, Spec 375 follow-up recommendation, existing admin/system auth and browser fixture patterns.
**Tests**: Required for later implementation. Use Pest 4 Feature tests and Pest Browser. This spec does not authorize product UI redesign.
## Test Governance Checklist
- [x] Lane assignment is named and narrow: Feature tests for fixture/auth safety, Browser lane for five-surface smoke.
- [x] New or changed tests stay in the smallest honest family; broad platform browser audit is not added.
- [x] Workspace, environment, provider, evidence, platform-user, and session fixtures remain explicit and opt-in.
- [x] Planned validation commands cover fixture safety and target surfaces without pulling in unrelated suites.
- [x] Browser screenshots are required only for the five in-scope surfaces.
- [x] Any material browser runtime, timeout, or lane-cost note is recorded in `artifacts/validation-report.md`.
## Phase 1: Preparation And Repo Truth
**Purpose**: Confirm the current blockers and existing fixture/auth patterns before code changes.
- [x] T001 Re-read `specs/376-browser-audit-fixture-coverage-evidence-system-surfaces/spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`.
- [x] T002 Re-read Spec 368 inputs:
- `specs/368-platform-ui-signal-to-noise-browser-audit/audit.md`
- `specs/368-platform-ui-signal-to-noise-browser-audit/findings.md`
- `specs/368-platform-ui-signal-to-noise-browser-audit/page-scorecard.csv`
- `specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/raw/browser-notes.md`
- `specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/raw/routes.txt`
- [x] T003 Re-read current completed evidence for the in-scope admin surfaces, without modifying completed specs:
- `specs/353-provider-connections-resolution-guidance-v1/spec.md`
- `specs/353-provider-connections-resolution-guidance-v1/tasks.md`
- `specs/353-provider-connections-resolution-guidance-v1/artifacts/screenshots/...`
- `specs/372-customer-auditor-surface-safety-pass/artifacts/browser-verification-report.md`
- `specs/372-customer-auditor-surface-safety-pass/artifacts/screenshots/...`
- [x] T004 Re-read relevant Spec 370-375 artifacts and record unavailable artifacts as `not available`, without modifying completed specs.
- [x] T005 Inspect route truth with `cd apps/platform && ./vendor/bin/sail artisan route:list` or the closest available route-list command.
- [x] T006 Inspect existing admin smoke-login and fixture patterns in `apps/platform/routes/web.php`, `SeedReviewOutputBrowserFixture`, direct Browser `actingAs()`/workspace-session harnesses, Spec 353/372 browser tests, and their Feature tests.
- [x] T007 Inspect system auth separation in `SystemPanelProvider`, `PlatformUser`, `PlatformCapabilities`, `UseSystemSessionCookie`, `EnsurePlatformCapability`, existing system Browser `actingAs(..., 'platform')` usage, and system auth/access tests.
- [x] T008 Inspect existing Evidence Snapshot, Required Permissions, and Provider Connection route helpers/tests needed to resolve scoped URLs safely.
- [x] T009 Create `artifacts/source-audit-summary.md` with Spec 368 blockers, Spec 353/372 current browser evidence, related specs, route/auth/data status, fixture gaps, and selected implementation option.
- [x] T010 Create initial `artifacts/route-reachability-report.md` with route names, paths, middleware/auth guard, required parameters, current evidence source, and known redirect/login behavior.
## Phase 2: Fixture Design Before Implementation
**Purpose**: Make the fixture contract reviewable before adding code.
- [x] T011 Create `artifacts/fixture-design.md` with per-surface route, auth, scope, data, existing fixture source, new fixture source if needed, local/testing guarantee, browser URL, and failure mode.
- [x] T012 Create `artifacts/fixture-coverage-matrix.md` with rows for Evidence Snapshot View, Required Permissions, System Dashboard, System Operations, and Provider Connection Detail.
- [x] T013 Create `artifacts/affected-files.md` with planned files, purpose, change type, runtime/test/spec classification, surface, verification level, risk, and production impact.
- [x] T014 Create `artifacts/validation-report.md` with branch, HEAD, dirty state before implementation, planned commands, and no-product-UI-refactor assertion.
- [x] T015 Create `artifacts/screenshots/` and `artifacts/follow-up-recommendations.md` with placeholder sections for blocked surfaces, fixture gaps, UI productization follow-ups, final closeout audit readiness, and recommended next spec.
## Phase 3: Tests First - Fixture Safety
**Purpose**: Prove fixture routes and resolver behavior before relying on browser screenshots.
- [x] T016 Add or update focused Feature coverage proving existing admin smoke-login or direct Browser session fixtures can target the Evidence Snapshot View and Required Permissions fixture URLs while preserving workspace/environment context.
- [x] T017 If a system local/testing smoke fixture route is added, first add Feature coverage proving it returns 404 outside local/testing. *(N/A: no system smoke fixture route was added; existing platform-guard Pest Browser auth was sufficient.)*
- [x] T018 If a system local/testing smoke fixture route is added, add Feature coverage proving it authenticates only `PlatformUser` on the `platform` guard and never authenticates a tenant/admin `User` into `/system`. *(N/A: no system smoke fixture route was added; `SystemPanelAuthTest` and Spec 376 browser smoke cover platform guard access.)*
- [x] T019 If a system local/testing smoke fixture route is added, add Feature coverage proving `platform.access_system_panel` is required and missing capability remains forbidden for `/system`. *(N/A: no system smoke fixture route was added; existing `SystemPanelAuthTest` covers the capability boundary.)*
- [x] T020 If a system local/testing smoke fixture route is added, add Feature coverage proving redirect targets are limited to safe local app paths and external or cross-plane targets are rejected. *(N/A: no system smoke fixture route was added, so no new redirect surface exists.)*
- [x] T021 If an Artisan fixture command is added or extended, add coverage proving it fails closed outside local/testing and does not mutate data there. *(N/A: no Artisan fixture command was added or extended.)*
- [x] T022 Add or update focused fixture/resolver tests proving Evidence Snapshot fixture data belongs to the selected workspace/environment and unauthorized cross-scope data is not used, unless existing Spec 372 evidence is recorded as sufficient with no new fixture code. *(Existing `EvidenceSnapshotResourceTest` plus Spec 376 browser fixture prove scoped access; no product fixture resolver was added.)*
- [x] T023 Add or update focused fixture/resolver tests proving Required Permissions fixture data belongs to the selected workspace/environment/provider context, unless existing Spec 353/283 evidence is recorded as sufficient with no new fixture code. *(Existing `RequiredPermissionsAccessTest` plus Spec 376 seeded permission rows prove scoped route access; no product fixture resolver was added.)*
- [x] T024 Add or update focused fixture/resolver tests proving Provider Connection Detail fixture data is scoped to the selected workspace/provider authority, uses explicit `environment_id` or record-derived managed-environment authority, and does not depend on stale hidden environment state. *(Existing Spec 353 provider guidance tests plus Spec 376 browser URL with explicit `environment_id` prove the selected path.)*
## Phase 4: Minimal Fixture Implementation
**Purpose**: Implement only the narrow local/testing support required for browser reachability.
- [x] T025 Reuse existing `/admin/local/smoke-login` or direct Browser `actingAs()`/workspace-session patterns for admin-plane surfaces before adding new admin fixture routes.
- [x] T026 Reuse or extend existing review-output browser fixture setup or Spec 372-compatible Evidence Snapshot browser fixture setup if it already produces the required snapshot and route context.
- [x] T027 Reuse existing Required Permissions factories/provider readiness setup and Spec 353/283 evidence before adding new fixture config.
- [x] T028 Reuse existing Provider Connection factories/fixture setup and explicit `environment_id` URL helpers before adding new fixture config.
- [x] T029 If existing system Browser `actingAs(..., 'platform')` patterns cannot produce the required evidence and system browser ergonomics require it, add a local/testing-only system smoke fixture route guarded by `app()->environment(['local', 'testing'])`. *(N/A: existing system Browser `actingAs(..., 'platform')` produced the required evidence.)*
- [x] T030 If system fixture route is added, ensure it uses `auth('platform')`, `UseSystemSessionCookie`/system session semantics where needed, `PlatformUser`, and platform capabilities only. *(N/A: no system fixture route was added.)*
- [x] T031 Validate fixture route redirects centrally or locally with an allowlist of relative/admin/system paths; reject arbitrary URLs. *(N/A for system route; existing admin smoke-login redirect behavior was reused unchanged and remains covered by existing Feature tests.)*
- [x] T032 Ensure no production route, provider, policy, model, migration, Graph contract, OperationRun behavior, or product UI copy/layout changes are included.
## Phase 5: Browser Smoke And Screenshots
**Purpose**: Produce reproducible browser evidence or exact blockers.
- [x] T033 Add a bounded Pest Browser test under `apps/platform/tests/Browser/` for Spec 376 fixture coverage or document which existing browser tests provide current evidence for a surface.
- [x] T034 Browser-open Evidence Snapshot View through the local/testing fixture and save `artifacts/screenshots/001-evidence-snapshot-view.png`, or record existing Spec 372 screenshot evidence / blocked screenshot / note.
- [x] T035 Browser-open Required Permissions through the local/testing fixture and save `artifacts/screenshots/002-required-permissions.png`, or record existing Spec 353/283 screenshot evidence / blocked screenshot / note.
- [x] T036 Browser-open System Dashboard through platform-plane fixture auth and save `artifacts/screenshots/003-system-dashboard.png`, or blocked screenshot/note.
- [x] T037 Browser-open System Operations through platform-plane fixture auth and save `artifacts/screenshots/004-system-operations.png`, or blocked screenshot/note.
- [x] T038 Browser-open Provider Connection Detail through scoped admin fixture auth with explicit `environment_id` or record-derived managed-environment authority and save `artifacts/screenshots/005-provider-connection-detail.png`, or record existing Spec 353 screenshot evidence / blocked screenshot / note.
- [x] T039 For every reachable page, assert no JavaScript errors and no console logs using Pest Browser assertions.
- [x] T040 For every blocked page, record final URL, redirect/login path, blocker class, and whether a screenshot was captured. *(N/A: no in-scope page remained blocked after the passing browser smoke.)*
## Phase 6: Reports And Validation
**Purpose**: Close the feature with evidence, limitations, and no hidden implementation drift.
- [x] T041 Complete `artifacts/browser-verification-report.md` with URL, panel, fixture used, current evidence source, expected outcome, actual outcome, final URL, screenshot path, explicit FR-376-014 verification/blocker label, and notes for all surfaces.
- [x] T042 Complete `artifacts/screenshot-index.md` with screenshot path, reachable yes/no, blocked reason, and notes.
- [x] T043 Complete `artifacts/fixture-coverage-matrix.md` with implemented fixture, reachability result, verification level, and remaining limitation.
- [x] T044 Complete `artifacts/route-reachability-report.md` with final HTTP/browser outcomes.
- [x] T045 Complete `artifacts/affected-files.md` with actual changed files and production impact.
- [x] T046 Complete `artifacts/validation-report.md` with commands run, test/browser results, screenshots, limitations, dirty state after implementation, and whether closeout audit can proceed.
- [x] T047 Complete `artifacts/follow-up-recommendations.md` with any remaining blockers and recommended next spec, defaulting to Spec 377 - Post-Productization Browser Re-Audit & Closeout Gate v1 if no narrower blocker remains.
- [x] T048 Run `git diff --check`.
- [x] T049 If PHP files changed, run `cd apps/platform && ./vendor/bin/pint --dirty`.
- [x] T050 Run targeted Feature tests selected by changed files, including auth/system/evidence/required-permissions/provider coverage.
- [x] T051 Run the Spec 376 Pest Browser smoke or document the exact reason it cannot run locally.
## Non-Goals Checklist
- [x] NT001 Do not redesign Evidence Snapshot, Required Permissions, System Dashboard, System Operations, or Provider Connection Detail.
- [x] NT002 Do not add migrations, models, product persisted truth, product enum/status families, Graph contracts, jobs, policies, or OperationRun behavior.
- [x] NT003 Do not weaken production auth, add production smoke login, or authenticate tenant users into the system panel.
- [x] NT004 Do not create real customer data or depend on fragile hardcoded local IDs.
- [x] NT005 Do not change UI bloat guard rules or run a full platform-wide browser audit.
- [x] NT006 Do not rewrite completed historical specs or remove implementation close-out/validation/browser evidence.
## Dependencies And Execution Order
- Phase 1 must complete before fixture design.
- Phase 2 must complete before code edits.
- Phase 3 tests must precede or accompany fixture implementation.
- Phase 4 keeps implementation minimal and local/testing-only.
- Phase 5 produces browser evidence.
- Phase 6 validates and closes artifacts.
## Recommended Implementation Strategy
Start by inventorying current Spec 353, Spec 372, and Spec 283 browser evidence, then prove only remaining admin-plane gaps through existing Browser `actingAs()` / workspace-session patterns, `/admin/local/smoke-login`, and fixture seed commands. Handle system panel separately with platform guard semantics; only add a system smoke-login fixture if Pest Browser cannot reliably use existing `actingAs($platformUser, 'platform')` patterns for screenshots. Treat any UI/product findings discovered during screenshots as follow-up recommendations, not in-scope fixes.