@tamsensedev/runner 0.10.0 → 0.18.0

package/library/skills/ui-testing/references/local-stand.md

@@ -1,51 +1,51 @@
-# Starting a local copy of the app
-
-Read this before you start the app for a check. In a TAMsense run the task folder is a fresh checkout: no dependencies, no `.env`, nothing running. You set up a local copy from this checkout yourself, every time, and you take it down at the end. The person's own setup, their databases and every shared server stay untouched.
-
-## The rules
-
-1. **This task folder only.** Everything you start comes from the checkout in the task folder. Never read or copy `.env` files, keys or settings from elsewhere on this computer, including the person's own checkout of the same project.
-2. **Find the local setup yourself.** Look in the README, compose files named local or dev (`docker-compose.local.yml`, `infra/compose/local.compose.yml`, `compose.dev.yaml`), `.env.example` and other env files meant for a local run (`.env.local.example`, `.env.development`), and the package scripts (`dev`, `db:migrate`, `db:seed`). The CI workflow often shows the exact services and commands.
-3. **Check every address before you start.** In the settings you use, databases, caches, queues and APIs must point at `localhost`, `127.0.0.1` or containers you start. A staging, shared dev or production address, or a cloud host you do not start, means stop (rule 7). Keys of outside services (payments, mail, analytics, storage, AI APIs) stay empty; never fill them with real ones. Check variables by name and address only; never print secrets.
-4. **Your own compose project on free ports.** Start containers as a separate compose project named `tamsense-task-<task id>`, so they never mix with the person's containers. Map them to free host ports with an override file in a temp folder, not by editing the project's files. Find a free port by asking the system (`node -e "const s=require('net').createServer().listen(0,()=>{console.log(s.address().port);s.close()})"`).
-5. **Never touch containers you did not start.** Do not stop, restart, remove or change other containers, volumes or networks, even when a port is taken: pick another port.
-6. **Clean up.** At the end run `docker compose -p tamsense-task-<task id> down -v` with the same files, stop the app by its process id, and delete the temp folder.
-7. **When it cannot run, stop.** If Docker is not running, the project has no local setup, or the settings point outside this computer, do not start anything and do not look for a workaround. In a check step, call `submit_verdict` with `passed: false` and `couldNotRun: true`, write the exact reason and what a person should do in the report ("Docker is not running: start Docker Desktop and run this step again"), and do not hand off. The task then waits on this step for a person. In a code step, say so in your report.
-
-The browser adds a guard of its own: requests other than GET, HEAD and OPTIONS to an address outside this computer are aborted (see [recording.md](recording.md)). It does not replace rule 3: the app's server talks to its database and services directly.
-
-## Example
-
-Task 40, a project with `infra/compose/local.compose.yml` (postgres and redis), `.env.example` pointing at `localhost:5432` and `localhost:6379`, and a `dev` script.
-
-```bash
-docker info --format '{{.ServerVersion}}'   # an error here means Docker is not running: stop (rule 7)
-TMP=$(node -p "require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'tamsense-task-40-'))")
-
-# free host ports for the two services, found as in rule 4
-cat > "$TMP/ports.override.yml" <<'EOF'
-services:
-  postgres:
-    ports: !override
-      - "55432:5432"
-  redis:
-    ports: !override
-      - "56379:6379"
-EOF
-
-docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" up -d postgres redis
-
-pnpm install --frozen-lockfile
-# settings from .env.example, with the ports changed to the free ones, passed as variables, not written into the repository
-export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/app REDIS_URL=redis://localhost:56379
-pnpm db:migrate                              # migrations go to the local database only
-BROWSER=none pnpm dev --port 53100           # the project's own dev script on a free port; note its process id
-
-# ... the headless check against http://localhost:53100 ...
-
-# stop the dev server by its process id, then
-docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" down -v
-rm -rf "$TMP"
-```
-
-Before `db:migrate`, look at the address once more: `DATABASE_URL` must name `localhost` and the port of your container. `!override` (Docker Compose 2.24 or newer) replaces the project's own port list instead of adding to it, so nothing binds the ports the person's own containers may use.
+# Starting a local copy of the app
+
+Read this before you start the app for a check. In a TAMsense run the task folder is a fresh checkout: no dependencies, no `.env`, nothing running. You set up a local copy from this checkout yourself, every time, and you take it down at the end. The person's own setup, their databases and every shared server stay untouched.
+
+## The rules
+
+1. **This task folder only.** Everything you start comes from the checkout in the task folder. Never read or copy `.env` files, keys or settings from elsewhere on this computer, including the person's own checkout of the same project.
+2. **Find the local setup yourself.** Look in the README, compose files named local or dev (`docker-compose.local.yml`, `infra/compose/local.compose.yml`, `compose.dev.yaml`), `.env.example` and other env files meant for a local run (`.env.local.example`, `.env.development`), and the package scripts (`dev`, `db:migrate`, `db:seed`). The CI workflow often shows the exact services and commands.
+3. **Check every address before you start.** In the settings you use, databases, caches, queues and APIs must point at `localhost`, `127.0.0.1` or containers you start. A staging, shared dev or production address, or a cloud host you do not start, means stop (rule 7). Keys of outside services (payments, mail, analytics, storage, AI APIs) stay empty; never fill them with real ones. Check variables by name and address only; never print secrets.
+4. **Your own compose project on free ports.** Start containers as a separate compose project named `tamsense-task-<task id>`, so they never mix with the person's containers. Map them to free host ports with an override file in a temp folder, not by editing the project's files. Find a free port by asking the system (`node -e "const s=require('net').createServer().listen(0,()=>{console.log(s.address().port);s.close()})"`).
+5. **Never touch containers you did not start.** Do not stop, restart, remove or change other containers, volumes or networks, even when a port is taken: pick another port.
+6. **Clean up.** At the end run `docker compose -p tamsense-task-<task id> down -v` with the same files, stop the app by its process id, and delete the temp folder.
+7. **When it cannot run, stop.** If Docker is not running, the project has no local setup, or the settings point outside this computer, do not start anything and do not look for a workaround. In a check step, call `submit_verdict` with `passed: false` and `couldNotRun: true`, write the exact reason and what a person should do in the report ("Docker is not running: start Docker Desktop and run this step again"), and do not hand off. The task then waits on this step for a person. In a code step, say so in your report.
+
+The browser adds a guard of its own: requests other than GET, HEAD and OPTIONS to an address outside this computer are aborted (see [recording.md](recording.md)). It does not replace rule 3: the app's server talks to its database and services directly.
+
+## Example
+
+Task 40, a project with `infra/compose/local.compose.yml` (postgres and redis), `.env.example` pointing at `localhost:5432` and `localhost:6379`, and a `dev` script.
+
+```bash
+docker info --format '{{.ServerVersion}}'   # an error here means Docker is not running: stop (rule 7)
+TMP=$(node -p "require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'tamsense-task-40-'))")
+
+# free host ports for the two services, found as in rule 4
+cat > "$TMP/ports.override.yml" <<'EOF'
+services:
+  postgres:
+    ports: !override
+      - "55432:5432"
+  redis:
+    ports: !override
+      - "56379:6379"
+EOF
+
+docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" up -d postgres redis
+
+pnpm install --frozen-lockfile
+# settings from .env.example, with the ports changed to the free ones, passed as variables, not written into the repository
+export DATABASE_URL=postgresql://postgres:postgres@localhost:55432/app REDIS_URL=redis://localhost:56379
+pnpm db:migrate                              # migrations go to the local database only
+BROWSER=none pnpm dev --port 53100           # the project's own dev script on a free port; note its process id
+
+# ... the headless check against http://localhost:53100 ...
+
+# stop the dev server by its process id, then
+docker compose -p tamsense-task-40 -f infra/compose/local.compose.yml -f "$TMP/ports.override.yml" down -v
+rm -rf "$TMP"
+```
+
+Before `db:migrate`, look at the address once more: `DATABASE_URL` must name `localhost` and the port of your container. `!override` (Docker Compose 2.24 or newer) replaces the project's own port list instead of adding to it, so nothing binds the ports the person's own containers may use.

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

