From d1b8bff5ce22557e1b1373d6461f5b221095bc9a Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 30 Sep 2026 07:49:56 +1000 Subject: [PATCH] docs(development): decide the dashboard test harness --- docs/data/generated/dev-docs.json | 2 +- docs/development/frontend-ui.md | 44 +++++++++++++++++++++++++++++++ 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index e310e5f42..5b6352e21 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -130,7 +130,7 @@ "url": "/dev/development/frontend-ui/", "title": "Frontend UI", "section": "Development", - "body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n6. For a new live topic, add one process-wide producer to `internal/webui`'s\n `RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`\n starts the producers with the process context. Never create an upstream\n watch or poller in an HTTP handler. A slow client must reconnect for cursor\n and snapshot repair rather than silently lose an update. Prove the producer\n with several browser clients against the real peer, not just a scripted\n stream; `live_hub_test.go` is the example.\n" + "body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Testing the dashboard\n\nAuthority: the runner itself is `ui/package.json`'s `test` script: `node --test\n--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs\npure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,\nno second dependency beyond what the app already carries. That is the standard,\nand a decision record for when it is deliberately not enough:\n\n- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,\n draft state, copy conditions, filters and payload building live in plain\n `.ts` files beside the components and are tested in `ui/test/`. Components\n stay thin, so there is normally nothing in an SFC that is archie logic.\n- **Installed primitives are upstream-tested, not re-tested here.**\n `reka-ui` (2.10.5 here) maintains colocated tests per component in its own\n repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the\n arrow-navigation composables). The npm package ships none of those files, so\n this coverage is inherited through the version bound, not the tarball —\n `grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local\n mount tests would test a dependency.\n- **A `.vue` import cannot run under the module runner.** `node --test` fails\n such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no\n built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is\n therefore a broken test, not a weak one.\n- **If a DOM mount harness is ever needed** (a page-level accessibility\n contract, cross-component interaction, focus behaviour): `happy-dom` +\n `@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the\n module runner for everything else. Measured on the ui tree (vitest 5.0.2,\n happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level\n `node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount\n suite (role=radiogroup vs role=switch, aria-label, click activation against\n the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and\n `vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner\n alternative (absorbing the existing suite into vitest) was measured\n infeasible as-is: all 29 existing files import `node:test`, which vitest\n cannot collect (\"No test suite found in file\" for every one), so it would be\n a rewrite of the whole suite, and its runtime was not measured. Nothing in\n `ui/dist` or CI changes either way; happy-dom is pure JS, no browser binary.\n- **What the module standard does not verify:** whether a call site passes an\n `aria-label` or which `v-if` branch shows. Those live in SFC templates and\n are only visible with a mount. If a page's accessible-name wiring is the\n risk, say so in the page's task and reach for the harness decision above\n rather than quietly growing mount tests. Never suppress a lint rule or a\n test to keep SFC behaviour out of the gate.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n6. For a new live topic, add one process-wide producer to `internal/webui`'s\n `RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`\n starts the producers with the process context. Never create an upstream\n watch or poller in an HTTP handler. A slow client must reconnect for cursor\n and snapshot repair rather than silently lose an update. Prove the producer\n with several browser clients against the real peer, not just a scripted\n stream; `live_hub_test.go` is the example.\n" }, { "url": "/dev/development/merging-work/", diff --git a/docs/development/frontend-ui.md b/docs/development/frontend-ui.md index ce0fb9812..110f3efab 100644 --- a/docs/development/frontend-ui.md +++ b/docs/development/frontend-ui.md @@ -31,6 +31,50 @@ should look. after visiting Settings and Logs: the UI process serves HTTP/1.1 and six persistent streams can starve every later browser request. +## Testing the dashboard + +Authority: the runner itself is `ui/package.json`'s `test` script: `node --test +--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs +pure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM, +no second dependency beyond what the app already carries. That is the standard, +and a decision record for when it is deliberately not enough: + +- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes, + draft state, copy conditions, filters and payload building live in plain + `.ts` files beside the components and are tested in `ui/test/`. Components + stay thin, so there is normally nothing in an SFC that is archie logic. +- **Installed primitives are upstream-tested, not re-tested here.** + `reka-ui` (2.10.5 here) maintains colocated tests per component in its own + repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the + arrow-navigation composables). The npm package ships none of those files, so + this coverage is inherited through the version bound, not the tarball — + `grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local + mount tests would test a dependency. +- **A `.vue` import cannot run under the module runner.** `node --test` fails + such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no + built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is + therefore a broken test, not a weak one. +- **If a DOM mount harness is ever needed** (a page-level accessibility + contract, cross-component interaction, focus behaviour): `happy-dom` + + `@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the + module runner for everything else. Measured on the ui tree (vitest 5.0.2, + happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level + `node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount + suite (role=radiogroup vs role=switch, aria-label, click activation against + the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and + `vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner + alternative (absorbing the existing suite into vitest) was measured + infeasible as-is: all 29 existing files import `node:test`, which vitest + cannot collect ("No test suite found in file" for every one), so it would be + a rewrite of the whole suite, and its runtime was not measured. Nothing in + `ui/dist` or CI changes either way; happy-dom is pure JS, no browser binary. +- **What the module standard does not verify:** whether a call site passes an + `aria-label` or which `v-if` branch shows. Those live in SFC templates and + are only visible with a mount. If a page's accessible-name wiring is the + risk, say so in the page's task and reach for the harness decision above + rather than quietly growing mount tests. Never suppress a lint rule or a + test to keep SFC behaviour out of the gate. + ## Adding an API route 1. The handler goes in the `internal/webui/api_.go` file for its