akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 16 Packages Projects Releases Wiki Activity
Files
0e680c72fb36f1a480dc517b613dc7e51e1a5b6b
Charon/.github/skills/test-e2e-playwright-debug.SKILL.md
GitHub Actions f64e3feef8 chore: clean .gitignore cache
2026-01-26 19:22:05 +00:00

9.6 KiB
Raw Blame History

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 skill)
  • 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

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/

Reference in New Issue View Git Blame Copy Permalink