@@ -1,134 +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.
+# 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.

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

@@ -1,58 +1,61 @@
-# 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.
-- Requests other than GET, HEAD and OPTIONS to an address outside this computer (anything but `localhost`, `*.localhost` and loopback addresses) are aborted, so a test run never writes to an outside service. The summary from `closeRecorded` counts them in `blockedExternalWrites`. If a flow you check needs such a write, it was set up against an outside service: say so instead of working around it.
-- 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.
+# 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.
+- Requests other than GET, HEAD and OPTIONS to an address outside this computer (anything but `localhost`, `*.localhost` and loopback addresses) are aborted, so a test run never writes to an outside service. The summary from `closeRecorded` counts them in `blockedExternalWrites`. If a flow you check needs such a write, it was set up against an outside service: say so instead of working around it.
+- 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.
+- The task shows who made each recording: your role, the step, the round and the computer. You do not write that yourself.
+
+## 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 notes = 'Opened checkout with a saved card and clicked Pay. Expected the receipt with the corrected total of $42: it showed $42. Passed.'
+const recorded = recorder ? await recorder.closeRecorded(context, { notes }) : 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, { notes })`: 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.
+- `notes`: what you tested in this browser and what happened, in your own words, at most 600 characters: what you opened, what you clicked or typed, what you expected, and whether it passed or failed. People see them on the replay card and above the player before they press play, so write them for someone who did not read your report. Write them after the steps ran, from what you actually saw. A recording without notes shows the marks you set instead, and without marks, "No notes from the agent".
+- 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, a purpose and notes (the notes you gave `closeRecorded` are used when you leave them out). A run attaches at most 20 replays and 5 videos; the ones you named come first.