pi-ui-extend 1.0.41 → 1.0.45

package/skills/playwright-cli/references/spec-driven-testing.md

@@ -1,311 +0,0 @@
-# Spec-driven testing (plan → generate → heal)
-
-End-to-end workflow for authoring and maintaining Playwright tests using `playwright-cli`. The three sections below can be used independently:
-
-- **Planning** — explore the app, produce a spec file describing what to test.
-- **Generate** — turn a spec into Playwright test files. Update the spec if it's vague or stale.
-- **Heal** — diagnose failing tests, fix the code, reconcile the spec with reality.
-
-All three lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics and [test-generation.md](test-generation.md) for how every `playwright-cli` action emits Playwright TypeScript.
-
-Each debug run owns two resources: the background test PID and the unique generated `tw-XXXX` session. Record both as soon as they exist. On success, failure, interruption, or timeout, detach that exact CLI session, stop and reap that exact PID, and verify the session name is absent from `playwright-cli list` before starting another run or responding. Never substitute `close-all` or `kill-all`, because other sessions may have different owners.
-
----
-
-## 1. Planning
-
-Goal: produce a spec file (e.g. `specs/<feature>.plan.md`) that enumerates the scenarios to test. **Always** write the spec to a file.
-
-### 1.1 Prerequisite: workspace
-
-Check the workspace has Playwright installed before anything else:
-
-```bash
-# Either of these confirms a workspace:
-test -f playwright.config.ts || test -f playwright.config.js
-npx --no-install playwright --version
-```
-
-If there is no Playwright install, bootstrap one and let the user pick the defaults:
-
-```bash
-npm init playwright@latest
-```
-
-### 1.2 Prerequisite: seed test
-
-A **seed test** is a minimal test that lands the page in the state every scenario starts from: navigation to the app, any required login, feature flags, etc. Scenarios assume a fresh start *after* the seed. `--debug=cli` pauses *inside* this test, so the seed is where every planning and generation session begins.
-
-Minimum viable seed:
-
-```ts
-// tests/seed.spec.ts
-import { test } from '@playwright/test';
-
-test('seed', async ({ page }) => {
-  await page.goto('https://example.com/');
-});
-```
-
-Preferred — push navigation into a fixture so scenario tests reuse it:
-
-```ts
-// tests/fixtures.ts
-import { test as baseTest } from '@playwright/test';
-export { expect } from '@playwright/test';
-
-export const test = baseTest.extend({
-  page: async ({ page }, use) => {
-    await page.goto('https://example.com/');
-    await use(page);
-  },
-});
-```
-
-```ts
-// tests/seed.spec.ts
-import { test } from './fixtures';
-
-test('seed', async ({ page }) => {
-  // Fixture already navigates. This empty body tells agents where to start.
-});
-```
-
-If no seed exists, create one that at least navigates to the app.
-
-### 1.3 Explore the app
-
-Launch the app via the seed in the background and attach:
-
-```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/seed.spec.ts --debug=cli > playwright-debug.log 2>&1 &
-TEST_PID=$!
-# wait for "Debugging Instructions" and the session name tw-XXXX
-playwright-cli attach tw-XXXX
-```
-
-Resume so the seed runs, then probe the app:
-
-```bash
-playwright-cli resume                   # resume so that seed test runs fully
-playwright-cli snapshot                 # inventory of interactive elements
-playwright-cli click e5                 # follow a flow
-playwright-cli eval "location.href"     # read URL / state
-playwright-cli show --annotate          # ask the user to point at something
-```
-
-Map out:
-
-- Interactive surfaces (forms, buttons, lists, filters, modals).
-- Primary user journeys end-to-end.
-- Edge cases: empty states, validation errors, very long input, boundary values.
-- Persistence: reload, local/session storage, URL fragments.
-- Navigation: which controls change the URL, back/forward behaviour.
-
-**Important**: Do not just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
-**Important**: When done exploring, run `playwright-cli -s=tw-XXXX detach`, stop and `wait` for `$TEST_PID`, then run `playwright-cli list` and verify `tw-XXXX` is absent.
-
-### 1.4 Write the spec file
-
-Save under `specs/<feature>.plan.md`. Use this structure:
-
-```markdown
-# <Feature> Test Plan
-
-## Application Overview
-
-<One paragraph describing what the feature does and why it matters.>
-
-## Test Scenarios
-
-### 1. <Group Name>
-
-**Seed:** `tests/seed.spec.ts`
-
-#### 1.1. <kebab-case-scenario-name>
-
-**File:** `tests/<group>/<kebab-case-scenario-name>.spec.ts`
-
-**Steps:**
-  1. <Concrete user step>
-    - expect: <observable outcome>
-    - expect: <another observable outcome>
-  2. <Next step>
-    - expect: <outcome>
-
-#### 1.2. <next-scenario>
-...
-
-### 2. <Next Group>
-
-**Seed:** `tests/seed.spec.ts`
-...
-```
-
-Guidelines:
-
-- Each scenario is independent and starts from the seed's fresh state — never chain scenarios.
-- Scenario names are kebab-case and match the test file name (`should-add-single-todo` → `should-add-single-todo.spec.ts`).
-- Cover happy path, edge cases, validation, negative flows, persistence.
-- Write steps at the user level ("Type 'Buy milk' into the input"), not the API level ("call `fill`").
-- Put observable outcomes in `- expect:` bullets; each becomes an assertion during generation.
-
----
-
-## 2. Generate
-
-Goal: take a spec file and produce Playwright test files. Optionally update the spec if it has drifted.
-
-### 2.1 Inputs
-
-- **Spec file**, e.g. `specs/basic-operations.plan.md`.
-- **Target**: either a single scenario (e.g. `1.2`), a whole group (`1`), or all.
-- **Seed file**, read from the `**Seed:**` line of the scenario's group.
-
-### 2.2 Generate one scenario
-
-For each target scenario, in sequence (never in parallel — scenarios share the seed session):
-
-```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test <seed-file> --debug=cli > playwright-debug.log 2>&1 &
-TEST_PID=$!
-# Read the log, register the generated session name, then attach.
-playwright-cli attach tw-XXXX
-# resume
-```
-
-**Do not** just open the app url with playwright-cli, always go through the test to capture any custom setup done there.
-
-Walk the scenario's `Steps:` one by one with `playwright-cli`, treating the spec as the plan and the live app as the source of truth. If a step is vague ("click the button" — which button?), references an element that no longer exists, or contradicts the app's actual behaviour, use your judgement: update the spec to match what the app really does, then keep going. Editing the spec mid-generation is expected.
-
-Every action prints the equivalent Playwright TypeScript (see [test-generation.md](test-generation.md)):
-
-```bash
-playwright-cli snapshot                         # find refs
-playwright-cli fill e3 "John Doe"               # -> page.getByRole('textbox', {...}).fill(...)
-playwright-cli press Enter
-playwright-cli click e7
-```
-
-For each `- expect:` bullet, add an explicit assertion. See [test-generation.md](test-generation.md) for details.
-
-Collect the generated code and write the test file at the path given in the spec:
-
-```ts
-// spec: specs/basic-operations.plan.md
-// seed: tests/seed.spec.ts
-import { test, expect } from './fixtures';   // or '@playwright/test' if no fixtures file
-
-test.describe('Singing in and out', () => {
-  test('should sign in', async ({ page }) => {
-    // 1. Navigate to the application
-    // (handled by the seed fixture)
-
-    // 2. Type 'John Doe' into the username field
-    await page.getByRole('textbox', { name: 'username' }).fill('John Doe');
-
-    // 3. Type password
-    await page.getByRole('textbox', { name: 'password' }).fill('TestPassword');
-
-    // 4. Press Enter to submit
-    await page.getByRole('textbox', { name: 'password' }).press('Enter');
-
-    await expect(page.getByRole('heading')).toContainText('Welcome, John Doe!');
-  });
-});
-```
-
-Rules:
-
-- **One test per file.** File path, describe name, and test name come verbatim from the spec (minus the ordinal).
-- Prefix each numbered step with a `// N. <step text>` comment before its actions.
-- Use the describe group name verbatim from the spec (no `1.` ordinal).
-- Import from `./fixtures` if the project has one; otherwise `@playwright/test`.
-- **Important**: detach the exact `tw-XXXX` CLI session, stop and reap `$TEST_PID`, and verify the session is absent from `playwright-cli list` before moving to the next scenario.
-
-### 2.3 Generate multiple scenarios
-
-Loop 2.2 over the targeted scenarios one at a time, restarting the seed between each so every test starts from a clean page. Keep this sequential as required above; unique generated names prevent collisions but do not replace per-run ownership and verified cleanup.
-
-### 2.4 Run generated tests
-
-After generation, run the new tests once:
-
-```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts
-```
-
-Any failure goes to Section 3.
-
----
-
-## 3. Heal
-
-Goal: fix failing tests, and update the spec if the app's intended behaviour changed.
-
-### 3.1 Find failing tests
-
-```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test
-```
-
-Record the list of failing `<file>:<line>` entries and process them one at a time. Do not attempt parallel fixes — shared state and the single CLI session make that fragile.
-
-### 3.2 Debug one failure
-
-Run the single failing test in debug mode in the background, then attach:
-
-```bash
-PLAYWRIGHT_HTML_OPEN=never npx playwright test tests/<group>/<scenario>.spec.ts:<line> --debug=cli > playwright-debug.log 2>&1 &
-TEST_PID=$!
-# wait for "Debugging Instructions" and the tw-XXXX session name
-playwright-cli attach tw-XXXX
-```
-
-The test is paused at the start. Step forward or run to until just before the failing action or assertion, then diagnose:
-
-```bash
-playwright-cli snapshot                # did the element change / move / rename?
-playwright-cli console                 # app-side errors?
-playwright-cli network                 # failed request? wrong payload?
-playwright-cli show --annotate         # ask the user to point somewhere
-```
-
-Common causes: selector drift, new wrapper element, label/ARIA rename, timing (transition, async load), assertion text updated in the app, test data leaking between runs.
-
-Rehearse the corrected interaction with `playwright-cli` — the generated code in the output is what you paste back into the test.
-
-### 3.3 Apply the fix
-
-Edit the test file: update the locator, assertion, step order, or inputs to match the corrected behaviour. Detach the exact generated CLI session, stop and reap the background debug PID, and verify the session name is absent from `playwright-cli list`. Then rerun the single test to confirm green.
-
-Never skip hooks or add sleeps as a fix. Never use `networkidle`.
-
-### 3.4 Reconcile with the spec
-
-Open the spec referenced by the `// spec:` header in the test file and locate the scenario that matches the test.
-
-- **Fix was purely technical** (locator drift, better assertion shape) and the spec's user-level behaviour still matches the app → leave the spec alone.
-- **Fix changed user-visible steps, inputs, order, or expected outcomes** that the spec describes → update the spec to match reality. Keep the scenario id and file path stable; only the step / expect lines change.
-- **Unclear whether the app change is intentional** (spec is stale) **or a regression** (test was right, app is wrong) → **stop and ask the user**. Provide:
-  - the scenario id (e.g. `2.3`),
-  - the spec lines that no longer match,
-  - the observed app behaviour (quote a snapshot excerpt or a concrete outcome).
-
-Only after the user answers, either update the spec (intentional change) or file/flag the test as covering a bug (regression).
-
-### 3.5 Iteration and giving up
-
-- Fix failures one at a time; rerun after each.
-- If after thorough investigation you are confident the test is correct but the app is wrong *and* the user has confirmed it's a bug: mark the test `test.fixme(...)` with a comment pointing at the user's decision or issue link. Never silently skip.
-
----
-
-## Cross-references
-
-| For... | See |
-|---|---|
-| `--debug=cli` / attach mechanics | [playwright-tests.md](playwright-tests.md) |
-| How `playwright-cli` actions become TS | [test-generation.md](test-generation.md) |
-| Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md) |
-| Managing the CLI browser session | [session-management.md](session-management.md) |

