Portal Frontend QA Scenarios

Portal Frontend QA Scenarios

This document is the source scenario matrix for portal UI checks. It covers the frontend states an agent is expected to verify before calling a portal change done. Web output is evidence only; source tests and screenshots are the contract.

Scope

• Target app: https://portal.yamon.io
• Source repository: yamonco/fractalops-frontend
• High-risk pages: project overview, assets, agents, studio, operations, evidence, access, project index, public routes, proposal/review routes.
• Required viewport set: desktop 1440x1100, mobile 390x1000.
• Required session state: authenticated portal operator account when checking private project routes.

Local Gates

Run from fractalops-frontend before a commit:

pnpm lint:frontend
pnpm portal:check
pnpm portal:build
pnpm --dir portal exec vitest run src/components/organisms/ProtectedRegistryUiUx.test.ts

Run from fractalops/docs after this document changes:

pnpm run check
pnpm run build

Link And Button Contract

Every visible button-like control must satisfy one of these shapes:

Shape	Contract	Failure example
route link	href points to a real route, hash target, or external URL	`href={item.url
modal/workbench opener	button type="button" has a bound data-* opener and a mounted listener	data-open-project-workbench="package-hub" without a matching workbench listener
mutation/action button	button type="button" has a real handler and busy/disabled state	enabled button with no handler
disabled placeholder	disabled or aria-disabled="true" with no fake link target	fake anchor using # when data is missing
external link	target="_blank" plus rel="noreferrer"	external href without rel

Section hashes are allowed only when the target element exists in the same rendered page. A placeholder hash is not allowed. If source data lacks a URL, render a read-only row or disabled button instead of an anchor.

Scenario Matrix

ID	Route	Action surface	Expected result	Evidence
PQA-001	/projects	New project, launch-ready filter, favorites filter, Agent studio link	Buttons filter or open the mounted project factory; no dead button	Playwright desktop/mobile screenshot + console clean
PQA-002	/projects/{slug}	Project rail, overview panels, action chips	All child nav links resolve without horizontal overflow	Playwright screenshot + selector counts
PQA-003	/projects/{slug}/assets	Repository, Topology, Packages, Studio, Access buttons	Repository/Topology open workbenches, Packages scrolls to package hub, Studio/Access route correctly	data-project-assets-lanes, no table in repository summary
PQA-004	/projects/{slug}/assets	Repository binding rows	GitHub opens only with repo URL; Branch/Daytona opens branch dialog; Edit opens binding workbench	data-project-repository-binding-row count matches bindings
PQA-005	/projects/{slug}/assets	Asset lane cards	No `href
PQA-006	/projects/{slug}/agents	AgentSquad delivery rail	Metrics include Agents, Workspace, Heartbeat, Handoffs, Lineage, Proof, Tools, Blockers	data-agent-squad-runtime-metrics and Heartbeat text
PQA-007	/projects/{slug}/agents	Runtime control panel	Launch path and command deck route to Studio workbench hash; disabled controls explain unavailable state	data-agent-squad-launch-route and data-agent-squad-command-route
PQA-008	/projects/{slug}/studio	Workbench tabs and dialogs	Launch/config/agents/template/session controls render with no duplicate inactive modal	tab selector + console clean
PQA-009	/projects/{slug}/operations	Operations runtime metrics and recovery links	runtime metrics match Agents surface; Studio launch path is stable	selector parity with Agents
PQA-010	/review/* and /proposals/*	proposal actions and proof/detail links	derived proposal keys never generate broken /proposals/ links	static source scan + route smoke
PQA-011	/public/routes	public route catalog	public links are available without private session	unauthenticated Playwright smoke
PQA-012	external native tools	DataHub, ClickHouse, Daytona, GitHub, preview links	external links include target="_blank" and rel="noreferrer"	static source scan

Live Sweep Script Shape

Use Playwright CLI or Node Playwright. Store artifacts under output/playwright/<run-key>/.

Required checks for each page:

• HTTP status is 200 or an intentional redirect for login-gated public entry.
• document.title matches the route identity.
• document.body.innerText is not blank and contains page-specific labels.
• overflowX is 0.
• console errors, page errors, and request failures are empty.
• expected selectors exist.
• visible anchors have non-empty href.
• no anchor uses a placeholder # unless it targets an in-page section that exists.

Current Proof Points

The latest portal asset/runtime cleanup used these selectors:

[data-project-assets-summary]
[data-project-assets-metrics]
[data-project-asset-lane]
[data-project-repository-binding-summary]
[data-project-repository-binding-row]
[data-project-topology-summary]
[data-project-asset-studio-card]
[data-project-proof-assets]
[data-agent-squad-runtime-metrics]

The evidence artifact pattern is:

output/playwright/live-project-assets-runtime-<commit>/
output/playwright/live-project-assets-runtime-<commit>-recheck/

Completion Gate

A portal frontend change is done only when:

1. scenario docs are updated when the tested surface changes;
2. static tests reject fake links, unbound workbench openers, and local CSS overrides for the touched surface;
3. pnpm lint:frontend, pnpm portal:check, and pnpm portal:build pass;
4. live Playwright screenshots cover desktop and mobile for every touched private route;
5. GitHub Actions and the selected production deploy workflow are green.