@dyyz1993/agent-browser 0.9.2 → 0.11.0

package/skills/agent-browser/references/network-monitoring.md

@@ -0,0 +1,232 @@
+# Network Request Monitoring
+
+The `network` command provides powerful network interception and monitoring capabilities for testing APIs, blocking unwanted requests, mocking responses, and debugging network behavior.
+
+## Basic Network Monitoring
+
+### View All Network Requests
+
+```bash
+# Start monitoring network requests
+agent-browser network requests
+
+# Clear request history
+agent-browser network requests --clear
+
+# Filter requests by URL pattern
+agent-browser network requests --filter "**/api/**"
+agent-browser network requests --filter "**/json"
+```
+
+### Example: Monitor API Calls
+
+```bash
+# Open a page
+agent-browser open https://httpbin.org/delay/1
+
+# View all network requests made
+agent-browser network requests
+
+# Filter to see only JSON responses
+agent-browser network requests --filter "**/json"
+```
+
+## Request Interception (Routing)
+
+### Mock API Responses
+
+```bash
+# Set up a mock response for a URL pattern
+agent-browser network route "**/api/users" --body '{"users": [{"id": 1, "name": "Mock User"}]}'
+
+# Now any request to /api/users will return the mock data
+agent-browser open https://example.com
+
+# Remove the route
+agent-browser network unroute "**/api/users"
+```
+
+### Block Unwanted Requests
+
+```bash
+# Block ads or tracking scripts
+agent-browser network route "**/ads/**" --abort
+agent-browser network route "**/tracking/**" --abort
+
+# Block specific domains
+agent-browser network route "**/analytics.google.com/**" --abort
+
+# Remove block
+agent-browser network unroute "**/ads/**"
+```
+
+## Recording Network Activity
+
+### During Recorder Session
+
+```bash
+# Start recording session
+agent-browser recorder start --session network-test
+
+# Navigate and perform actions
+agent-browser open https://httpbin.org/get
+agent-browser open https://httpbin.org/json
+
+# View network requests during recording
+agent-browser network requests
+agent-browser network requests --filter "**/json"
+
+# Stop recording
+agent-browser recorder stop --output network-test.yaml
+```
+
+## Advanced Patterns
+
+### Debug API Issues
+
+```bash
+# 1. Clear previous requests
+agent-browser network requests --clear
+
+# 2. Navigate to trigger API calls
+agent-browser open https://example.com/dashboard
+
+# 3. Check what requests were made
+agent-browser network requests
+
+# 4. Filter for specific endpoints
+agent-browser network requests --filter "**/api/v1/**"
+```
+
+### Test Error Handling
+
+```bash
+# Mock error responses
+agent-browser network route "**/api/critical" --body '{"error": "Service unavailable"}'
+
+# Or block the request entirely
+agent-browser network route "**/api/critical" --abort
+
+# Test how your app handles the error
+agent-browser open https://example.com
+```
+
+### Performance Testing
+
+```bash
+# Monitor requests while testing
+agent-browser network requests --clear
+
+# Perform actions
+agent-browser click @e1
+agent-browser wait --load networkidle
+
+# Check how many requests were made
+agent-browser network requests
+```
+
+## URL Pattern Matching
+
+The routing uses glob patterns:
+
+- `**/api/**` - Match any path containing /api/
+- `**/api/users` - Match specific endpoint
+- `**/*.json` - Match all JSON files
+- `https://example.com/**` - Match specific domain
+- `**/ads/**` - Match any ad URLs
+
+## Integration with Recorder
+
+Network monitoring works seamlessly with the recorder:
+
+```bash
+# Start recording with network monitoring
+agent-browser recorder start --session my-test
+
+# Your workflow
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+
+# Check network requests
+agent-browser network requests
+
+# Stop and save
+agent-browser recorder stop --output test-with-network.yaml
+```
+
+## Best Practices
+
+1. **Clear before testing**: Use `--clear` to start fresh
+   ```bash
+   agent-browser network requests --clear
+   ```
+
+2. **Filter effectively**: Use specific patterns to reduce noise
+   ```bash
+   agent-browser network requests --filter "**/api/v2/**"
+   ```
+
+3. **Clean up routes**: Always remove test routes
+   ```bash
+   agent-browser network unroute "**/test/**"
+   ```
+
+4. **Combine with wait**: Use network idle for comprehensive testing
+   ```bash
+   agent-browser click @e1
+   agent-browser wait --load networkidle
+   agent-browser network requests
+   ```
+
+## Use Cases
+
+- **API Testing**: Mock responses and test error handling
+- **Performance**: Monitor request count and patterns
+- **Debugging**: See what requests your app makes
+- **Ad Blocking**: Block unwanted requests during testing
+- **Offline Testing**: Block external dependencies
+- **Security**: Audit what data is being sent
+
+## Example Test Script
+
+```bash
+#!/bin/bash
+
+# Test network monitoring with httpbin.org
+
+# Start browser
+agent-browser open https://httpbin.org
+
+# Clear previous requests
+agent-browser network requests --clear
+
+# Make some requests
+agent-browser open https://httpbin.org/get
+agent-browser open https://httpbin.org/json
+agent-browser open https://httpbin.org/html
+
+# Check all requests
+agent-browser network requests
+
+# Filter JSON requests
+agent-browser network requests --filter "**/json"
+
+# Test mocking
+agent-browser network route "**/test" --body '{"mocked": true}'
+agent-browser open https://httpbin.org/test
+agent-browser network unroute "**/test"
+
+# Test blocking
+agent-browser network route "**/blocked" --abort
+
+# Clean up
+agent-browser close
+```
+
+## Limitations
+
+- Routes are session-specific and reset on browser close
+- Request history is stored in memory and cleared on browser close
+- Mock responses only work for simple JSON bodies
+- For complex mocking, consider using a dedicated API mocking service

