@boopkit/cap-web 0.5.6 → 0.5.8

package/skills/boop-web-testing/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: boop-web-testing
+description: "When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes — or to confirm in a browser that a change to something a person looks at does what its issue said, since a green suite proves behaviour but not what renders."
+metadata:
+  category: test
+---
+> **Read `PROJECT.md`, beside this file, first.**
+> It records how this project applies the guidance below, and where it deliberately differs.
+> Where the two conflict, `PROJECT.md` wins.
+> Record project-specific rules there, never in this file.
+
+# Testing: Express App (Web & APIs)
+
+
+Parent skill: `boop-testing-testing` (philosophy, generic approach)
+
+---
+
+## Running Tests
+
+```bash
+npm test                                                    # Full suite
+npx jest tests/services/foo.test.ts --no-coverage           # Single file
+npx jest tests/services/foo --no-coverage                   # Pattern match
+npx jest tests/services/foo.test.ts -t "handles replay"     # By test name
+```
+
+The focused forms are safe to reach for: the concurrency and per-worker memory settings live in `jest.config.js`, not in the `test` script, so `npx jest <path>` runs under the same settings the full suite does. Which of these you should be running on a given piece of work is a separate question — see "Which tests to run, and when" in the parent skill.
+
+**Prerequisites**: integration tests run against the project's real backing services rather than mocks, so whatever the app talks to at runtime — the database first of all — has to be reachable from the machine running the tests. Which services those are depends on the capabilities the project has installed; its README and environment template are the authority.
+
+## Test File Layout
+
+```
+tests/
+  helpers/                          # shared setup, factories, harnesses (see below)
+  services/
+    foo.test.ts                     # Unit tests (mocked deps)
+    foo.integration.test.ts         # Integration tests (real services)
+  controllers/
+    itemsAPI.test.ts                # HTTP route tests
+  middleware/
+  utils/
+```
+
+- `.test.ts` for Jest auto-discovery. Keep the mocked tests and the real-service tests for the same subject in **separate files**: `jest.mock` is hoisted above the imports and applies to every test in the module, so one file cannot both stub a dependency and exercise the real one. `.integration.test.ts` is the conventional name for the half that uses the real services.
+- Group by domain: `services/`, `controllers/`, `middleware/`
+
+## Test Helpers
+
+Shared test setup belongs in one place under `tests/`, not re-derived in each spec file: booting the app, creating the entities a test needs and tearing them down again, and harnesses that make an awkward dependency — a broker, a queue, a rendered template — drivable from a test.
+
+**Read what the project already has before you write one.** These helpers are not scaffolded and cannot be, because they follow whichever capabilities and domain the project has. Every project grows its own set, and the shape varies from one shared module to a directory of purpose-built ones. Reuse what fits and extend it, rather than starting a private copy inside your test file. A helper used by exactly one test is not a helper — leave it in the test.
+
+When you do add one, keep two properties. A factory returns a real, persisted entity rather than a hand-built object literal, so the test exercises the same shape production does. And whatever creates data owns its teardown, so one failed run does not poison the next.
+
+## Integration Test Data Isolation
+
+Integration tests share their backing services with every other integration test, and with whatever the last run left behind. Three habits keep them from interfering with each other:
+
+- **Namespace whatever you create.** A per-run prefix (`_test/${Date.now()}`, a UUID) keeps parallel runs and repeat runs from colliding on unique constraints.
+- **Track created records and remove them in `afterAll`**, each cleanup wrapped in its own `try/catch` so one failure doesn't strand the rest.
+- **Scope instead of deleting where deletes are expensive.** Some stores — append-only logs, analytics columnstores, anything with asynchronous merge semantics — make row deletion slow or eventually-consistent. Isolate those by writing under a test-specific tenant or key and leave the rows in place.
+
+## HTTP Route Tests
+Test Express routes via **real HTTP requests** (`fetch()`) against a running local server. This exercises the full middleware chain (auth → controller → service → DB → response).
+
+Why real HTTP over supertest: supertest skips TCP/listen and can mask middleware ordering or config bugs. Auth middleware is a critical path worth testing through, not around.
+
+**Setup:**
+```typescript
+const BASE_URL = process.env.TEST_BASE_URL || 'http://localhost:3000';
+const TEST_API_KEY = process.env.TEST_API_KEY; // however this project issues API keys
+const authHeaders = { 'Authorization': `Bearer ${TEST_API_KEY}`, 'Content-Type': 'application/json' };
+```
+
+**What to cover:** auth rejection (401/403), request validation (400), the happy-path response shape, and the authorization boundary — that one account cannot reach another's data. If the project gates routes on anything further (feature flags, roles, plan tiers), cover the closed gate too, and assert the status code it actually returns rather than the one that seems right.
+
+**Prereqs:** a local server running against a reachable database, a durable test account, and whatever credential the auth middleware expects (`TEST_API_KEY` by convention).
+
+## Ad-Hoc Testing Tools
+
+Jest is what runs in CI and before a commit. Alongside it, projects grow small CLIs for the things a test suite is the wrong shape for: generating fixture data, poking a live local server, checking what actually landed in the database.
+
+Boop scaffolds one — `npm run db:query` (database capability) — for reading the local database without opening Prisma Studio. Anything beyond that is project-grown; `package.json` scripts and `src/scripts/` are where to look for what yours has, and `--help` on each is faster than reading its source.
+
+These are exploratory aids. They are not part of the automated suite, and none of them substitutes for a Jest test that can go red on its own.
+
+## Verifying a change someone will look at
+
+When a change alters something a person looks at, such as a page, a form, a list, an empty state or a message, finish by driving it in a browser against seeded data.
+**A passing suite proves the behaviour. Only the rendered page proves that a person can reach it.**
+
+A change can be correct and still fail the person it was built for.
+A confirmation renders six screens below the fold; an error appears at the bottom of a form while the reader looks at the top; a button's label does not say what it does; a control lands on the wrong one of two pages.
+In each, the code does what it should and its test passes, because a test asserts that the confirmation renders and none asserts where on the page it lands.
+In one downstream project a change shipped with over eight thousand passing tests and a clean typecheck, and twenty minutes of driving it found a P1: the confirmation that was the only defence against a repeated submit rendered more than four thousand pixels down the page, so the reader saw a form redisplay unchanged and pressed submit again.
+
+So the question here is not whether it works, which the suite answered, but **whether the person this is for would get what the issue promised.**
+Get the suite green first, or you will spend the session diagnosing a failure a test would have named in seconds.
+This is no substitute for tests, and it does not re-prove logic a unit test already covers.
+
+### The rendered page is the authority for what a page shows
+
+Before you say a surface works or is broken, sign in as the person it is for and render it.
+A database query and a code trace each describe something next to the page, not the page.
+In the same project, a query found the value a fix had written and the fix was called done, while the view read a different, empty field and still showed the old text; a later fix was then called broken from a code trace, and the render showed it worked.
+
+- Verify the broad claim the change makes across the whole surface, not only the row you changed.
+- Before handing to the operator, ask what they would catch on it, and go and find that first.
+- A sub-agent's "verified on real data" is a lead to check, not a verdict.
+
+A surface you are making no claim about needs no render.
+
+### Stand up an environment with the states the surface will meet
+
+- **Never the shared development database or a deployed environment.**
+  Use a throwaway database and a server started from the worktree whose code you are verifying.
+  A server running another checkout's code produces a page that looks plausible and is wrong, so confirm the server process's working directory is your worktree.
+- **Rebuild the compiled stylesheet first.**
+  It is usually gitignored, so a fresh worktree lacks it or holds a build from before the branch's CSS, and nothing warns you: the page still renders, and you judge a layout you did not ship.
+- **Seed the variety of states.**
+  A fault that shows only in an empty, single, partial, finished or failed state is invisible while the database holds one well-formed example.
+  Reuse a seed the project already has that writes those states.
+  When a feature brings a new kind of list, roster, directory or inbox, scope a seed-data spec beside the feature spec, naming the permutations it must write; the two can run as parallel loops, neither gating the other, so the feature develops against the seed and exposes shapes the seed missed.
+- **Run the background workers the pages depend on.**
+  A web process alone leaves the jobs a page waits on sitting in their queue, and the page eventually reports a failure that nothing logs as an error.
+
+### Drive it
+
+Use the browser tools against the real pages: read the page, fill the real inputs, press the real buttons.
+A bare HTTP request to the route is not a check of the surface, because what renders is the thing under test.
+Walk the issue's Done-when one line at a time, and for each ask what a person would see, not whether the write happened.
+
+These traps each cost a downstream session time:
+
+- **Page-text extraction reports screen-reader-only text as if it were visible.**
+  Confirm anything you rely on with a screenshot or by measuring the element.
+- **Presence is not position.**
+  When something must catch the reader's attention, such as a confirmation, an error or a warning, measure where it lands rather than confirming it exists:
+  ```js
+  const r = el.getBoundingClientRect();
+  ({ top: Math.round(r.top), aboveFold: r.top < window.innerHeight })
+  ```
+- **A Chromium capture can miss a mobile overflow caused by a native form control.**
+  Chromium shrinks a `<select>` with long options; Safari sizes it to its longest option, so a picker that fitted 390px and 320px captures overflowed on an iPhone.
+  Where `<select>`, date or file inputs sit in a narrow layout, reason about the layout's structure, prefer fixes that hold in any browser (`min-width: 0` on flex children, a column layout, `max-width: 100%`), and have the change confirmed on a real device.
+- **`:focus` did not match under a headless Playwright probe**, measured once: a focused input read back its unfocused border colour, including one whose focus rule had worked for months.
+  Read focus and hover rules from the compiled stylesheet instead, and compare any probe with a sibling known to work, so that a false result shows itself.
+- **The seed may not hold the case you need.**
+  Rather than hunting for a record that happens to match, change one you control so that it does; that tests your change and the path beneath it in one move.
+
+### Judge what you see
+
+Once a flow works, whether it reads well is a separate judgement.
+When the project has the ux capability, run `boop-ux-purpose-judgement` for whether each thing on the page belongs there, then `boop-ux-visual-judgement` for how it looks and scans.
+
+- **Read each page, message or notification as its recipient would:** addressed to its reader, warm and professional, free of internal identifiers and jargon, and carrying nothing that reader should not see, such as the operator's budget.
+  Wording that confuses you will confuse the person it is for.
+- **When a count or a set appears on more than one surface**, such as a badge in the navigation, a summary on a hub and the rows of a list, put the surfaces side by side.
+  A difference between them is the defect, and comparing them finds what a test of one surface cannot.
+- **When the page and the data could disagree, look at the data** with the project's query tool (`npm run db:query` above).
+  A row that repeats one value five times is either a rendering fault or a storage fault, and the two have different owners, so establish which before you file it.
+
+### Record and tear down
+
+**Findings are observations, not commits.**
+Capture what you saw and file it; do not start fixing mid-run, because editing the code restarts the server and destroys the state you are standing in.
+
+File each finding as its own issue, saying what the person sees, why it matters, and what good looks like.
+Put a finding caused by the work under test beneath that work's epic, and file a pre-existing one standalone, saying in its body how you established it was not this branch: a seed fault blamed on the branch sends the next person to the wrong code.
+
+Then stop the server you started and drop the throwaway database, and confirm that the port is free and the database is gone rather than assuming the teardown worked.
+
+## References
+
+- `boop-testing-testing` — testing philosophy and the generic approach
+- `boop-testing-tdd-light` — the red/green loop for a single change
+- The project's own shared test setup under `tests/` — read it before adding another helper
+- `jest.config.js` at the project root — test discovery, transform, and match config

