Charon/.github/skills/test-e2e-playwright-debug.SKILL.md

name, version, description, author, license, tags, compatibility, requirements, environment_variables, parameters, outputs, metadata

name	version	description	author	license	tags	compatibility	requirements	environment_variables	parameters	outputs	metadata
test-e2e-playwright-debug	1.0.0	Run Playwright E2E tests in headed/debug mode for troubleshooting with slowMo and trace collection	Charon Project	MIT	testing e2e playwright debug troubleshooting	os shells linux darwin bash	name version optional node >=18.0 false name version optional npx >=1.0 false	name description default required PLAYWRIGHT_BASE_URL Base URL of the Charon application under test http://localhost:8080 false name description default required PWDEBUG Enable Playwright Inspector (set to '1' for step-by-step debugging) false name description default required DEBUG Enable verbose Playwright logging (e.g., 'pw:api') false	name type description default required file string Specific test file to run (relative to tests/ directory) false name type description default required grep string Filter tests by title pattern (regex) false name type description default required slowmo number Slow down operations by specified milliseconds 500 false name type description default required inspector boolean Open Playwright Inspector for step-by-step debugging false false name type description default required project string Browser project to run (chromium, firefox, webkit) chromium false	name type description path playwright-report directory HTML test report directory playwright-report/ name type description path test-results directory Test artifacts, screenshots, and traces test-results/	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent test e2e-debug variable low false true true

Test E2E Playwright Debug

Overview

Runs Playwright E2E tests in headed/debug mode for troubleshooting. This skill provides enhanced debugging capabilities including:

• Headed Mode: Visible browser window to watch test execution
• Slow Motion: Configurable delay between actions for observation
• Playwright Inspector: Step-by-step debugging with breakpoints
• Trace Collection: Always captures traces for post-mortem analysis
• Single Test Focus: Run individual tests or test files

Use this skill when:

• Debugging failing E2E tests
• Understanding test flow and interactions
• Developing new E2E tests
• Investigating flaky tests

Prerequisites

• Node.js 18.0 or higher installed and in PATH
• Playwright browsers installed (npx playwright install chromium)
• Charon application running at localhost:8080 (use docker-rebuild-e2e when app/runtime inputs change or the container is not running)
• Display available (X11 or Wayland on Linux, native on macOS)
• Test files in tests/ directory

Usage

Basic Debug Mode

Run all tests in headed mode with slow motion:

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug

Debug Specific Test File

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --file=login.spec.ts

Debug Test by Name Pattern

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --grep="should login with valid credentials"

With Playwright Inspector

Open the Playwright Inspector for step-by-step debugging:

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --inspector

Custom Slow Motion

Adjust the delay between actions (in milliseconds):

# Slower for detailed observation
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --slowmo=1000

# Faster but still visible
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --slowmo=200

Different Browser

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --project=firefox

Combined Options

.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug \
    --file=dashboard.spec.ts \
    --grep="navigation" \
    --slowmo=750 \
    --project=chromium

Parameters

Parameter	Type	Required	Default	Description
file	string	No	""	Specific test file to run
grep	string	No	""	Filter tests by title pattern
slowmo	number	No	500	Delay between actions (ms)
inspector	boolean	No	false	Open Playwright Inspector
project	string	No	chromium	Browser to use

Environment Variables

Variable	Required	Default	Description
PLAYWRIGHT_BASE_URL	No	http://localhost:8080	Application URL
PWDEBUG	No	""	Set to "1" for Inspector mode
DEBUG	No	""	Verbose logging (e.g., "pw:api")

Debugging Techniques

Using Playwright Inspector

The Inspector provides:

• Step-through Execution: Execute one action at a time
• Locator Playground: Test and refine selectors
• Call Log: View all Playwright API calls
• Console: Access browser console

# Enable Inspector
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --inspector

In the Inspector:

1. Use Resume to continue to next action
2. Use Step to execute one action
3. Use the Locator tab to test selectors
4. Check Console for JavaScript errors

Adding Breakpoints in Tests

Add await page.pause() in your test code:

test('debug this test', async ({ page }) => {
    await page.goto('/');
    await page.pause(); // Opens Inspector here
    await page.click('button');
});

Verbose Logging

Enable detailed Playwright API logging:

DEBUG=pw:api .github/skills/scripts/skill-runner.sh test-e2e-playwright-debug

Screenshot on Failure

Tests automatically capture screenshots on failure. Find them in:

test-results/<test-name>/
├── test-failed-1.png
├── trace.zip
└── ...

Analyzing Traces

Traces are always captured in debug mode. View them with:

# Open trace viewer for a specific test
npx playwright show-trace test-results/<test-name>/trace.zip

# Or view in browser
npx playwright show-trace --port 9322

Traces include:

• DOM snapshots at each step
• Network requests/responses
• Console logs
• Screenshots
• Action timeline

Examples

Example 1: Debug Login Flow

# Rebuild environment with clean state
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e --clean

# Debug login tests
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug \
    --file=login.spec.ts \
    --slowmo=800

Example 2: Investigate Flaky Test

# Run with Inspector to step through
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug \
    --grep="flaky test name" \
    --inspector

# After identifying the issue, view the trace
npx playwright show-trace test-results/*/trace.zip

Example 3: Develop New Test

# Run in headed mode while developing
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug \
    --file=new-feature.spec.ts \
    --slowmo=500

Example 4: Cross-Browser Debug

# Debug in Firefox
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug \
    --project=firefox \
    --grep="cross-browser issue"

Test File Locations

Path	Description
tests/	All E2E test files
tests/auth.setup.ts	Authentication setup
tests/login.spec.ts	Login flow tests
tests/dashboard.spec.ts	Dashboard tests
tests/dns-records.spec.ts	DNS management tests
playwright/.auth/	Stored auth state

Troubleshooting

No Browser Window Opens

Linux: Ensure X11/Wayland display is available

echo $DISPLAY  # Should show :0 or similar

Remote/SSH: Use X11 forwarding or VNC

ssh -X user@host

WSL2: Install and configure WSLg or X server

Test Times Out

Increase timeout for debugging:

# In your test file
test.setTimeout(120000); // 2 minutes

Inspector Doesn't Open

Ensure PWDEBUG is set:

PWDEBUG=1 npx playwright test --headed

Cannot Find Test File

Check the file exists:

ls -la tests/*.spec.ts

Use relative path from tests/ directory:

--file=login.spec.ts  # Not tests/login.spec.ts

Common Issues and Solutions

Issue	Solution
"Target closed"	Application crashed - check container logs
"Element not found"	Use Inspector to verify selector
"Timeout exceeded"	Increase timeout or check if element is hidden
"Net::ERR_CONNECTION_REFUSED"	Ensure Docker container is running
Flaky test	Add explicit waits or use Inspector to find race condition

Related Skills

• test-e2e-playwright - Run tests normally
• docker-rebuild-e2e - Rebuild E2E environment
• test-e2e-playwright-coverage - Run with coverage

Notes

• Not CI/CD Safe: Headed mode requires a display
• Resource Usage: Browser windows consume significant memory
• Slow Motion: Default 500ms delay; adjust based on needs
• Traces: Always captured for post-mortem analysis
• Single Worker: Runs one test at a time for clarity

---

Last Updated: 2026-01-21 Maintained by: Charon Project Team Test Directory: tests/