@tamsensedev/runner 0.0.0-stage → 0.2.1

package/library/skills/test-driven-development/references/writing-good-tests.md

@@ -0,0 +1,85 @@
+# Writing good tests
+
+Read this when writing or changing a test, adding a mock, or adding a test helper.
+
+A test exists to catch a specific break. Two rules carry most of the weight:
+
+1. Every test names the break it catches.
+2. Every test exercises the real thing.
+
+## Rule 1: name the break
+
+Before writing the body, answer: which production change would make this test fail, and is that change a bug or a deliberate decision? A good test catches a wrong branch, a missing side effect, a wrong argument, a boundary case or a broken contract.
+
+**Derive expected values independently.** Use literals and hand-checked fixtures. An expected value computed by the code under test (or its helpers) passes whatever the code does.
+
+```ts
+// Bad: the same builder produces both sides, so it is always equal
+const expected = buildSearchQuery({ tag: 'urgent' })
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected)
+
+// Bad: recomputes the answer the way the code does
+expect(add(a, b)).toBe(a + b)
+
+// Good: written out by hand
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"')
+```
+
+Table-driven tests with literal expected values are a good shape for many cases.
+
+**No change detectors.** A test that only fails on intentional decisions (a constant's value, exact message wording, private structure) fires on every redesign and sleeps through real bugs. Test the behaviour that depends on the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is retried 5 times and a sixth attempt never happens".
+
+**Behaviour, not source text.** Asserting that a file contains a certain line proves only that the file is the file. Run the script, config or template against a controlled input and check the output, side effect or exit code.
+
+**Your code, not the framework.** Test the contract your code makes at its boundary: the route you register, the query you build, the payload you send. Do not test that the router calls a registered handler; that is the framework's job. Constructors, getters and simple pass-throughs earn a test only when they validate, normalise, default, derive or cause a side effect.
+
+**Through the public surface.** Test via the function, endpoint, component or command that callers use. A test that breaks when you refactor internals without changing behaviour is coupled to implementation. Avoid checking results through a side channel (querying the database directly) when the public interface can show them.
+
+## Rule 2: exercise the real thing
+
+**Never assert on a mock.** An assertion that a mock was rendered or exists passes when the mock is there and says nothing about the component.
+
+```ts
+// Bad: tests the mock
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument()
+
+// Good: tests the real behaviour
+expect(screen.getByRole('navigation')).toBeInTheDocument()
+```
+
+**Mock at the right level.** Before replacing a method, learn all its side effects. Mock the slow or external part below it (network, paid API, clock, email) and keep what the test depends on real. A mock that swallows a write that the code later reads makes the test pass while the real thing breaks.
+
+**Make doubles specific.** When arguments, call counts or order are part of the contract, assert them. Give success, error and malformed responses their own fixtures, so the wrong branch cannot satisfy the test.
+
+**Mirror real data completely.** Fake responses should have the full structure of the real one, not only the fields this test reads. Partial fakes hide failures in code that reads the other fields.
+
+**Production code carries production methods only.** Cleanup or reset methods that only tests call belong in test utilities, not on the production class.
+
+**Prefer real components over elaborate mocks.** When mock setup is longer than the test logic, or the test breaks whenever the mock changes, switch to a test with real collaborators (an in-memory database, the real module, the project's existing test server).
+
+## The mutation check
+
+Before finishing, imagine small breaks in the production code. At least one test should fail for each realistic one:
+
+- A wrong constant or argument.
+- A wrong branch taken.
+- A missing state change or side effect.
+- An empty or default return value.
+- Missing validation for zero, empty, null, unauthorised or malformed input.
+
+If nothing fails for a realistic mutation, that behaviour is unprotected. For an important change you can make the mutation for real: invert one condition, run the tests, confirm a failure, restore the line, and confirm with `git diff` that it is restored.
+
+## Warning signs
+
+- Setup and assertion share the same object, so they are equal by construction.
+- The test can only fail by crashing or by a missing selector.
+- The test fails on every intentional change but never on accidental breakage.
+- Expected values are hidden behind loops, builders or helpers.
+- The test greps source text.
+- The test exists for coverage and checks no outcome.
+- An assertion checks a `*-mock` test id, or fails if you remove the mock.
+- A method is called only from test files.
+- Mock setup is more than half the test, or you cannot say why the mock is needed.
+- Writing all the tests for a feature before any implementation: tests for imagined behaviour test the shape of things, not what users see. Go one test at a time.
+
+Sources: obra/superpowers (MIT, commit bb92a77) writing-good-tests and mattpocock/skills (MIT, commit 5beb35b) tdd. Changed: shortened and merged.

package/library/skills/ui-testing/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: ui-testing
+description: Use when a change affects what users see or click in a web app and should be checked in a real browser, when writing or fixing Playwright or Cypress tests, or when a test step must verify UI behaviour. Runs the project's E2E suite or a headless check from a temp folder and reports screenshots and errors as evidence.
+---
+
+# UI testing in a headless browser
+
+Reading the code tells you what should happen; a browser shows what does. This skill gets the app running, drives the changed flows headless, and turns what it saw into evidence for the report. Nobody watches the run, so every step must finish on its own and leave the machine as it was.
+
+The project's own setup wins: its E2E framework, config, fixtures, page objects, test data, auth helpers and scripts. Use them before anything from here.
+
+## Hard rules
+
+1. **Headless only.** Never open a window: no `--headed`, `--ui`, `--debug`, `show-report`, `show-trace`, `cypress open`, `PWDEBUG`. Playwright's HTML reporter opens a browser on failure when not in CI, so run with `--reporter=line` and `PW_TEST_HTML_REPORT_OPEN=never`. Set `BROWSER=none` when starting dev servers so they do not open one either.
+2. **No new dependencies.** Do not add packages to the repository and do not download browsers (`playwright install`, `npx some-tool@latest`) just to check. Use what is installed. If the project has no Playwright but the `TAMSENSE_PLAYWRIGHT` environment variable is set, the TAMsense runner has already installed `playwright-core` and a headless browser outside the project, and the headless check script uses them. If nothing is, check from the code and say the browser check could not run.
+3. **The project's own start command, on a free port.** Start the app with its dev or preview script, never a hand-made server that skips its config. Prefer the headless check script, which starts the server and stops its whole process tree for you. Stop it at the end, including child processes, and confirm the port is free again.
+8. **Stop only what you started, by process id.** This is someone's own computer and their other programs may be running. Never kill processes by name or pattern: no `taskkill /IM`, `pkill`, `killall`, `Stop-Process -Name`. If you start a server yourself, record its PID and stop that process tree (`taskkill /PID <pid> /T /F` on Windows, `kill -- -<pgid>` elsewhere). If a process you started cannot be stopped that way, say so in the report and leave the rest alone.
+4. **Outputs outside the repository.** Screenshots, traces, reports, scratch scripts and auth state go to a new folder in the OS temp directory. `git status` must show nothing new from you when you finish.
+5. **Never fake it.** If the app cannot start (missing environment variables, secrets, a database or service you may not use), report exactly what is missing. Do not mock the whole backend and call the result a pass, and do not invent screenshots or results.
+6. **Do not write to shared systems.** If the local app is configured against a shared or production backend or database, look but do not submit forms or trigger writes.
+7. **Never hide failures.** Do not skip, `fixme`, delete or loosen a failing test to get a green run. In a check step, a failing test is a finding.
+9. **Every browser is recorded for the task.** In a TAMsense run each Playwright context becomes a replay people watch on the task, and the tested site's TAMsense tracker is blocked. Open contexts through the recorder with a title and a purpose, mark the meaningful steps, and add a video for canvas, maps, video players or iframes from another site: see [references/recording.md](references/recording.md).
+
+## Process
+
+### 1. Decide what to check
+
+From the task, the spec's acceptance criteria and the diff (`git diff origin/<base>...HEAD --stat`, then the changed components, routes and styles), write a short list of scenarios before touching the browser:
+
+- The main flow the task changed, end to end.
+- Its states: loading, empty, error, long or unusual content, many items, disabled controls.
+- A narrow screen (390 px wide) if layout or styles changed, plus a desktop width.
+- Keyboard use for any new or changed control (Tab to it, activate with Enter or Space, Escape closes overlays). The `accessibility` skill has the full checks.
+
+### 2. Find how this project runs and tests its UI
+
+- E2E setup: `playwright.config.*`, `cypress.config.*`, `e2e/` or `tests/` folders, scripts like `test:e2e` in `package.json`, and the CI workflow steps that run them (they show the exact command, env vars and services).
+- The app: dev and preview scripts, required env vars (`.env.example`, config validation, README), services it needs (database, cache, other apps in a monorepo). Check whether required variables are set by name; never print their values.
+- Auth: seeded test users, a test login endpoint, existing storage-state setup.
+- The installed Playwright or Cypress version.
+
+### 3a. The project has an E2E suite
+
+Run the specs related to the change, then the whole suite if it is fast enough.
+
+- Playwright: `PW_TEST_HTML_REPORT_OPEN=never npx playwright test <specs> --reporter=line --output <tmp>/test-results` (use the package manager the project uses). Its browsers are recorded by themselves under the step's name; a long suite fills the run's limit of 20 replays, so run the related specs rather than everything when you can. Its `webServer` config usually starts the app: check the port and `reuseExistingServer`, and make sure no stale server of yours is still running.
+- Cypress: `npx cypress run --spec <specs> --config screenshotsFolder=<tmp>/screens,videosFolder=<tmp>/videos,video=false` (headless by default).
+- If a run fails, rerun the failing spec alone to separate a real failure from a flaky one, and read the error and screenshot. Decide whether the failure comes from the change (the diff touches that flow) or existed before; say which and why.
+
+In a code step, add or update tests for the changed flow following the suite's structure; see [references/playwright-patterns.md](references/playwright-patterns.md) for locators, waiting, auth, mocking and the plan, write, repair loop. In a review or test step, do not edit the repository's tests; check extra scenarios with 3b instead.
+
+### 3b. No suite, or scenarios the suite does not cover
+
+Use the headless check in [references/headless-check.md](references/headless-check.md): a Node.js script you write to a temp folder that resolves Playwright from the project, starts the app with the project's command on a free port, visits the pages at 1280 and 390 px, runs your steps with marks, records each page for the task, saves screenshots and a JSON summary (console errors, failed requests, horizontal overflow, optional axe scan), and stops the app.
+
+If Playwright is not installed in the project and no other headless browser tool is available, do not install one. Check the change from the code and say so.
+
+### 4. Look at the evidence
+
+- Open every screenshot with the Read tool and compare it with what the scenario expects. Describe what you see in plain words: what is on the screen, what is wrong, where.
+- Console errors, page errors and failed requests from the changed code are findings; third-party noise is not, but name it so the reader knows you saw it.
+- Sideways scrolling at 390 px, cut-off text, overlapping elements, missing states and dead buttons are findings.
+- For visual quality and consistency with the design system, apply the `design-review` skill; for the rules list, `web-interface-guidelines`; for accessibility, `accessibility`.
+
+### 5. Clean up
+
+Stop the servers you started, by their process id only (hard rule 8), check the port no longer answers, remove containers and temp folders you created unless the task asks to keep artifacts, and run `git status` in every repository to confirm you left nothing behind.
+
+## Report
+
+```
+UI check: <passed | failed | could not run>
+How: <suite command or headless check>, browser <chromium | chrome | msedge>, widths <1280, 390>
+Recordings: <titles of the replays and videos attached to the task>
+Scenarios:
+- <scenario>: pass | fail | not checked (why). Evidence: <what the screenshot or log shows>
+Findings:
+- <file:line if traced> <what is wrong, how to reproduce, what was expected>
+Not checked: <and why: missing env vars X, Y; no browser available; flow needs an external provider>
+Assumptions: <test account used, data you created locally, version>
+```
+
+In a test step, base the verdict on the scenarios: a broken acceptance criterion, an error from the changed code or a layout broken on narrow screens fails it. If the browser check could not run, do not report it as passed; judge from the other evidence (tests, code) and state clearly that the UI was not seen. If the change itself stops the app from starting or building, that is a failure.
+
+## Common mistakes
+
+- Assuming the page works because the build passed.
+- Fixed sleeps instead of waiting for the element that proves readiness.
+- Letting the HTML reporter or a dev server open a browser window.
+- Leaving the dev server running, or `test-results/` and screenshots inside the repository.
+- Testing only the happy path at desktop width.
+- Pointing the check at staging or production because the local app did not start.
+- Listing screenshot paths without saying what they show.
+- Generic names for screenshots and recordings ("screenshot1", "test run") instead of what they show and why.
+
+## Done when
+
+- Every scenario from step 1 is checked or listed as not checked with a reason.
+- Evidence (described screenshots, error lines, failing assertions) backs each finding.
+- No window was opened, no dependency added, nothing left running or written into the repository.
+
+Sources: the start, wait, act, stop approach of anthropics/skills webapp-testing (Apache-2.0, commit dbd4588), testdino-hq/playwright-skill (MIT, commit 178d1cb), ideas from the Playwright test agents (Apache-2.0). Changed: rewritten for Node and the project's own setup, unattended rules added.

package/library/skills/ui-testing/references/headless-check.md

@@ -0,0 +1,280 @@
+# Headless check without an E2E suite
+
+Read this when the project has no Playwright or Cypress tests you can run for the change, but you still need to see the pages: screenshots, console errors, failed requests, horizontal overflow on narrow screens, and optionally an axe scan.
+
+The script below starts the app with the project's own command on a free port, waits for it, opens each page headless at a desktop and a phone width, runs optional steps you write, saves screenshots and a JSON summary to a temp folder, and stops the app and all its child processes at the end. In a TAMsense run each page and width is also recorded as a replay for the task, named from `CONFIG.title` and `CONFIG.purpose` (see [recording.md](recording.md)).
+
+## What it needs
+
+- Node.js 20 or newer.
+- The `playwright`, `@playwright/test` or `playwright-core` package already installed in the project (it is resolved from the project folder you give it; in a monorepo, use the package folder of the web app). If the project has none and the `TAMSENSE_PLAYWRIGHT` environment variable is set, the script loads the `playwright-core` that the TAMsense runner installed in that folder, with the headless browser from the `TAMSENSE_PLAYWRIGHT_BROWSERS` folder. Nothing is installed.
+- A browser that is already on the machine: Playwright's downloaded Chromium (the project's or the runner's), or the system Chrome or Edge as a fallback. If none works, the script stops and says so. Do not run `playwright install` or add packages to get one; report that the check could not run.
+- `axe-core` is optional: if the project already has it, each page also gets an accessibility scan.
+
+## How to use it
+
+1. Make a new folder in the OS temp directory (`node -p "require('os').tmpdir()"`), for example `<tmp>/ui-check-<random>`. Never inside the repository.
+2. Write the script there as `ui-check.mjs` and edit only the `CONFIG` block and the `steps` function. Set `title` and `purpose` to what this check is and why ("Feature testing, attempt 2", "Checking the empty orders state after the fix"), and `video: true` when the pages have a canvas, a map, a video player or iframes from another site.
+3. Run `node <tmp>/ui-check-<random>/ui-check.mjs` with a timeout of a few minutes. It prints the summary; screenshots are in `CONFIG.outDir`.
+4. Open the screenshots with the Read tool and look at them. Describe in the report what each one shows; the paths alone mean nothing to the reader.
+5. Delete the folder when the report is written, unless the task asks you to keep artifacts.
+
+`startCommand` is the project's own dev or preview command with `{port}` where the port goes, for example `pnpm dev --port {port} --strictPort` (Vite), `npm run dev -- -p {port}` (Next.js), `pnpm nuxt dev --port {port}`, `bin/rails server -p {port}`, `python manage.py runserver 127.0.0.1:{port}`. The script also sets `PORT`. Leave it empty and set `baseUrl` if the app is already running or is static files you serve another way.
+
+On Windows the command runs in `cmd.exe`, which may not see the same PATH as your shell. If the summary says the command is not recognized, use absolute paths (for example the full path to `node.exe` and the package manager's script) rather than changing anything in the project.
+
+## The script
+
+```js
+import { createRequire } from 'node:module'
+import { spawn, execFileSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import net from 'node:net'
+
+const CONFIG = {
+    projectDir: '/absolute/path/to/web/app',
+    outDir: '/absolute/path/to/tmp/ui-check-1234/out',
+    startCommand: 'pnpm dev --port {port} --strictPort',
+    baseUrl: '',
+    paths: ['/'],
+    widths: [1280, 390],
+    startTimeoutMs: 120_000,
+    navigationTimeoutMs: 30_000,
+    title: 'Feature testing',
+    purpose: 'Checking the changed screens at desktop and phone width',
+    video: false,
+}
+
+async function steps(page, { path, width, mark }) {
+}
+
+const MAX_ITEMS = 20
+const MAX_TITLE = 60
+const serverOutput = []
+const recorder = process.env.TAMSENSE_RECORDER ? createRequire(import.meta.url)(process.env.TAMSENSE_RECORDER) : null
+
+function keepTail(chunk) {
+    serverOutput.push(...String(chunk).split('\n').filter(Boolean))
+    serverOutput.splice(0, Math.max(0, serverOutput.length - 40))
+}
+
+function requireFrom(dir, names) {
+    const require = createRequire(join(dir, 'package.json'))
+    for (const name of names) {
+        try {
+            return require(name)
+        } catch {}
+    }
+    return null
+}
+
+function loadFromProject(names) {
+    const found = requireFrom(CONFIG.projectDir, names)
+    const runnerCopy = process.env.TAMSENSE_PLAYWRIGHT
+    if (found || !names.includes('playwright-core') || !runnerCopy) return found
+    if (process.env.TAMSENSE_PLAYWRIGHT_BROWSERS) process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.TAMSENSE_PLAYWRIGHT_BROWSERS
+    return requireFrom(runnerCopy, ['playwright-core'])
+}
+
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer()
+        server.on('error', reject)
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address()
+            server.close(() => resolve(port))
+        })
+    })
+}
+
+function startServer(command, port) {
+    const child = spawn(command.replaceAll('{port}', String(port)), {
+        cwd: CONFIG.projectDir,
+        shell: true,
+        env: { ...process.env, PORT: String(port), BROWSER: 'none' },
+        detached: process.platform !== 'win32',
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    child.stdout.on('data', keepTail)
+    child.stderr.on('data', keepTail)
+    return child
+}
+
+function stopServer(child) {
+    if (!child || child.exitCode !== null) return 'not running'
+    try {
+        if (process.platform === 'win32') {
+            const taskkill = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe')
+            execFileSync(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+        } else {
+            process.kill(-child.pid, 'SIGKILL')
+        }
+        return 'stopped'
+    } catch (error) {
+        child.kill('SIGKILL')
+        return `could not stop the process tree of pid ${child.pid}: ${error.message}`
+    } finally {
+        child.stdout.destroy()
+        child.stderr.destroy()
+        child.unref()
+    }
+}
+
+async function waitForServer(url, child) {
+    const deadline = Date.now() + CONFIG.startTimeoutMs
+    while (Date.now() < deadline) {
+        if (child && child.exitCode !== null) throw new Error(`start command exited with code ${child.exitCode}`)
+        try {
+            await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(5_000) })
+            return
+        } catch {}
+        await new Promise(resolve => setTimeout(resolve, 1_000))
+    }
+    throw new Error(`no response from ${url} within ${CONFIG.startTimeoutMs / 1000}s`)
+}
+
+async function launchBrowser(chromium) {
+    const failures = []
+    for (const channel of [undefined, 'chromium', 'chrome', 'msedge']) {
+        try {
+            return await chromium.launch({ headless: true, channel })
+        } catch (error) {
+            failures.push(`${channel ?? 'playwright chromium'}: ${String(error.message).split('\n')[0]}`)
+        }
+    }
+    throw new Error(`no browser available without downloading one: ${failures.join(' | ')}`)
+}
+
+async function runAxe(page, axeSource) {
+    try {
+        await page.addScriptTag({ content: axeSource })
+        return await page.evaluate(async () => {
+            const result = await window.axe.run(document, {
+                runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'] },
+            })
+            return result.violations.map(violation => ({
+                rule: violation.id,
+                impact: violation.impact,
+                help: violation.help,
+                count: violation.nodes.length,
+                targets: violation.nodes.slice(0, 5).map(node => JSON.stringify(node.target)),
+            }))
+        })
+    } catch (error) {
+        return { error: String(error.message).split('\n')[0] }
+    }
+}
+
+async function openContext(browser, path, width) {
+    const options = { viewport: { width, height: 900 } }
+    if (!recorder) return browser.newContext(options)
+    const where = `, ${path} at ${width}px`
+    const title = `${CONFIG.title.slice(0, MAX_TITLE - where.length)}${where}`
+    return recorder.newRecordedContext(browser, { title, purpose: CONFIG.purpose, video: CONFIG.video, context: options })
+}
+
+async function checkPage(browser, url, path, width, axeSource) {
+    const context = await openContext(browser, path, width)
+    const page = await context.newPage()
+    const mark = label => recorder?.mark(page, label)
+    const result = { path, width, consoleErrors: [], pageErrors: [], failedRequests: [], badResponses: [] }
+    const add = (list, item) => { if (list.length < MAX_ITEMS) list.push(item) }
+    page.on('console', message => { if (message.type() === 'error') add(result.consoleErrors, message.text()) })
+    page.on('pageerror', error => add(result.pageErrors, String(error.message)))
+    page.on('requestfailed', request => add(result.failedRequests, `${request.method()} ${request.url()} ${request.failure()?.errorText ?? ''}`))
+    page.on('response', response => { if (response.status() >= 400) add(result.badResponses, `${response.status()} ${response.url()}`) })
+    try {
+        const response = await page.goto(url, { waitUntil: 'load', timeout: CONFIG.navigationTimeoutMs })
+        result.status = response?.status() ?? null
+        await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {})
+        await mark(`Opened ${path}`)
+        result.steps = await steps(page, { path, width, mark })
+        result.title = await page.title()
+        result.finalUrl = page.url()
+        result.horizontalOverflowPx = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)
+        const name = `${path.replace(/[^a-z0-9]+/gi, '_').replace(/^_|_$/g, '') || 'root'}-${width}.png`
+        result.screenshot = join(CONFIG.outDir, name)
+        await page.screenshot({ path: result.screenshot, fullPage: true })
+        if (axeSource) result.axe = await runAxe(page, axeSource)
+    } catch (error) {
+        result.error = String(error.message).split('\n')[0]
+    } finally {
+        result.recording = recorder ? await recorder.closeRecorded(context) : await context.close()
+    }
+    return result
+}
+
+async function main() {
+    mkdirSync(CONFIG.outDir, { recursive: true })
+    const summary = { pages: [], serverOutputTail: serverOutput }
+    const playwright = loadFromProject(['playwright', '@playwright/test', 'playwright-core'])
+    if (!playwright?.chromium) throw new Error(`Playwright is not installed in ${CONFIG.projectDir} and TAMSENSE_PLAYWRIGHT is not set`)
+    const axeSource = loadFromProject(['axe-core'])?.source ?? null
+    summary.axe = axeSource ? 'axe-core found in the project' : 'axe-core not installed, scan skipped'
+
+    let server = null
+    let browser = null
+    try {
+        let baseUrl = CONFIG.baseUrl
+        if (CONFIG.startCommand) {
+            const port = await freePort()
+            server = startServer(CONFIG.startCommand, port)
+            baseUrl = `http://localhost:${port}`
+        }
+        if (!baseUrl) throw new Error('set CONFIG.startCommand or CONFIG.baseUrl')
+        summary.baseUrl = baseUrl
+        await waitForServer(baseUrl, server)
+        browser = await launchBrowser(playwright.chromium)
+        for (const path of CONFIG.paths) {
+            for (const width of CONFIG.widths) {
+                summary.pages.push(await checkPage(browser, new URL(path, baseUrl).href, path, width, axeSource))
+            }
+        }
+    } catch (error) {
+        summary.setupError = String(error.message)
+        process.exitCode = 2
+    } finally {
+        await browser?.close().catch(() => {})
+        if (server) summary.server = stopServer(server)
+        writeFileSync(join(CONFIG.outDir, 'summary.json'), JSON.stringify(summary, null, 2))
+        console.log(JSON.stringify(summary, null, 2))
+    }
+}
+
+main().catch(error => {
+    console.error(error.message)
+    process.exitCode = 2
+})
+```
+
+## Writing steps
+
+`steps` runs on every page and width before the screenshot. Use it to reach the state the task changed: open the dialog, fill and submit the form, switch the tab. Branch on `path` when pages need different steps. Call `await mark('...')` after each meaningful step: the marks show on the replay's timeline for the people on the task. Whatever it returns is saved as `steps` in that page's summary (for example the focus order from a keyboard pass, see the `accessibility` skill). Use the same rules as in tests: role and label locators, web-first waits, no fixed sleeps (see [playwright-patterns.md](playwright-patterns.md)).
+
+```js
+async function steps(page, { path, mark }) {
+    if (path !== '/settings') return
+    await page.getByRole('button', { name: 'Edit profile' }).click()
+    await mark('Opened the profile form')
+    await page.getByLabel('Display name').fill('A very long display name that should wrap or truncate')
+    await page.getByRole('button', { name: 'Save' }).click()
+    await page.getByRole('status').waitFor()
+    await mark('Saved a long display name')
+}
+```
+
+Steps that write data only touch the local app and whatever local database it uses. If the dev server is configured to talk to a shared or production backend or database, do not submit forms or trigger writes; check that first (see the `safe-database-changes` skill for how to read where the app connects).
+
+## Reading the summary
+
+- `server`: should be `stopped`. Anything else names a process you must stop yourself before finishing.
+- `recording`: where each page's replay (and video) is. They are attached to the task when the run ends; `attach_replay` and `attach_video` attach one sooner.
+- `setupError`: the app or the browser did not start. Report it with the last lines of `serverOutputTail` (strip anything that looks like a secret). Do not retry with a different command unless the first one was clearly wrong, and never invent results.
+- `status` 4xx or 5xx, `pageErrors`, `consoleErrors`: real findings when they come from the changed code; noise from browser extensions does not exist here, but third-party scripts and dev-server warnings do. Say which is which.
+- `badResponses` and `failedRequests`: API calls the page needed that failed. A 401 or a redirect to a login page means the page needs a signed-in user (see the auth section of [playwright-patterns.md](playwright-patterns.md)).
+- `horizontalOverflowPx` above 0 at 390 px: the page scrolls sideways on phones.
+- `axe`: list each rule with impact and a target; the `accessibility` skill explains how to judge them.
+
+Written for this library. The start, wait, act, stop approach follows anthropics/skills `webapp-testing` (Apache-2.0, commit dbd4588f9e1033efb41dad4bef2f7947c8993d44, Copyright 2026 Anthropic, PBC); the script is new Node.js code, not a translation of its Python helper.

package/library/skills/ui-testing/references/playwright-patterns.md

@@ -0,0 +1,134 @@
+# Playwright patterns: locators, waiting, flakes, auth, mocking
+
+Read this when you write, fix or review browser tests or the `steps` of a headless check. In a TAMsense run every browser context, also those of the project's tests, is recorded for the task; scripts of your own name their recordings as [recording.md](recording.md) shows. Examples are Playwright Test in TypeScript; translate to the project's language and runner. If the project uses Cypress, the same ideas apply (see the last section). Check the installed version (`npx playwright --version`) before using an API you are not sure exists in it.
+
+## Locators
+
+Use the first one that works, in this order:
+
+```ts
+page.getByRole('button', { name: 'Save changes' })   // 1. role + accessible name
+page.getByLabel('Email address')                      // 2. form fields by label
+page.getByText('Welcome back')                        // 3. non-interactive text
+page.getByPlaceholder('Search')                       // 4. only if there is no label
+page.getByAltText('Company logo')                     // 5. images
+page.getByTestId('checkout-summary')                  // 6. when nothing semantic is stable
+page.locator('.legacy-widget button')                 // 7. CSS or XPath, last resort
+```
+
+- Role locators survive class renames and component swaps, and they fail when the control is not accessible, which is a finding in itself.
+- `exact: true` stops "Log" from matching "Log out".
+- Scope instead of indexing: `page.getByRole('dialog', { name: 'Delete project' }).getByRole('button', { name: 'Delete' })` beats `.nth(2)`.
+- Rows and cards: `page.getByRole('row').filter({ hasText: 'Invoice 42' }).getByRole('button', { name: 'Open' })`.
+- Use the project's existing `data-testid` convention if it has one; do not add test ids to product code during a check step.
+- Strict mode errors ("resolved to 2 elements") mean the locator is ambiguous: scope it, do not add `.first()` to silence it.
+
+## Waiting and assertions
+
+Actions (`click`, `fill`, `check`) already wait for the element to be attached, visible, stable and enabled. Assertions on locators retry until they pass or time out. Use them; do not sleep.
+
+| Need | Use |
+|---|---|
+| Element shown or hidden | `await expect(locator).toBeVisible()` / `.toBeHidden()` |
+| Text | `toHaveText` (full) or `toContainText` |
+| Count | `toHaveCount(n)` |
+| Input value, attribute, focus | `toHaveValue`, `toHaveAttribute`, `toBeFocused` |
+| Navigation | `await expect(page).toHaveURL(/\/dashboard/)` |
+| A request or response | register `page.waitForResponse(...)` **before** the action that triggers it |
+| A non-DOM condition | `await expect.poll(() => readStatus()).toBe('done')` |
+
+Wrong and right:
+
+```ts
+await page.waitForTimeout(2000);                              // wrong: too slow or too short
+expect(await page.getByRole('alert').isVisible()).toBe(true); // wrong: checks once, no retry
+expect(await row.textContent()).toBe('Paid');                 // wrong: no retry
+
+await expect(page.getByRole('alert')).toBeVisible();          // right
+await expect(row).toHaveText('Paid');                         // right
+
+const saved = page.waitForResponse(r => r.url().includes('/api/profile') && r.ok());
+await page.getByRole('button', { name: 'Save' }).click();
+await saved;                                                  // right: registered before the click
+```
+
+- `networkidle` is unreliable with websockets, polling or analytics. Wait for the element or URL that proves the page is ready.
+- Every `expect` and every action is awaited. A missing `await` makes a test pass before it checked anything.
+- Do not wrap assertions in try/catch; do not raise timeouts above about 30 s to make something pass.
+
+## Flaky tests
+
+A flaky test has a cause; retries and longer timeouts only hide it. Classify first:
+
+| Symptom | Likely cause | How to confirm |
+|---|---|---|
+| Fails sometimes even alone | Timing: missing await, sleep, race between action and assertion | `npx playwright test <file> --repeat-each=10` (raise the count for rare races) |
+| Passes alone, fails in the suite | Isolation: shared state, shared test data, order dependence | `--grep "<name>" --workers=1` passes, full run fails |
+| Fails only in CI | Environment: viewport, fonts, slower machine, missing service | Compare traces and screenshots from both |
+| Random crashes, "Target closed" | Infrastructure: memory, browser crash | Errors mention the browser, not the app |
+
+Fixes: replace sleeps with web-first assertions; register waits before actions; give each test its own data (unique names, per-test setup); avoid module-level mutable variables; set viewport and `reducedMotion: 'reduce'` explicitly when animation or layout matters. For evidence, run with `--trace retain-on-failure --reporter=line --output <tmp>/test-results` and read the error message and the error-context and screenshot files in that output folder. Do not open `show-trace`, `show-report`, `--ui` or `--headed`: they open windows, and nobody is there to look.
+
+## Authentication
+
+- Use the project's existing auth setup first: a setup project, a global setup that saves `storageState`, a fixture, a test-only login endpoint.
+- Without one, log in once per run through the UI or the API with a **test account the project documents for local development** (seed data, README, fixtures), save `storageState` to the temp folder, and reuse it.
+- Never use real user credentials, never read secrets the task did not give you, and never write auth state files inside the repository.
+- Testing the login page itself: start from an empty state (`storageState: { cookies: [], origins: [] }`).
+- OAuth or SSO with an external provider: do not hit the real provider; check the pages around it or report that the flow could not be exercised.
+
+```ts
+// global setup or the first step of a headless check
+await page.goto('/login');
+await page.getByLabel('Email').fill(process.env.E2E_USER ?? 'demo@example.test');
+await page.getByLabel('Password').fill(process.env.E2E_PASSWORD ?? 'from-the-seed-file');
+await page.getByRole('button', { name: 'Sign in' }).click();
+await expect(page).toHaveURL(/dashboard/);
+await page.context().storageState({ path: `${tmpDir}/auth.json` });
+```
+
+## Network mocking
+
+Mock what you do not own (payment providers, email, maps, analytics) and error states you cannot trigger otherwise. Do not mock the app's own pages, scripts or styles, and prefer the real backend for the happy path.
+
+```ts
+await page.route('**/api/orders', route =>
+  route.fulfill({ status: 500, json: { error: 'Internal error' } }));   // error state
+await page.route('**/api/orders', route => route.fulfill({ json: [] })); // empty state
+await page.route('**/api/orders', async route => {                        // slow: loading state
+  await new Promise(r => setTimeout(r, 3000));
+  await route.continue();
+});
+await page.route(/analytics|segment|hotjar/, route => route.abort());    // third-party noise
+```
+
+- Register routes before `page.goto`.
+- Every handler calls exactly one of `fulfill`, `continue` or `abort`, otherwise the request hangs.
+- Keep globs narrow (`**/api/orders`, not `**/*`).
+- Loading, empty and error states are where UI changes break most often; mocking is the cheapest way to see them.
+
+## Writing new tests (code step only)
+
+When the task changes a user flow and the project has an E2E suite:
+
+1. **Plan:** list the scenarios from the acceptance criteria: the happy path, the main error state, the empty state, the narrow screen if layout changed. Note what each one must assert.
+2. **Generate:** follow the suite's existing structure, fixtures, page objects and naming. One behaviour per test; several related `expect`s are fine.
+3. **Run** the new tests several times (`--repeat-each=3` at least) and the related existing tests once.
+4. **Repair** failures by finding the cause. If a test fails because the app is wrong, fix the app (in a code step) or report the bug (in a check step).
+
+Never make a run green by marking tests `test.skip`, `test.fixme`, `test.fail`, `.only`-ing others, deleting assertions, loosening them (`toHaveText` to `toContainText` without reason), or adding sleeps. A healed test that hides a regression is worse than a red one.
+
+## Cypress equivalents
+
+| Playwright | Cypress |
+|---|---|
+| `getByRole`, `getByLabel` | `cy.findByRole`, `cy.findByLabelText` if Testing Library is installed; otherwise `cy.contains` and the project's `data-cy` / `data-testid` |
+| web-first `expect(locator)` | `cy.get(...).should(...)` (retries) |
+| `waitForResponse` | `cy.intercept(...).as('x')` then `cy.wait('@x')` |
+| `page.route(...).fulfill` | `cy.intercept(method, url, { statusCode, body })` |
+| `storageState` | `cy.session()` |
+| `npx playwright test <file>` | `npx cypress run --spec <file>` (headless by default; never `cypress open`) |
+
+The same bans apply: no `cy.wait(<milliseconds>)`, no skipping failing tests.
+
+Adapted from testdino-hq/playwright-skill guides `core/locators.md`, `core/assertions-and-waiting.md`, `core/flaky-tests.md`, `core/authentication.md`, `core/network-mocking.md` and `core/test-agents.md` (MIT, commit 178d1cb537604279d7b54500c4823a6db42b9de6, Copyright (c) 2026 TestDino). Changed: condensed several thousand lines into one page, removed version-specific APIs and vendor mentions, added unattended rules (test accounts, temp folders, no skips), added the Cypress table. The plan, generate, repair loop restates the idea of the Playwright test agents (microsoft/playwright, Apache-2.0) in our own words; no text copied.