pi-ui-extend 1.0.41 → 1.0.45

package/skills/playwright-cli/references/test-generation.md

@@ -1,142 +0,0 @@
-# Test Generation
-
-Generate Playwright test code automatically as you interact with the browser.
-
-## How It Works
-
-Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
-This code appears in the output and can be copied directly into your test files.
-
-## Example Workflow
-
-```bash
-# Choose a unique name, record it as owned by this task, and start the session.
-SESSION="testgen-login-$(date +%s)-$$"
-playwright-cli -s="$SESSION" open https://example.com/login
-
-# Take a snapshot to see elements
-playwright-cli -s="$SESSION" snapshot
-# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
-
-# Fill form fields - generates code automatically
-playwright-cli -s="$SESSION" fill e1 "user@example.com"
-# Ran Playwright code:
-# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
-
-playwright-cli -s="$SESSION" fill e2 "password123"
-# Ran Playwright code:
-# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
-
-playwright-cli -s="$SESSION" click e3
-# Ran Playwright code:
-# await page.getByRole('button', { name: 'Sign In' }).click();
-
-# Mandatory on success and errors.
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-## Building a Test File
-
-Collect the generated code into a Playwright test:
-
-```typescript
-import { test, expect } from '@playwright/test';
-
-test('login flow', async ({ page }) => {
-  // Generated code from playwright-cli session:
-  await page.goto('https://example.com/login');
-  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
-  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
-  await page.getByRole('button', { name: 'Sign In' }).click();
-
-  // Add assertions
-  await expect(page).toHaveURL(/.*dashboard/);
-});
-```
-
-## Best Practices
-
-### 1. Use Semantic Locators
-
-The generated code uses role-based locators when possible, which are more resilient:
-
-```typescript
-// Generated (good - semantic)
-await page.getByRole('button', { name: 'Submit' }).click();
-
-// Avoid (fragile - CSS selectors)
-await page.locator('#submit-btn').click();
-```
-
-### 2. Explore Before Recording
-
-Take snapshots to understand the page structure before recording actions:
-
-```bash
-SESSION="testgen-explore-$(date +%s)-$$"
-playwright-cli -s="$SESSION" open https://example.com
-playwright-cli -s="$SESSION" snapshot
-# Review the element structure
-playwright-cli -s="$SESSION" click e5
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-### 3. Add Assertions Manually
-
-Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
-
-- `toBeVisible()` — element is rendered and visible
-- `toHaveText(text)` — element text content matches
-- `toHaveValue(value) / toBeEmpty()` — input/select value matches
-- `toBeChecked() / toBeUnchecked()` — checkbox state matches
-- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
-
-Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
-
-When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
-
-Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
-
-```bash
-# Get a stable locator for an element ref to use in the assertion
-playwright-cli --raw generate-locator e5
-# getByRole('button', { name: 'Submit' })
-
-# Capture expected text content for toHaveText
-playwright-cli --raw eval "el => el.textContent" e5
-
-# Capture expected input value for toHaveValue/toBeEmpty
-playwright-cli --raw eval "el => el.value" e5
-
-# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
-# (whole page, or use a ref to scope to a region)
-playwright-cli --raw snapshot
-playwright-cli --raw snapshot e5
-```
-
-```typescript
-// Generated action
-await page.getByRole('button', { name: 'Submit' }).click();
-
-// Manual assertions using the outputs above:
-await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();
-await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');
-await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('user@example.com');
-await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();
-
-// toMatchAriaSnapshot on the whole page, finds a matching region
-await expect(page).toMatchAriaSnapshot(`
-  - heading "Welcome, user"
-  - link /\\d+ new messages?/
-  - button "Sign out"
-`);
-
-// toMatchAriaSnapshot scoped to a region
-await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
-  - link "Home"
-  - link /\\d+ new messages?/
-  - link "Profile"
-`);
-```

package/skills/playwright-cli/references/tracing.md

@@ -1,154 +0,0 @@
-# Tracing
-
-Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
-
-## Basic Usage
-
-```bash
-SESSION="trace-basic-$(date +%s)-$$"  # record as owned before first command
-# Start trace recording
-playwright-cli -s="$SESSION" tracing-start
-
-# Perform actions
-playwright-cli -s="$SESSION" open https://example.com
-playwright-cli -s="$SESSION" click e1
-playwright-cli -s="$SESSION" fill e2 "test"
-
-# Stop trace recording
-playwright-cli -s="$SESSION" tracing-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-## Trace Output Files
-
-When you start tracing, Playwright creates a `traces/` directory with several files:
-
-### `trace-{timestamp}.trace`
-
-**Action log** - The main trace file containing:
-- Every action performed (clicks, fills, navigations)
-- DOM snapshots before and after each action
-- Screenshots at each step
-- Timing information
-- Console messages
-- Source locations
-
-### `trace-{timestamp}.network`
-
-**Network log** - Complete network activity:
-- All HTTP requests and responses
-- Request headers and bodies
-- Response headers and bodies
-- Timing (DNS, connect, TLS, TTFB, download)
-- Resource sizes
-- Failed requests and errors
-
-### `resources/`
-
-**Resources directory** - Cached resources:
-- Images, fonts, stylesheets, scripts
-- Response bodies for replay
-- Assets needed to reconstruct page state
-
-## What Traces Capture
-
-| Category | Details |
-|----------|---------|
-| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
-| **DOM** | Full DOM snapshot before/after each action |
-| **Screenshots** | Visual state at each step |
-| **Network** | All requests, responses, headers, bodies, timing |
-| **Console** | All console.log, warn, error messages |
-| **Timing** | Precise timing for each operation |
-
-## Use Cases
-
-### Debugging Failed Actions
-
-```bash
-SESSION="trace-failure-$(date +%s)-$$"
-playwright-cli -s="$SESSION" tracing-start
-playwright-cli -s="$SESSION" open https://app.example.com
-
-# This click fails - why?
-playwright-cli -s="$SESSION" click e5
-
-playwright-cli -s="$SESSION" tracing-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-# Open trace to see DOM state when click was attempted
-```
-
-### Analyzing Performance
-
-```bash
-SESSION="trace-performance-$(date +%s)-$$"
-playwright-cli -s="$SESSION" tracing-start
-playwright-cli -s="$SESSION" open https://slow-site.com
-playwright-cli -s="$SESSION" tracing-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-
-# View network waterfall to identify slow resources
-```
-
-### Capturing Evidence
-
-```bash
-# Record a complete user flow for documentation
-SESSION="trace-evidence-$(date +%s)-$$"
-playwright-cli -s="$SESSION" tracing-start
-
-playwright-cli -s="$SESSION" open https://app.example.com/checkout
-playwright-cli -s="$SESSION" fill e1 "4111111111111111"
-playwright-cli -s="$SESSION" fill e2 "12/25"
-playwright-cli -s="$SESSION" fill e3 "123"
-playwright-cli -s="$SESSION" click e4
-
-playwright-cli -s="$SESSION" tracing-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-# Trace shows exact sequence of events
-```
-
-## Trace vs Video vs Screenshot
-
-| Feature | Trace | Video | Screenshot |
-|---------|-------|-------|------------|
-| **Format** | .trace file | .webm video | .png/.jpeg image |
-| **DOM inspection** | Yes | No | No |
-| **Network details** | Yes | No | No |
-| **Step-by-step replay** | Yes | Continuous | Single frame |
-| **File size** | Medium | Large | Small |
-| **Best for** | Debugging | Demos | Quick capture |
-
-## Best Practices
-
-### 1. Start Tracing Before the Problem
-
-```bash
-# Trace the entire flow, not just the failing step
-SESSION="trace-flow-$(date +%s)-$$"
-playwright-cli -s="$SESSION" tracing-start
-playwright-cli -s="$SESSION" open https://example.com
-# ... all steps leading to the issue ...
-playwright-cli -s="$SESSION" tracing-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-### 2. Clean Up Old Traces
-
-Traces can consume significant disk space:
-
-```bash
-# Remove traces older than 7 days
-find .playwright-cli/traces -mtime +7 -delete
-```
-
-## Limitations
-
-- Traces add overhead to automation
-- Large traces can consume significant disk space
-- Some dynamic content may not replay perfectly

package/skills/playwright-cli/references/video-recording.md

@@ -1,147 +0,0 @@
-# Video Recording
-
-Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
-
-## Basic Recording
-
-```bash
-# Choose a unique name and record it as owned before opening.
-SESSION="video-demo-$(date +%s)-$$"
-# Open browser first
-playwright-cli -s="$SESSION" open
-
-# Start recording
-playwright-cli -s="$SESSION" video-start demo.webm
-
-# Add a chapter marker for section transitions
-playwright-cli -s="$SESSION" video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
-
-# Navigate and perform actions
-playwright-cli -s="$SESSION" goto https://example.com
-playwright-cli -s="$SESSION" snapshot
-playwright-cli -s="$SESSION" click e1
-
-# Add another chapter
-playwright-cli -s="$SESSION" video-chapter "Filling Form" --description="Entering test data" --duration=2000
-playwright-cli -s="$SESSION" fill e2 "test input"
-
-# Stop and save
-playwright-cli -s="$SESSION" video-stop
-playwright-cli -s="$SESSION" close
-playwright-cli list  # verify $SESSION is absent
-```
-
-## Best Practices
-
-### 1. Use Descriptive Filenames
-
-```bash
-# Include context in filename
-playwright-cli video-start recordings/login-flow-2024-01-15.webm
-playwright-cli video-start recordings/checkout-test-run-42.webm
-```
-
-### 2. Record entire hero scripts.
-
-When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
-It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
-
-1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
-2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
-3) In the task-owned unique session, use `playwright-cli -s="$SESSION" run-code --filename your-script.js`, then close that exact session and verify it is absent from `playwright-cli list`, including on errors.
-
-**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
-
-```js
-async page => {
-  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
-  await page.goto('https://demo.playwright.dev/todomvc');
-
-  // Show a chapter card — blurs the page and shows a dialog.
-  // Blocks until duration expires, then auto-removes.
-  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
-  // overlay via await page.screencast.showOverlay().
-  await page.screencast.showChapter('Adding Todo Items', {
-    description: 'We will add several items to the todo list.',
-    duration: 2000,
-  });
-
-  // Perform action
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
-  await page.waitForTimeout(1000);
-
-  // Show next chapter
-  await page.screencast.showChapter('Verifying Results', {
-    description: 'Checking the item appeared in the list.',
-    duration: 2000,
-  });
-
-  // Add a sticky annotation that stays while you perform actions.
-  // Overlays are pointer-events: none, so they won't block clicks.
-  const annotation = await page.screencast.showOverlay(`
-    <div style="position: absolute; top: 8px; right: 8px;
-      padding: 6px 12px; background: rgba(0,0,0,0.7);
-      border-radius: 8px; font-size: 13px; color: white;">
-      ✓ Item added successfully
-    </div>
-  `);
-
-  // Perform more actions while the annotation is visible
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
-  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
-  await page.waitForTimeout(1500);
-
-  // Remove the annotation when done
-  await annotation.dispose();
-
-  // You can also highlight relevant locators and provide contextual annotations.
-  const bounds = await page.getByText('Walk the dog').boundingBox();
-  await page.screencast.showOverlay(`
-    <div style="position: absolute;
-      top: ${bounds.y}px;
-      left: ${bounds.x}px;
-      width: ${bounds.width}px;
-      height: ${bounds.height}px;
-      border: 1px solid red;">
-    </div>
-    <div style="position: absolute;
-      top: ${bounds.y + bounds.height + 5}px;
-      left: ${bounds.x + bounds.width / 2}px;
-      transform: translateX(-50%);
-      padding: 6px;
-      background: #808080;
-      border-radius: 10px;
-      font-size: 14px;
-      color: white;">Check it out, it is right above this text
-    </div>
-  `, { duration: 2000 });
-
-  await page.screencast.stop();
-}
-```
-
-Embrace creativity, overlays are powerful.
-
-### Overlay API Summary
-
-| Method | Use Case |
-|--------|----------|
-| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
-| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
-| `disposable.dispose()` | Remove a sticky overlay added without duration |
-| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
-
-## Tracing vs Video
-
-| Feature | Video | Tracing |
-|---------|-------|---------|
-| Output | WebM file | Trace file (viewable in Trace Viewer) |
-| Shows | Visual recording | DOM snapshots, network, console, actions |
-| Use case | Demos, documentation | Debugging, analysis |
-| Size | Larger | Smaller |
-
-## Limitations
-
-- Recording adds slight overhead to automation
-- Large recordings can consume significant disk space

package/skills/spec-lite/SKILL.md

@@ -1,140 +0,0 @@
----
-name: spec-lite
-description: Use this skill for creating, updating, or checking lightweight specs for existing code, risky changes, public behavior, bug fixes, or spec-code drift. Use it before or during non-trivial changes that touch security, data, persistence, public APIs, CLI/UI contracts, integrations, concurrency, architecture, or user-visible behavior with edge cases. Do not use it for trivial local edits.
-argument-hint: "behavior, change, bug, or spec path to document/check"
----
-
-# Spec Lite
-
-Use the lightest spec process that preserves correctness. The goal is to make behavior and risk explicit without turning every change into a heavyweight design process.
-
-## Core rules
-
-- Do not change production code unless the user explicitly asks for implementation.
-- Specs describe either current behavior or intended behavior; label which one clearly.
-- Do not invent behavior. If evidence is missing or ambiguous, mark uncertainty explicitly.
-- Prefer compact specs over exhaustive documents.
-- Load only relevant files, tests, schemas, docs, migrations, entrypoints, and existing specs.
-- Do not load all specs by default.
-- Keep the spec close to the codebase convention when a specs directory, ADR folder, or feature-doc pattern already exists.
-
-## When to create or update a spec
-
-Create or update a lightweight spec when the work affects any of these areas:
-
-- security, privacy, auth, or permissions;
-- data, schemas, migrations, persistence, or file formats;
-- public APIs, CLI behavior, UI contracts, events, or other external contracts;
-- external integrations;
-- payments, destructive operations, or irreversible workflows;
-- background jobs, concurrency, cancellation, retries, or async behavior;
-- cross-cutting architecture;
-- user-visible behavior with non-trivial edge cases;
-- bug fixes where expected behavior, compatibility, or regression risk is unclear;
-- suspected drift between existing specs/docs/tests and code.
-
-Do not require a spec for trivial local edits, mechanical renames, formatting-only changes, or obvious one-file fixes with no broader behavior impact.
-
-## As-is spec workflow
-
-Use this workflow for existing code or spec-code drift checks:
-
-1. Identify the narrow behavior or contract to document.
-2. Inspect relevant code, tests, docs, schemas, migrations, and entrypoints.
-3. Identify current behavior and known gaps.
-4. Mark claims using evidence labels:
-   - confirmed by code;
-   - confirmed by tests;
-   - confirmed by docs;
-   - inferred;
-   - unknown.
-5. Create or update a compact as-is spec.
-6. If drift is found, report it separately from confirmed behavior.
-
-## Change spec workflow
-
-Use this workflow before risky implementation:
-
-1. Define the goal.
-2. Define scope and non-goals.
-3. State expected behavior.
-4. List affected contracts.
-5. List risks, compatibility concerns, and migration concerns if any.
-6. Define a verification path.
-7. Then implement only the scoped change, if implementation was requested.
-
-## Spec template
-
-Use this template by default. Remove sections that are genuinely irrelevant, but keep `Type`, `Goal`, `Behavior`, `Related files`, `Verification`, and `Evidence` when possible.
-
-```markdown
-# Spec: <name>
-
-## Type
-
-As-is | Change
-
-## Goal
-
-...
-
-## Scope
-
-...
-
-## Non-goals
-
-...
-
-## Behavior
-
-...
-
-## Contracts
-
-Inputs, outputs, APIs, CLI, UI, events, files, schemas.
-
-## Invariants
-
-...
-
-## Edge cases
-
-...
-
-## Side effects
-
-...
-
-## Related files
-
-...
-
-## Verification
-
-...
-
-## Risks / unknowns
-
-...
-
-## Evidence
-
-- Confirmed by code:
-- Confirmed by tests:
-- Confirmed by docs:
-- Inferred:
-- Unknown:
-```
-
-## Output guidance
-
-When the user asks only for a spec, write or update the spec and summarize:
-
-- spec path;
-- whether it is as-is or change-oriented;
-- strongest evidence sources;
-- important unknowns or drift;
-- whether production code was left untouched.
-
-When the user asks for implementation too, keep the spec scoped and practical, then implement only after the expected behavior and verification path are clear.