package/skills/boop-web-web-ui-design/SKILL.md

@@ -11,7 +11,7 @@ metadata:
 
 # Web UI Design Principles
 
-For controller design (the code that handles requests and renders views), apply the core principles in `design.controllers.skill.md` from the `services` capability: thin dispatch, no business logic in controllers, services handle the work. This skill adds web-specific guidance on top: view rendering, template structure, CSS patterns.
+For controller design (the code that handles requests and renders views), apply the core principles in `design.controllers.skill.md` from the `services` capability: thin dispatch, no business logic in controllers, services handle the work. This skill adds web-specific guidance on top: view rendering, template structure and markup patterns.
 
 ## Core Philosophy
 When building UI components, align with the **Spartan Code Philosophy** (see `boop-coding-development`):
@@ -20,44 +20,15 @@ When building UI components, align with the **Spartan Code Philosophy** (see `bo
 - Resist adding extra styling, animations, or features beyond what's requested
 - If additional UI enhancements seem beneficial, discuss with the team first
 
-## Semantic CSS Approach
-We use **semantic CSS classes** that describe the purpose of elements rather than their appearance:
+## CSS
+Before you add or change a class, a selector or a stylesheet rule, read [`boop-web-css`](../boop-web-css/SKILL.md).
+It states how classes are named and nested, rules out BEM, and says when to reuse a class.
+The class names in the markup patterns below follow it.
 
-**Good (semantic):**
-```html
-<h1 class="page-title">Dashboard</h1>
-<p class="page-subtitle">Welcome back</p>
-<button class="btn-primary">Save Changes</button>
-<div class="policy-item">...</div>
-```
-
-**Avoid (presentational):**
-```html
-<h1 class="text-2xl font-bold text-gray-900">Dashboard</h1>
-<p class="text-sm text-gray-600 mt-2">Welcome back</p>
-<button class="bg-blue-500 text-white px-4 py-2 rounded">Save Changes</button>
-```
-
-### Implementation
-- Define semantic class names in `styles.css` using nested structure
-- Apply Tailwind utility classes with `@apply` directive inside semantic classes
-- Use semantic classes in HTML/Handlebars templates
-- Group related styles together with CSS nesting
-
-**Example:**
-```css
-.settings-page {
-    @apply px-6 py-4;
-
-    .settings-block {
-        @apply mb-8 bg-white border border-gray-200 rounded-lg p-6;
-    }
-
-    .block-heading {
-        @apply text-lg font-semibold text-gray-900 mb-4;
-    }
-}
-```
+## State labels and action verbs
+Before you name a state, choose its tone or signal, or write the label of a button or link, read the "Status communication" and "Affordance signaling" sections of `boop-ux-visual-judgement`, if the project has the `ux` capability.
+They say to take each state's label, tone and signal from one shared table, and to use one verb for an action on every surface.
+Whether or not it does, keep the project's state table and chosen verbs in its reference pages, and check them before adding a new state word or action label.
 
 ## Modular Templates and Partials
 Structure templates for reusability while maintaining simplicity:
@@ -83,28 +54,8 @@ When considering whether to reuse existing components:
 - **DON'T make** components overly configurable to handle every edge case
 - **DO create** a second simpler component if the existing one requires too many parameters or conditions
 
-### Handlebars Helpers
-`@boopkit/cap-web` includes the [`handlebars-helpers`](https://github.com/helpers/handlebars-helpers) library (~130 helpers) plus custom formatting helpers.
-
-**Standard helpers (from handlebars-helpers) — most useful:**
-- Comparison: `gt`, `lt`, `gte`, `lte`, `eq`, `is`, `not`, `compare`
-- Logical: `and`, `or`, `not`
-- String: `capitalize`, `trim`, `replace`, `startsWith`, `contains`
-- Array: `first`, `last`, `sort`, `forEach`, `join`
-- Math: `add`, `subtract`, `multiply`, `divide`, `ceil`, `floor`, `round`
-
-**Custom helpers (from @boopkit/cap-web):**
-- `fmt_dollars` — format number as currency: `{{fmt_dollars 1234}}` → `$1,234` (optional `sigfigs` for data viz: `{{fmt_dollars 12345 sigfigs=4}}` → `$12,350`)
-- `fmt_percent` — format as percentage: `{{fmt_percent 45}}` → `45%`
-- `fmt_date` — human-readable date: `{{fmt_date createdAt}}` → `March 28, 2026`
-- `markdown` — render markdown to HTML: `{{markdown text}}` or `{{#markdown}}...{{/markdown}}`
-- `icon` — inline SVG icon from heroicons: `{{icon "user" "24/outline"}}` or with CSS class: `{{icon "check" "24/solid" class="w-5 h-5 text-green-600"}}`. Styles: `24/outline`, `24/solid`, `20/solid`, `16/solid`. Icons are read from `node_modules/heroicons/` and cached.
-- `json` — JSON stringify: `{{json obj}}`
-- `truncate` — truncate string: `{{truncate text 100}}`
-- `urlencode` — percent-encode a value for a query parameter: `<a href="/signup?next={{urlencode next}}">`. Handlebars escapes an interpolated value for HTML, not for a URL, so `?next={{next}}` renders a return path of `/a&b=c` as `next=/a&amp;b&#x3D;c` and the browser reads `next=/a`. Use this helper for **every** value that lands in a query string; it encodes rather than validates, so whatever gates the value keeps doing that job.
-- `upper` / `lower` — case conversion
-- `eq` — strict equality check (also available from handlebars-helpers)
-
+### Template logic
+The Handlebars helpers the web capability registers are listed in [`reference/web-ui.ref.md`](../../reference/web-ui.ref.md#helpers).
 Keep template logic minimal—complex logic belongs in the controller/service layer.
 
 ## UI Structure Patterns
@@ -113,10 +64,10 @@ Keep template logic minimal—complex logic belongs in the controller/service la
 Follow consistent page patterns:
 ```html
 <div class="[page-type]-page">
-  <div class="page-header mb-6">
-    <h1 class="page-title">Page Title</h1>
-    <p class="page-subtitle">Brief description of the page</p>
-  </div>
+  <header class="header">
+    <h1 class="title">Page Title</h1>
+    <p class="subtitle">Brief description of the page</p>
+  </header>
 
   <section class="[content-section-class]">
     <!-- Page content -->
@@ -128,60 +79,37 @@ Follow consistent page patterns:
 Use consistent form patterns:
 ```html
 <form method="POST" action="/path" class="form">
-  <div class="form-group horizontal">
-    <label for="field-id" class="form-label">Field Name</label>
-    <input id="field-id" name="fieldName" type="text" class="form-input">
+  <div class="field horizontal">
+    <label for="field-id">Field Name</label>
+    <input id="field-id" name="fieldName" type="text">
   </div>
-  
-  <div class="form-actions">
+
+  <div class="actions">
     <button type="submit" class="btn-primary">Save</button>
-    <button type="button" class="btn-cancel">Cancel</button>
+    <button type="button" class="btn-secondary">Cancel</button>
   </div>
 </form>
 ```
 
 ### Component Structure
-Group related elements with semantic containers:
+Group related elements with semantic containers, a block class on the outside and short child names inside it:
 ```html
 <div class="policy-list">
-  <div class="policy-item">
-    <div class="policy-header">
-      <h2 class="policy-name">Policy Name</h2>
+  <div class="policy{{#if archived}} archived{{/if}}">
+    <div class="header">
+      <h2 class="name">Policy Name</h2>
       <!-- controls -->
     </div>
-    <p class="policy-description">Description text</p>
+    <p class="description">Description text</p>
   </div>
 </div>
 ```
 
-## Best Practices
-
-### Naming Conventions
-- Use lowercase with hyphens: `page-title`, `btn-primary`, `policy-item`
-- Be descriptive of purpose, not appearance: `block-heading` not `large-bold-text`
-- Group related classes with common prefixes: `policy-item`, `policy-header`, `policy-name`
-
-### CSS Organization
-- Group page-specific styles under page class selector
-- Use nesting to show hierarchy and relationships
-- Add comments to mark major sections: `/** === Settings Page === **/`
-- Keep specificity low—avoid deep nesting unless necessary
-
-### Reuse Strategy
-1. **First**, check if an existing semantic class fits your needs
-2. **If close**, use the existing class—don't create near-duplicates
-3. **If not quite right**, evaluate:
-   - Is it worth making the existing class more flexible?
-   - Or is a new simple class clearer?
-4. **Remember**: Two simple classes are better than one complex parameterized system
-
 ## Anti-Patterns to Avoid
-- ❌ Using Tailwind utility classes directly in templates (except for one-off spacing tweaks)
 - ❌ Creating overly abstract/configurable components for simple use cases
 - ❌ Deep partial nesting that makes template flow hard to follow
 - ❌ Adding UI elements or styles "just in case" they're needed later
 - ❌ Creating partials for markup that only appears once
-- ❌ Duplicating semantic classes with slightly different names
 
 ## "Paper-Style" Reports (Analytics & Insights)
 When designing report/analytics UIs, prefer a **paper-like** presentation:
@@ -198,7 +126,6 @@ When designing report/analytics UIs, prefer a **paper-like** presentation:
 See also:
 - `boop-coding-development` for Spartan Code Philosophy
 - [`reference/web-ui.ref.md`](../../reference/web-ui.ref.md) for the current implementation: the view engine, the CSS pipeline and the page pattern
-- [`reference/boop-guide.ref.md`](../../reference/boop-guide.ref.md) for the CSS extension model (`@theme` tokens, package styles, cascade overrides)
 
 ## Visually verify before declaring done
 
@@ -208,7 +135,7 @@ The flow:
 
 1. **Build the CSS bundle.** `npm run tailwind:build` (or the project's equivalent). Semantic classes compiled via `@apply` do not exist in the served bundle until it is rebuilt.
 2. **Restart the dev server if it caches the bundle at boot.** Many dev servers read the compiled CSS once at startup and a file watcher that ignores CSS will not pick up the rebuild.
-3. **Capture the affected page** at desktop (1280px) and mobile (390px) widths via a headless capture tool — for example the `scripts/ux-eval-capture.ts` script `cap-ux` ships, or the project's equivalent.
+3. **Capture the affected page** at desktop (1280px) and mobile (390px) widths with `npm run ux:capture -- <path> <label>`, the Playwright capture script `cap-web` ships, or the project's equivalent.
 4. **Read the captures.** Confirm the new fields appear, the layout reads coherently, and nothing collapsed or stacked in a way the structural tests cannot see.
 
 If the capture surfaces a layout issue, fix it before closing the issue, even if all unit tests pass. A green test suite is not evidence that the surface looks right; only the capture is.