package/skills/playwright-cli/references/storage-state.md

@@ -1,290 +0,0 @@
-# Storage Management
-
-Manage cookies, localStorage, sessionStorage, and browser storage state.
-
-## Storage State
-
-Save and restore complete browser state including cookies and storage.
-
-### Save Storage State
-
-```bash
-# Save to auto-generated filename (storage-state-{timestamp}.json)
-playwright-cli state-save
-
-# Save to specific filename
-playwright-cli state-save my-auth-state.json
-```
-
-### Restore Storage State
-
-```bash
-SESSION="state-restore-$(date +%s)-$$"  # record as owned before first command
-# Load storage state from file
-playwright-cli -s="$SESSION" state-load my-auth-state.json
-
-# Reload page to apply cookies
-playwright-cli -s="$SESSION" open https://example.com
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-### Storage State File Format
-
-The saved file contains:
-
-```json
-{
-  "cookies": [
-    {
-      "name": "session_id",
-      "value": "abc123",
-      "domain": "example.com",
-      "path": "/",
-      "expires": 1735689600,
-      "httpOnly": true,
-      "secure": true,
-      "sameSite": "Lax"
-    }
-  ],
-  "origins": [
-    {
-      "origin": "https://example.com",
-      "localStorage": [
-        { "name": "theme", "value": "dark" },
-        { "name": "user_id", "value": "12345" }
-      ]
-    }
-  ]
-}
-```
-
-## Cookies
-
-### List All Cookies
-
-```bash
-playwright-cli cookie-list
-```
-
-### Filter Cookies by Domain
-
-```bash
-playwright-cli cookie-list --domain=example.com
-```
-
-### Filter Cookies by Path
-
-```bash
-playwright-cli cookie-list --path=/api
-```
-
-### Get Specific Cookie
-
-```bash
-playwright-cli cookie-get session_id
-```
-
-### Set a Cookie
-
-```bash
-# Basic cookie
-playwright-cli cookie-set session abc123
-
-# Cookie with options
-playwright-cli cookie-set session abc123 --domain=example.com --path=/ --httpOnly --secure --sameSite=Lax
-
-# Cookie with expiration (Unix timestamp)
-playwright-cli cookie-set remember_me token123 --expires=1735689600
-```
-
-### Delete a Cookie
-
-```bash
-playwright-cli cookie-delete session_id
-```
-
-### Clear All Cookies
-
-```bash
-playwright-cli cookie-clear
-```
-
-### Advanced: Multiple Cookies or Custom Options
-
-For complex scenarios like adding multiple cookies at once, use `run-code`:
-
-```bash
-playwright-cli run-code "async page => {
-  await page.context().addCookies([
-    { name: 'session_id', value: 'sess_abc123', domain: 'example.com', path: '/', httpOnly: true },
-    { name: 'preferences', value: JSON.stringify({ theme: 'dark' }), domain: 'example.com', path: '/' }
-  ]);
-}"
-```
-
-## Local Storage
-
-### List All localStorage Items
-
-```bash
-playwright-cli localstorage-list
-```
-
-### Get Single Value
-
-```bash
-playwright-cli localstorage-get token
-```
-
-### Set Value
-
-```bash
-playwright-cli localstorage-set theme dark
-```
-
-### Set JSON Value
-
-```bash
-playwright-cli localstorage-set user_settings '{"theme":"dark","language":"en"}'
-```
-
-### Delete Single Item
-
-```bash
-playwright-cli localstorage-delete token
-```
-
-### Clear All localStorage
-
-```bash
-playwright-cli localstorage-clear
-```
-
-### Advanced: Multiple Operations
-
-For complex scenarios like setting multiple values at once, use `run-code`:
-
-```bash
-playwright-cli run-code "async page => {
-  await page.evaluate(() => {
-    localStorage.setItem('token', 'jwt_abc123');
-    localStorage.setItem('user_id', '12345');
-    localStorage.setItem('expires_at', Date.now() + 3600000);
-  });
-}"
-```
-
-## Session Storage
-
-### List All sessionStorage Items
-
-```bash
-playwright-cli sessionstorage-list
-```
-
-### Get Single Value
-
-```bash
-playwright-cli sessionstorage-get form_data
-```
-
-### Set Value
-
-```bash
-playwright-cli sessionstorage-set step 3
-```
-
-### Delete Single Item
-
-```bash
-playwright-cli sessionstorage-delete step
-```
-
-### Clear sessionStorage
-
-```bash
-playwright-cli sessionstorage-clear
-```
-
-## IndexedDB
-
-### List Databases
-
-```bash
-playwright-cli run-code "async page => {
-  return await page.evaluate(async () => {
-    const databases = await indexedDB.databases();
-    return databases;
-  });
-}"
-```
-
-### Delete Database
-
-```bash
-playwright-cli run-code "async page => {
-  await page.evaluate(() => {
-    indexedDB.deleteDatabase('myDatabase');
-  });
-}"
-```
-
-## Common Patterns
-
-### Authentication State Reuse
-
-```bash
-# Step 1: Login and save state
-LOGIN_SESSION="auth-save-$(date +%s)-$$"
-playwright-cli -s="$LOGIN_SESSION" open https://app.example.com/login
-playwright-cli -s="$LOGIN_SESSION" snapshot
-playwright-cli -s="$LOGIN_SESSION" fill e1 "user@example.com"
-playwright-cli -s="$LOGIN_SESSION" fill e2 "password123"
-playwright-cli -s="$LOGIN_SESSION" click e3
-
-# Save the authenticated state
-playwright-cli -s="$LOGIN_SESSION" state-save auth.json
-playwright-cli -s="$LOGIN_SESSION" close
-playwright-cli list  # verify $LOGIN_SESSION is absent
-
-# Step 2: Later, restore state and skip login
-RESTORE_SESSION="auth-restore-$(date +%s)-$$"
-playwright-cli -s="$RESTORE_SESSION" state-load auth.json
-playwright-cli -s="$RESTORE_SESSION" open https://app.example.com/dashboard
-# Already logged in!
-playwright-cli -s="$RESTORE_SESSION" close
-playwright-cli list  # verify $RESTORE_SESSION is absent
-```
-
-### Save and Restore Roundtrip
-
-```bash
-# Set up authentication state
-SAVE_SESSION="state-save-$(date +%s)-$$"
-playwright-cli -s="$SAVE_SESSION" open https://example.com
-playwright-cli -s="$SAVE_SESSION" eval "() => { document.cookie = 'session=abc123'; localStorage.setItem('user', 'john'); }"
-
-# Save state to file
-playwright-cli -s="$SAVE_SESSION" state-save my-session.json
-playwright-cli -s="$SAVE_SESSION" close
-playwright-cli list  # verify $SAVE_SESSION is absent
-
-# ... later, in a new session ...
-
-# Restore state
-LOAD_SESSION="state-load-$(date +%s)-$$"
-playwright-cli -s="$LOAD_SESSION" state-load my-session.json
-playwright-cli -s="$LOAD_SESSION" open https://example.com
-# Cookies and localStorage are restored!
-playwright-cli -s="$LOAD_SESSION" close
-playwright-cli list  # verify $LOAD_SESSION is absent
-```
-
-## Security Notes
-
-- Never commit storage state files containing auth tokens
-- Add `*.auth-state.json` to `.gitignore`
-- Delete state files after automation completes
-- Use environment variables for sensitive data
-- By default, sessions run in-memory mode which is safer for sensitive operations