package/skills/agent-browser/references/profiling.md

@@ -0,0 +1,120 @@
+# Profiling
+
+Capture Chrome DevTools performance profiles during browser automation for performance analysis.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Profiling](#basic-profiling)
+- [Profiler Commands](#profiler-commands)
+- [Categories](#categories)
+- [Use Cases](#use-cases)
+- [Output Format](#output-format)
+- [Viewing Profiles](#viewing-profiles)
+- [Limitations](#limitations)
+
+## Basic Profiling
+
+```bash
+# Start profiling
+agent-browser profiler start
+
+# Perform actions
+agent-browser navigate https://example.com
+agent-browser click "#button"
+agent-browser wait 1000
+
+# Stop and save
+agent-browser profiler stop ./trace.json
+```
+
+## Profiler Commands
+
+```bash
+# Start profiling with default categories
+agent-browser profiler start
+
+# Start with custom trace categories
+agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
+
+# Stop profiling and save to file
+agent-browser profiler stop ./trace.json
+```
+
+## Categories
+
+The `--categories` flag accepts a comma-separated list of Chrome trace categories. Default categories include:
+
+- `devtools.timeline` -- standard DevTools performance traces
+- `v8.execute` -- time spent running JavaScript
+- `blink` -- renderer events
+- `blink.user_timing` -- `performance.mark()` / `performance.measure()` calls
+- `latencyInfo` -- input-to-latency tracking
+- `renderer.scheduler` -- task scheduling and execution
+- `toplevel` -- broad-spectrum basic events
+
+Several `disabled-by-default-*` categories are also included for detailed timeline, call stack, and V8 CPU profiling data.
+
+## Use Cases
+
+### Diagnosing Slow Page Loads
+
+```bash
+agent-browser profiler start
+agent-browser navigate https://app.example.com
+agent-browser wait --load networkidle
+agent-browser profiler stop ./page-load-profile.json
+```
+
+### Profiling User Interactions
+
+```bash
+agent-browser navigate https://app.example.com
+agent-browser profiler start
+agent-browser click "#submit"
+agent-browser wait 2000
+agent-browser profiler stop ./interaction-profile.json
+```
+
+### CI Performance Regression Checks
+
+```bash
+#!/bin/bash
+agent-browser profiler start
+agent-browser navigate https://app.example.com
+agent-browser wait --load networkidle
+agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"
+```
+
+## Output Format
+
+The output is a JSON file in Chrome Trace Event format:
+
+```json
+{
+  "traceEvents": [
+    { "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
+    ...
+  ],
+  "metadata": {
+    "clock-domain": "LINUX_CLOCK_MONOTONIC"
+  }
+}
+```
+
+The `metadata.clock-domain` field is set based on the host platform (Linux or macOS). On Windows it is omitted.
+
+## Viewing Profiles
+
+Load the output JSON file in any of these tools:
+
+- **Chrome DevTools**: Performance panel > Load profile (Ctrl+Shift+I > Performance)
+- **Perfetto UI**: https://ui.perfetto.dev/ -- drag and drop the JSON file
+- **Trace Viewer**: `chrome://tracing` in any Chromium browser
+
+## Limitations
+
+- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
+- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
+- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.

package/skills/agent-browser/references/recorder.md

@@ -0,0 +1,319 @@
+# Recorder (Action Recording & Replay)
+
+Record user interactions as structured steps that can be replayed or exported for LLM processing.
+
+**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
+
+## Contents
+
+- [Basic Recording](#basic-recording)
+- [Recording Workflow](#recording-workflow)
+- [Supported Actions](#supported-actions)
+- [YAML Output Format](#yaml-output-format)
+- [Replay Feature](#replay-feature)
+- [Use Cases](#use-cases)
+- [Best Practices](#best-practices)
+
+## Basic Recording
+
+```bash
+# Start recording session
+agent-browser recorder start
+
+# Perform actions
+agent-browser open https://example.com
+agent-browser snapshot -i
+agent-browser click @e1
+agent-browser fill @e2 "test input"
+agent-browser select @e3 "option"
+
+# Stop recording and save to file
+agent-browser recorder stop --output session.yaml
+```
+
+## Recording Workflow
+
+The recorder captures all browser interactions including:
+
+1. **Navigation**: Page loads and URL changes
+2. **Input**: Text entry in form fields
+3. **Selection**: Dropdown choices
+4. **Clicks**: Button and link clicks
+5. **Scrolling**: Page scroll events
+6. **Mouse Movement**: Trajectory data for human-like behavior
+
+```bash
+# Example: Complete form submission workflow
+agent-browser recorder start --session form-test
+
+# Navigate to form
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+
+# Fill form fields
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser select @e3 "United States"
+agent-browser check @e4
+
+# Submit form
+agent-browser click @e5
+agent-browser wait --load networkidle
+
+# Save recording
+agent-browser recorder stop --output form-submission.yaml
+```
+
+## Supported Actions
+
+| Action | Description | Example |
+|--------|-------------|---------|
+| `navigate` | Page navigation | `agent-browser open https://example.com` |
+| `fill` | Text input | `agent-browser fill @e1 "text"` |
+| `select` | Dropdown selection | `agent-browser select @e2 "option"` |
+| `click` | Element click | `agent-browser click @e3` |
+| `check` | Checkbox check | `agent-browser check @e4` |
+| `uncheck` | Checkbox uncheck | `agent-browser uncheck @e5` |
+| `scroll` | Page scroll | `agent-browser scroll down 500` |
+| `trajectory` | Mouse movement | Captured automatically |
+
+## YAML Output Format
+
+The recorder generates a structured YAML file with:
+
+```yaml
+session:
+  id: recorder-1234567890
+  startTime: 19:46:49
+  endTime: 19:48:28
+  steps: 83
+
+pages:
+  - url: https://example.com
+    title: Example Domain
+    firstVisitTime: 19:46:53
+
+steps:
+  - id: step-1234567890
+    time: 19:47:00
+    action: fill
+    selector: "#username"
+    xpath: "//*[@id='username']"
+    value: "testuser"
+
+  - id: step-1234567891
+    time: 19:47:05
+    action: click
+    selector: "#submit-btn"
+    xpath: "//*[@id='submit-btn']"
+
+  - id: step-1234567892
+    time: 19:47:10
+    action: scroll
+    x: 0
+    y: 500
+
+# CLI Commands section contains executable commands
+# for direct replay in terminal
+```
+
+## Replay Feature
+
+Replay recorded interactions from YAML file:
+
+```bash
+# Replay most recent recording
+agent-browser recorder replay
+
+# Replay specific file
+agent-browser recorder replay form-submission.yaml
+
+# Replay with verbose output
+agent-browser recorder replay session.yaml --verbose
+```
+
+The replay feature:
+1. Parses the YAML file
+2. Executes each step in sequence
+3. Handles both navigation and interactions
+4. Supports all recorded action types
+
+## Use Cases
+
+### 1. Test Automation Documentation
+
+Record manual test sessions for documentation:
+
+```bash
+agent-browser recorder start --session checkout-flow
+
+# Perform checkout process
+agent-browser open https://shop.example.com/cart
+agent-browser snapshot -i
+agent-browser fill @e1 "123 Main St"
+agent-browser fill @e2 "New York"
+agent-browser fill @e3 "10001"
+agent-browser click @e4
+agent-browser wait --load networkidle
+
+# Save for documentation
+agent-browser recorder stop --output docs/checkout-flow.yaml
+```
+
+### 2. Regression Testing
+
+Create reusable test scenarios:
+
+```bash
+# Record once
+agent-browser recorder start
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "$USERNAME"
+agent-browser fill @e2 "$PASSWORD"
+agent-browser click @e3
+agent-browser recorder stop --output tests/login.yaml
+
+# Replay in CI/CD
+agent-browser recorder replay tests/login.yaml
+```
+
+### 3. Workflow Automation
+
+Capture complex workflows for automation:
+
+```bash
+# Record multi-step workflow
+agent-browser recorder start
+agent-browser open https://dashboard.example.com
+agent-browser snapshot -i
+agent-browser click @e1  # Navigate to reports
+agent-browser click @e2  # Select date range
+agent-browser click @e3  # Export CSV
+agent-browser recorder stop --output workflows/export-data.yaml
+```
+
+### 4. Debugging & Analysis
+
+Record sessions for debugging:
+
+```bash
+agent-browser recorder start --session debug-$(date +%s)
+
+# Run problematic workflow
+agent-browser open https://example.com
+# ... interactions ...
+
+# Save for analysis
+agent-browser recorder stop --output debug/session.yaml
+```
+
+## Best Practices
+
+### 1. Use Session Names
+
+```bash
+# Good: Descriptive session names
+agent-browser recorder start --session user-registration
+agent-browser recorder start --session checkout-payment
+agent-browser recorder start --session search-functionality
+
+# Avoid: Generic names
+agent-browser recorder start --session test1
+agent-browser recorder start --session recording
+```
+
+### 2. Add Wait Times for Stability
+
+```bash
+agent-browser recorder start
+
+# Add waits after critical actions
+agent-browser click @e1
+agent-browser wait --load networkidle  # Wait for page load
+
+agent-browser fill @e2 "text"
+agent-browser wait 1000  # Wait for dynamic content
+
+agent-browser click @e3
+```
+
+### 3. Use Snapshots for Ref Stability
+
+```bash
+agent-browser recorder start
+
+# Always snapshot before interactions
+agent-browser snapshot -i
+agent-browser click @e1
+
+# Re-snapshot after navigation
+agent-browser wait --load networkidle
+agent-browser snapshot -i
+agent-browser click @e2
+```
+
+### 4. Organize Recordings
+
+```bash
+# Create organized directory structure
+recordings/
+├── tests/
+│   ├── login.yaml
+│   ├── registration.yaml
+│   └── checkout.yaml
+├── workflows/
+│   ├── data-export.yaml
+│   └── report-generation.yaml
+└── docs/
+    ├── user-guide.yaml
+    └── api-demo.yaml
+```
+
+### 5. Review Generated Commands
+
+The YAML file includes a CLI Commands section at the end with executable commands. Review these commands to:
+
+- Verify the captured selectors
+- Check for redundant steps
+- Identify opportunities for optimization
+- Ensure actions are in correct order
+
+## Advanced Features
+
+### Session-Based Recording
+
+```bash
+# Record with specific session
+agent-browser recorder start --session my-test --timeout 60000
+
+# Use session for all commands
+agent-browser open https://example.com --session my-test
+agent-browser snapshot -i --session my-test
+agent-browser click @e1 --session my-test
+
+# Stop recording
+agent-browser recorder stop --output my-test.yaml --session my-test
+```
+
+### Timeout Configuration
+
+```bash
+# Set recording timeout (default: 60 seconds)
+agent-browser recorder start --timeout 120000  # 2 minutes
+
+# Useful for long-running workflows
+```
+
+## Limitations
+
+- Refs (`@e1`, `@e2`) are session-specific and not portable
+- Convert to CSS selectors for cross-session reuse
+- Some dynamic content may require additional wait handling
+- Replay requires same page structure as recording
+
+## See Also
+
+- [snapshot-refs.md](snapshot-refs.md) - Understanding refs and their lifecycle
+- [authentication.md](authentication.md) - Recording login flows
+- [video-recording.md](video-recording.md) - Video recording for debugging