Package Exports

playwright-recording-annotator
playwright-recording-annotator/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (playwright-recording-annotator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

🎬 Playwright Recording Annotator

Real-time annotation tool for Playwright recordings that captures complete context for AI-powered test generation.

The Problem

Playwright's codegen has critical limitations that make AI-powered test generation ineffective:

1. Many Actions Simply Aren't Recorded

Drag & drop operations - No codegen support, requires manual implementation
Hover states & tooltips - Often missed or incorrectly captured
Complex mouse interactions - Multi-click, mouse drag sequences lost
Keyboard shortcuts - Modifier keys (Alt, Ctrl) break recording
Dynamic wait conditions - API calls, lazy loading, animations
File uploads via drag - Not captured, needs manual code
Scroll positions - Important for infinite scroll, parallax effects
Elements in tables - Clicks inside table cells often ignored
Cookie banners - Accept/reject clicks frequently missed
Browser context - Multiple tabs, popups, iframes interactions

2. Zero Context for AI Enhancement

Without understanding the "why" behind actions, AI cannot:

Generate robust selectors (which element attributes matter?)
Add proper wait conditions (is this a slow API or instant action?)
Implement error handling (what errors are expected?)
Create reusable patterns (is this a common workflow?)
Apply security best practices (which data is sensitive?)

3. No Control Over AI Context

You need to control exactly what context the AI receives to:

Prevent over-engineering simple tests
Focus on critical business logic
Explain complex workflows efficiently
Document edge cases and gotchas
Specify performance requirements

The Solution

Add rich context during recording to create bulletproof automations in one pass:

Real-Time Annotations

💬 Comments - Document missing actions & business logic (press Enter)
📸 Screenshots - Capture UI states that affect logic (press 'p')
⏱️ Wait notes - Specify timing requirements explicitly (press 'w')
📊 Event log - Complete timeline for AI to understand flow

Complete Context Capture

// What Playwright records:
await page.click('#submit');

// What you need to tell AI:
// 💬 USER NOTE [00:23]: Drag file to dropzone (not recorded by codegen)
// 💬 USER NOTE [00:25]: Wait for file processing - can take 30+ seconds
// 📸 SCREENSHOT [00:45]: Upload progress bar at 50%
// ⏱️ WAIT NOTE [01:00]: File processing complete (30 seconds)
await page.click('#submit');

Result: Production-Ready Automation

With complete context, AI can generate:

Missing drag & drop implementations
Proper wait conditions for slow operations
Retry logic for flaky elements
Error handling for known issues
Stealth browser compatibility
Performance monitoring
Cross-browser adaptations

Installation

npm install -g playwright-recording-annotator

Quick Start

# Start recording
record-pw

# With URL
record-pw https://app.example.com

# During recording:
# [Enter] - Add comment about missing actions or logic
# [p]     - Screenshot current state
# [w]     - Document wait requirements
# [h]     - Show annotation history

Key Use Cases

1. Document Unrecorded Actions

// Your comment during recording:
"Drag CSV file from desktop to dropzone - codegen can't record this"

// AI generates:
await page.locator('#dropzone').dragAndDrop('/path/to/file.csv');

2. Explain Complex Workflows

// Your comment:
"Check all items in infinite scroll list - need to scroll to load more"

// AI generates:
while (await page.locator('.load-more').isVisible()) {
  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
  await page.waitForTimeout(1000);
}

3. Specify Performance Requirements

// Your wait note:
"API response time SLA is 3 seconds max"

// AI generates:
await page.waitForResponse(
  response => response.url().includes('/api/data'),
  { timeout: 3000 }
);

Output Files

recording.spec.js - Playwright test with your annotations
recording.log.json - Complete context for AI processing
recording.md - Human-readable documentation
recording_images/ - Screenshots with absolute paths

Roadmap: MCP Server Integration

Next version: Direct AI integration for real-time enhancement:

Live context streaming - AI sees what you see
Bidirectional communication - AI asks clarifying questions
Automatic code generation - Missing actions implemented instantly
Stealth browser optimization - Anti-detection patterns applied

Requirements

Node.js >= 14.0.0
Playwright >= 1.40.0
macOS/Linux/Windows (screenshot paste: macOS only currently)

Troubleshooting

Screenshot Paste Not Working (macOS)

If screenshots aren't pasting on macOS:

Install pngpaste for better reliability:
```
brew install pngpaste
```
Ensure screenshot is in clipboard:
- Take screenshot: Cmd+Shift+4 (select area)
- The screenshot is automatically copied to clipboard
- Press p immediately after taking screenshot
Check clipboard permissions:
- System Preferences → Security & Privacy → Privacy
- Ensure Terminal has access to clipboard

Files Not Found After Recording

Recording files are saved with absolute paths in:

.playwright-shared/recordings/[recording_name]/

The summary at the end shows:

Full absolute paths to all files
Command to open directory in Finder/Explorer
Command to run the generated test

License

MIT - See LICENSE