Report Viewer E2E Specs
The e2e report viewer (app/acceptance/report_viewer/) has grown into a
complicated application in its own right, so it needs its own end-to-end
test suite — separate from the main Meadow e2e tests in
app/acceptance/e2e/tests/.
When invoked, the user wants to either add a new spec, run the existing suite, or fix a bug a spec exposed. Use this skill to establish shared context, then follow the user's specific ask.
Where everything lives
app/acceptance/report_viewer/
├── e2e/
│ ├── playwright.config.ts # two-entry webServer (express + vite)
│ ├── fixtures/
│ │ └── publish-flow-fixture.ts # ensurePublishFlowArtifact()
│ ├── pages/
│ │ ├── TickNavComponent.ts # navigate to a specific tick
│ │ └── MeadowHomeFilesComponent.ts # Files-tab assertions
│ └── tests/
│ └── *.spec.ts # one spec per file
├── tsconfig.e2e.json # separate tsconfig for e2e/
└── package.json # has "e2e" and "e2e:install" scriptsPage object pattern
Specs should be thin. DOM selectors and interaction sequences belong in
page-object components under e2e/pages/, mirroring the convention used
by the main e2e suite (see
app/acceptance/e2e/src/run/pages/BundleEditorPage/components/FilterPanelComponent.ts
for the reference).
- One class per logical area of the UI (a tab, a panel, a modal).
- Constructor takes
(page: Page, expect: Expect). - Private getters for reusable locators, public
asyncmethods for actions and assertions. - Prefer stable
data-*attribute selectors over structural CSS. The ScenarioViewer already exposesdata-idx,data-tick-index,data-file-path, anddata-file-status; add more when a new spec needs a stable hook rather than relying on class names or text content.
Existing components:
TickNavComponent.goToTick(n)— 1-indexed tick navigation via the header dropdown. Throws if the tick isn't in the dropdown.MeadowHomeFilesComponent.activate()/fileEntry(path)/expectFileNotModified(path)/expectFileCommitted(path)/getFileStatus(path). PreferexpectFileCommittedwhen the intent is "this file should have been committed by the app" — it covers bothuncommitted-newanduncommitted-modified. UseexpectFileNotModifiedwhen the tighter "shouldn't have local edits" assertion is what you want.
How to run the suite
cd app/acceptance/report_viewer
# First time only (or after package-lock changes):
npm install
npm run e2e:install # installs chromium
# Run the suite:
npm run e2e
# Run a single spec:
npm run e2e -- tests/sanity.spec.ts
# Run with UI / headed mode for debugging:
npm run e2e -- --headedFirst-run cost. The very first run builds the cached publish-flow
fixture, which shells out to the main test-runner CLI and actually runs
publish-flow.spec.ts (Docker containers, MinIO, any extension backing
services, the works). Expect it to take a couple of minutes. Subsequent
runs reuse the cache and are fast.
Port isolation. The e2e suite runs on dedicated ports 3556 (server)
and 5275 (client) — NOT the /dev defaults of 3456/5175. This is
deliberate so the suite works regardless of what dev servers other
worktrees are running. The server and vite configs accept
REPORT_VIEWER_PORT and REPORT_VIEWER_CLIENT_PORT env vars (defaults
preserved for /dev); e2e/playwright.config.ts sets them for its
webServer subprocesses and uses reuseExistingServer: false.
The cached publish-flow fixture
All specs share a single fixture: the artifact directory produced by running
app/acceptance/e2e/tests/publish-flow.spec.ts.
- Builder:
app/acceptance/report_viewer/e2e/fixtures/publish-flow-fixture.ts— exportsensurePublishFlowArtifact()which returns{ runId, testSlug, artifactDir }. - Cache key: SHA-256 of
publish-flow.spec.tscontents (first 12 chars). - Stable run id:
rv-fixture-<key>. - Location:
~/meadow-e2e-artifacts/current/rv-fixture-<key>/publish-flow-uploads-files-to-minio/(lives under the standard artifacts root so the report viewer server can read it with no extra plumbing). - Validation: the fixture is considered present iff
status.txtin the test slug dir sayspassed. - How it rebuilds: shells out to
npx tsx src/cli.ts --run-id <stableId> --grep "Publish flow"insideapp/acceptance/e2e/. Assumes test-runner deps are already installed (quickcheck does this). It bypassesslowcheck.shto avoid thenpm install --forceon every invocation. - Invalidation: content-hash of the spec file only. Changes to the
spec's dependencies do NOT invalidate the cache. If you know a dependency
changed in a way that affects the fixture, manually delete the
rv-fixture-*directory:rm -rf ~/meadow-e2e-artifacts/current/rv-fixture-*
Per-spec pattern
import { test, expect } from "@playwright/test";
import {
ensurePublishFlowArtifact,
type PublishFlowFixture,
} from "../fixtures/publish-flow-fixture.js";
let fixture: PublishFlowFixture;
test.beforeAll(() => {
fixture = ensurePublishFlowArtifact();
});
test("...", async ({ page, request }) => {
const { runId, testSlug } = fixture;
// API-level assertions: await request.get(`/api/${runId}/${testSlug}/...`)
// UI-level assertions: await page.goto(`/${runId}/${testSlug}`)
});One test per file. Reuse the cached fixture. Prefer a cheap API-level sanity check before the UI assertions — it produces a clearer failure message if the fixture is malformed.
UI assertion gotchas
Tick X/Y:counter is hidden until a tick is selected. On initial scenario load,ScenarioViewerrendersTick: --(dash) until the user scrubs the video or picks a tick from the dropdown. Don't assert on theX/Ytext unless your test first selects a tick.- Check
hasTicksvia the dropdown button. The tick dropdown button is present wheneverhasTicks=true, sopage.getByRole("button", { name: /^Tick/ })is a reliable way to prove the client saw ticks in the manifest. - Breadcrumb as a load indicator.
page.getByText(testSlug)being visible is a simple proof that the SPA router mountedScenarioViewerfor the target artifact.
Useful report-viewer server endpoints
(Served by app/acceptance/report_viewer/src/server/index.ts on port 3456,
proxied through Vite at 5175.)
GET /api/:runId/:testSlug/manifest— full manifest, includesticks: ProcessedTick[]GET /api/:runId/:testSlug/snapshots— MeadowHome commit snapshotsGET /api/:runId/:testSlug/minio-snapshots— S3/MinIO snapshotsGET /api/:runId/:testSlug/state-repos— extension-contributed state repos with their rendering meta (display name, key map, etc.)GET /api/:runId/:testSlug/state-snapshots/:repoName— snapshots for a named state repoGET /api/:runId/:testSlug/state-snapshot/:repoName/:hash— table contents at a state-repo commit
The client route for a scenario is /:runId/:testSlug, rendered by
ScenarioViewer.tsx.
Notable facts about the artifact
For the current publish-flow.spec.ts, the test slug is
publish-flow-uploads-files-to-minio (derived as
title.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase()). If the test title
ever changes, update PUBLISH_FLOW_TEST_SLUG in
publish-flow-fixture.ts.
After adding a spec
- Run
npm run e2einapp/acceptance/report_viewer/and confirm it passes. - Run
./quickcheckfrom the repo root (per project AGENTS.md). If changes are limited toapp/acceptance/, the scoped check is faster:
Quickcheck type-checks the e2e/ directory viacd app/acceptance && _module/scripts/quickchecktsconfig.e2e.jsonbut does NOT run the Playwright tests — those are opt-in vianpm run e2e.
Fixing bugs exposed by a spec (the fix → regenerate → verify loop)
Many specs in this suite are intentionally written to fail first —
they are tripwires pointing at real bugs in the Meadow app (e.g.
"app/app_config.yaml should not be marked modified at tick 2"). When
the user asks to fix the underlying bug, use this tight loop:
- Diagnose at the right layer. The report viewer just renders what
manifest.jsontells it (assembled from the run's tick log, which is dropped after assembly). If a file is reported as modified/new/etc., check:- First, read the live home's real
git statusat teardown from~/meadow-e2e-artifacts/current/<runId>/<testSlug>/meadowHome-final-status.txt. The savedmeadowHome-state-repoholds only.git: its history, plus the final working tree as the commitrefs/meadow-e2e/final-worktree(git show refs/meadow-e2e/final-worktree:<path>). If git itself agrees with the tick data, the bug is NOT infast_git_opsor the report viewer — it's upstream in the Meadow app (some code path writes to the file without committing). - If git disagrees, the bug is in
fast_git_ops(seeapp/runtime/native/fast_git_ops/fast_git_ops_code/src/main.rs) or in howtest-fixtures.tsconsumes its output.
- First, read the live home's real
- Fix at the source. For "file written but not committed" bugs,
the typical fix location is
app/runtime/service/src/index.ts startServer()where init helpers likeensureAppConfigInitializedrun. Have the init helper report whether it patched the file, and commit when it did — not only on first creation. See the existingensureAppConfigInitialized/ensureResourcesConfigInitializedpattern for reference. - Invalidate the cached fixture. The fixture builder only
rebuilds when the spec file's content hash changes, so after an app
fix you must manually clear the cache:
rm -rf ~/meadow-e2e-artifacts/current/rv-fixture-* - Regenerate + verify. Run
npm run e2einapp/acceptance/report_viewer/. The fixture builder will rerunpublish-flow.spec.ts(slow, ~20s) to produce a fresh artifact, then Playwright runs every spec against it. Confirm the target spec flips from red to green — and that no other spec regresses. - Run
./quickcheckfrom the repo root to catch any type or lint fallout from the app-side fix. - Repeat if the spec is still red — the fix wasn't sufficient, or the bug lives somewhere else than you thought. The cycle is cheap because step 3 is one command and step 4 is automated.
Cache key caveat. The fixture cache key is a hash of
publish-flow.spec.ts alone — it does NOT invalidate when the Meadow
app code changes. That's why step 3 is mandatory for app-side fixes.
Adjacent-bug heuristic. When you fix one "written but not committed" bug, look at the same startup sequence for sibling bugs in the same family, then have the user decide whether to add sibling specs before or after the fix. Writing the failing spec first is valuable because it proves the tripwire works.
Flakiness policy
Per project AGENTS.md: flaky tests are never acceptable. If a spec fails sometimes and passes sometimes, fix the root cause — don't retry it away. An intentionally failing regression spec (tripwire for an unfixed bug) is NOT flakiness — it's a controlled, deterministic failure that should stay red until the underlying bug is fixed. Don't silence or skip such specs; the failure is the signal.