ld
52dd56ff06
- feat: add `.agents/skills/playwright-cli/` with complete Skill markdown, agent interface, and 9 reference files covering session management, spec-driven testing, video recording, tracing, storage, request mocking, element attributes, test debugging, and running custom code - feat: add `.playwright/cli.config.json` to configure the Playwright CLI - feat: add `web/package.json` `playwright:cli` script that resolves `playwright cli` from the repo root - build: remove `@playwright/mcp` dependency from `web/package.json` - build: set `XDG_CACHE_HOME` in `mise.toml` - build: delete `.codex/config.toml` (MCP server config) - docs: update `README.md`, `docs/web/roadmap.md`, `docs/web/decisions.md`, and `web/README.md` to reflect the new Playwright CLI approach
140 lines
3.9 KiB
Markdown
140 lines
3.9 KiB
Markdown
# Tracing
|
|
|
|
Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
# Start trace recording
|
|
mise exec -- npm run playwright:cli -- tracing-start
|
|
|
|
# Perform actions
|
|
mise exec -- npm run playwright:cli -- open https://example.com
|
|
mise exec -- npm run playwright:cli -- click e1
|
|
mise exec -- npm run playwright:cli -- fill e2 "test"
|
|
|
|
# Stop trace recording
|
|
mise exec -- npm run playwright:cli -- tracing-stop
|
|
```
|
|
|
|
## 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
|
|
mise exec -- npm run playwright:cli -- tracing-start
|
|
mise exec -- npm run playwright:cli -- open https://app.example.com
|
|
|
|
# This click fails - why?
|
|
mise exec -- npm run playwright:cli -- click e5
|
|
|
|
mise exec -- npm run playwright:cli -- tracing-stop
|
|
# Open trace to see DOM state when click was attempted
|
|
```
|
|
|
|
### Analyzing Performance
|
|
|
|
```bash
|
|
mise exec -- npm run playwright:cli -- tracing-start
|
|
mise exec -- npm run playwright:cli -- open https://slow-site.com
|
|
mise exec -- npm run playwright:cli -- tracing-stop
|
|
|
|
# View network waterfall to identify slow resources
|
|
```
|
|
|
|
### Capturing Evidence
|
|
|
|
```bash
|
|
# Record a complete user flow for documentation
|
|
mise exec -- npm run playwright:cli -- tracing-start
|
|
|
|
mise exec -- npm run playwright:cli -- open https://app.example.com/checkout
|
|
mise exec -- npm run playwright:cli -- fill e1 "4111111111111111"
|
|
mise exec -- npm run playwright:cli -- fill e2 "12/25"
|
|
mise exec -- npm run playwright:cli -- fill e3 "123"
|
|
mise exec -- npm run playwright:cli -- click e4
|
|
|
|
mise exec -- npm run playwright:cli -- tracing-stop
|
|
# 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
|
|
mise exec -- npm run playwright:cli -- tracing-start
|
|
mise exec -- npm run playwright:cli -- open https://example.com
|
|
# ... all steps leading to the issue ...
|
|
mise exec -- npm run playwright:cli -- tracing-stop
|
|
```
|
|
|
|
### 2. Clean Up Old Traces
|
|
|
|
Traces can consume significant disk space:
|
|
|
|
```bash
|
|
# Remove traces older than 7 days
|
|
find ../.artifacts/playwright-cli -type f -mtime +7 -delete
|
|
```
|
|
|
|
## Limitations
|
|
|
|
- Traces add overhead to automation
|
|
- Large traces can consume significant disk space
|
|
- Some dynamic content may not replay perfectly
|