@tamsensedev/runner 0.13.0 → 0.19.0

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

@@ -1,295 +1,295 @@
-# 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 })
-}
-
-// Notes for the replay: what this page check did and what it found, read on the task before anyone presses play
-function pageNotes(result) {
-    const failedRequests = result.failedRequests.length + result.badResponses.length
-    const found = [
-        result.error && `the check stopped: ${result.error}`,
-        result.status >= 400 && `the page answered ${result.status}`,
-        result.pageErrors.length > 0 && `${result.pageErrors.length} page errors`,
-        result.consoleErrors.length > 0 && `${result.consoleErrors.length} console errors`,
-        failedRequests > 0 && `${failedRequests} failed requests`,
-        result.horizontalOverflowPx > 0 && `the page scrolls sideways by ${result.horizontalOverflowPx}px`,
-    ].filter(Boolean)
-    const outcome = found.length > 0 ? `Found ${found.join(', ')}.` : 'No errors, failed requests or sideways scroll.'
-    return `Opened ${result.path} at ${result.width}px and ran the steps. ${outcome}`.slice(0, 600)
-}
-
-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, { notes: pageNotes(result) }) : 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, with the notes the script wrote from this summary. They are attached to the task when the run ends. When you know what a replay proves (the expected state showed, or exactly what broke), attach it sooner with `attach_replay` and your own notes: what you opened, clicked and expected, and whether it passed.
-- `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.
+# 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 })
+}
+
+// Notes for the replay: what this page check did and what it found, read on the task before anyone presses play
+function pageNotes(result) {
+    const failedRequests = result.failedRequests.length + result.badResponses.length
+    const found = [
+        result.error && `the check stopped: ${result.error}`,
+        result.status >= 400 && `the page answered ${result.status}`,
+        result.pageErrors.length > 0 && `${result.pageErrors.length} page errors`,
+        result.consoleErrors.length > 0 && `${result.consoleErrors.length} console errors`,
+        failedRequests > 0 && `${failedRequests} failed requests`,
+        result.horizontalOverflowPx > 0 && `the page scrolls sideways by ${result.horizontalOverflowPx}px`,
+    ].filter(Boolean)
+    const outcome = found.length > 0 ? `Found ${found.join(', ')}.` : 'No errors, failed requests or sideways scroll.'
+    return `Opened ${result.path} at ${result.width}px and ran the steps. ${outcome}`.slice(0, 600)
+}
+
+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, { notes: pageNotes(result) }) : 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, with the notes the script wrote from this summary. They are attached to the task when the run ends. When you know what a replay proves (the expected state showed, or exactly what broke), attach it sooner with `attach_replay` and your own notes: what you opened, clicked and expected, and whether it passed.
+- `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.