@tamsensedev/runner 0.1.0 → 0.2.1

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

@@ -2,7 +2,7 @@
 
 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.
+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
 
@@ -14,7 +14,7 @@ The script below starts the app with the project's own command on a free port, w
 ## 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.
+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.
@@ -41,13 +41,18 @@ const CONFIG = {
     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 }) {
+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))
@@ -162,9 +167,18 @@ async function runAxe(page, axeSource) {
     }
 }
 
+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 browser.newContext({ viewport: { width, height: 900 } })
+    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()) })
@@ -175,7 +189,8 @@ async function checkPage(browser, url, path, width, axeSource) {
         const response = await page.goto(url, { waitUntil: 'load', timeout: CONFIG.navigationTimeoutMs })
         result.status = response?.status() ?? null
         await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {})
-        result.steps = await steps(page, { path, width })
+        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)
@@ -186,7 +201,7 @@ async function checkPage(browser, url, path, width, axeSource) {
     } catch (error) {
         result.error = String(error.message).split('\n')[0]
     } finally {
-        await context.close()
+        result.recording = recorder ? await recorder.closeRecorded(context) : await context.close()
     }
     return result
 }
@@ -236,15 +251,17 @@ main().catch(error => {
 
 ## 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. 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)).
+`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 }) {
+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')
 }
 ```
 
@@ -253,6 +270,7 @@ Steps that write data only touch the local app and whatever local database it us
 ## 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)).

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

@@ -1,6 +1,6 @@
 # Playwright patterns: locators, waiting, flakes, auth, mocking
 
-Read this when you write, fix or review browser tests or the `steps` of a headless check. 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.
+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
 

package/library/skills/ui-testing/references/recording.md

@@ -0,0 +1,57 @@
+# Recording the browser for the task
+
+Read this before any script that opens a browser during a TAMsense run. People on the task watch what your browser did: every page is recorded as a replay (the DOM, clicks and typing, played back in the TAMsense player) and attached to the task when the run ends.
+
+## What happens by itself
+
+- When the `TAMSENSE_RECORDER` environment variable is set, every Node process you start loads the TAMsense recorder, and every Playwright browser context is recorded, also the ones opened by the project's own E2E tests. You cannot switch this off, and you do not need to.
+- Requests from the tested site to the TAMsense tracker (`/api/events` with a `?key=` or sent to the TAMsense server) are answered by the recorder and never leave the browser, so your runs do not reach the product's analytics.
+- Password fields are masked in the replay.
+- Recordings you did not attach yourself are attached when the run ends. Unnamed ones get the step name as their title, so name yours.
+
+## What you add in every browser script
+
+Load the recorder and open each context through it, with a title and a purpose:
+
+```js
+import { createRequire } from 'node:module'
+
+const recorder = process.env.TAMSENSE_RECORDER ? createRequire(import.meta.url)(process.env.TAMSENSE_RECORDER) : null
+
+const context = recorder
+    ? await recorder.newRecordedContext(browser, {
+        title: 'Checkout testing, attempt 2',
+        purpose: 'Paying with a saved card after the fix to the total',
+        context: { viewport: { width: 1280, height: 900 } },
+    })
+    : await browser.newContext({ viewport: { width: 1280, height: 900 } })
+const page = await context.newPage()
+
+await page.goto(url)
+await recorder?.mark(page, 'Opened checkout')
+await page.getByRole('button', { name: 'Pay' }).click()
+await recorder?.mark(page, 'Paid, the receipt is shown')
+
+const recorded = recorder ? await recorder.closeRecorded(context) : await context.close()
+console.log(JSON.stringify(recorded, null, 2))
+```
+
+- `title`: what it shows, at most 60 characters. Number design variants ("Design option 1", "Design option 2") and name test runs by their goal and attempt ("Feature testing", "Second attempt at feature testing"). Never generic names like "screenshot1" or "test".
+- `purpose`: one line, at most 160 characters, on why it was made ("Comparing two layouts for the empty orders state").
+- `mark(page, label)`: call it at each meaningful step (opened a screen, submitted a form, saw the error). Marks show on the replay's timeline, and a click on one jumps there.
+- `closeRecorded(context)`: closes the context, finishes the files and returns where they are. Close every context this way, or at least with `context.close()`, before the script ends.
+- Without `TAMSENSE_RECORDER` (not a TAMsense run) the script works as before.
+
+## When to add a video
+
+A replay rebuilds the page from its DOM, so it cannot show pixels drawn by the page itself. Pass `video: true` to `newRecordedContext` as well when the screen has:
+
+- a `<canvas>` (charts drawn on canvas, editors, games), a map, or a `<video>` player;
+- iframes from another site (payment forms, embedded widgets);
+- or when someone in the chat asks for a video.
+
+`closeRecorded` warns when it saw a canvas, a video or a cross-origin iframe on a page recorded without video. Videos are larger (up to 200 MB each, 5 per run), so keep them short.
+
+## Attaching earlier
+
+Everything is attached at the end of the run. To attach a recording sooner, or with a better title, call `attach_replay` (the `.rrweb.ndjson` file) or `attach_video` (the `.webm` file) with the path from `closeRecorded`, a title and a purpose. A run attaches at most 20 replays and 5 videos; the ones you named come first.

package/package.json

@@ -1,45 +1,46 @@
-{
-    "name": "@tamsensedev/runner",
-    "type": "module",
-    "version": "0.1.0",
-    "description": "Connects your computer to TAMsense so it can work on your tasks",
-    "author": "TAMsense",
-    "license": "UNLICENSED",
-    "homepage": "https://my.tamsense.com",
-    "keywords": [
-        "tamsense",
-        "claude-code",
-        "agents",
-        "tasks"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "bin": {
-        "tamsense-runner": "./dist/cli.js"
-    },
-    "files": [
-        "dist",
-        "library"
-    ],
-    "engines": {
-        "node": ">=22"
-    },
-    "scripts": {
-        "build": "tsup",
-        "dev": "tsup --watch",
-        "clean": "rimraf dist",
-        "prepublishOnly": "tsup",
-        "test": "node --experimental-strip-types --no-warnings --import ./test/resolve.mjs --test \"test/*.test.ts\""
-    },
-    "dependencies": {
-        "@anthropic-ai/claude-agent-sdk": "^0.3.300",
-        "zod": "^4.0.0"
-    },
-    "devDependencies": {
-        "@types/node": "^22.0.0",
-        "rimraf": "^6.0.1",
-        "tsup": "^8.5.0",
-        "typescript": "^5.5.4"
-    }
-}
+{
+    "name": "@tamsensedev/runner",
+    "type": "module",
+    "version": "0.2.1",
+    "description": "Connects your computer to TAMsense so it can work on your tasks",
+    "author": "TAMsense",
+    "license": "UNLICENSED",
+    "homepage": "https://my.tamsense.com",
+    "keywords": [
+        "tamsense",
+        "claude-code",
+        "agents",
+        "tasks"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "bin": {
+        "tamsense-runner": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "library"
+    ],
+    "engines": {
+        "node": ">=22"
+    },
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "clean": "rimraf dist",
+        "prepublishOnly": "tsup",
+        "test": "node --experimental-strip-types --no-warnings --import ./test/resolve.mjs --test \"test/*.test.ts\""
+    },
+    "dependencies": {
+        "@anthropic-ai/claude-agent-sdk": "^0.3.300",
+        "rrweb": "2.0.0-alpha.20",
+        "zod": "^4.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.0.0",
+        "rimraf": "^6.0.1",
+        "tsup": "^8.5.0",
+        "typescript": "^5.5.4"
+    }
+}