Charon/.github/skills/test-e2e-playwright.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	1.0.0	Run Playwright E2E tests against the Charon application with browser selection and filtering	Charon Project	MIT	testing e2e playwright integration browser	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 PLAYWRIGHT_HTML_OPEN Controls HTML report auto-open behavior (set to 'never' for CI/non-interactive) never false name description default required CI Set to 'true' when running in CI environment false	name type description default required project string Browser project to run (chromium, firefox, webkit, all) chromium false name type description default required headed boolean Run tests in headed mode (visible browser) false false name type description default required grep string Filter tests by title pattern (regex) false	name type description path playwright-report directory HTML test report directory playwright-report/ name type description path test-results directory Test artifacts and traces test-results/	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent test e2e medium low true true true

Test E2E Playwright

Overview

Executes Playwright end-to-end tests against the Charon application. This skill supports browser selection, headed mode for debugging, and test filtering by name pattern.

The skill runs non-interactively by default (HTML report does not auto-open), making it suitable for CI/CD pipelines and automated testing scenarios.

Prerequisites

• Node.js 18.0 or higher installed and in PATH
• Playwright browsers installed (npx playwright install)
• Charon application running (default: http://localhost:8080)
• Test files in tests/ directory

Quick Start: Ensure E2E Environment is Ready

Before running tests, ensure the Docker E2E environment is running. Rebuild when application or Docker build inputs change. If only tests or docs changed and the container is already healthy, skip rebuild.

# Start/rebuild E2E Docker container (required when app/runtime inputs change)
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e

# Or for a complete clean rebuild:
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e --clean --no-cache

Usage

Basic Usage

Run E2E tests with default settings (Firefox, headless):

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

Browser Selection

Run tests in a specific browser:

# Firefox (default)
.github/skills/scripts/skill-runner.sh test-e2e-playwright --project=firefox

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

# WebKit (Safari)
.github/skills/scripts/skill-runner.sh test-e2e-playwright --project=webkit

# All browsers
.github/skills/scripts/skill-runner.sh test-e2e-playwright --project=all

Headed Mode (Debugging)

Run tests with a visible browser window:

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

Filter Tests

Run only tests matching a pattern:

# Run tests with "login" in the title
.github/skills/scripts/skill-runner.sh test-e2e-playwright --grep="login"

# Run tests with "DNS" in the title
.github/skills/scripts/skill-runner.sh test-e2e-playwright --grep="DNS"

Combined Options

.github/skills/scripts/skill-runner.sh test-e2e-playwright --project=firefox --headed --grep="dashboard"

CI/CD Integration

For use in GitHub Actions or other CI/CD pipelines:

- name: Run E2E Tests
  run: .github/skills/scripts/skill-runner.sh test-e2e-playwright
  env:
    PLAYWRIGHT_BASE_URL: http://localhost:8080
    CI: true

Parameters

Parameter	Type	Required	Default	Description
project	string	No	firefox	Browser project: chromium, firefox, webkit, all
headed	boolean	No	false	Run with visible browser window
grep	string	No	""	Filter tests by title pattern (regex)

Environment Variables

Variable	Required	Default	Description
PLAYWRIGHT_BASE_URL	No	http://localhost:8080	Application URL to test against
PLAYWRIGHT_HTML_OPEN	No	never	HTML report auto-open behavior
CI	No	""	Set to "true" for CI environment behavior

Outputs

Success Exit Code

• 0: All tests passed

Error Exit Codes

• 1: One or more tests failed
• Non-zero: Configuration or execution error

Output Directories

• playwright-report/: HTML report with test results and traces
• test-results/: Test artifacts, screenshots, and trace files

Viewing the Report

After test execution, view the HTML report using VS Code Simple Browser:

Method 1: Start Report Server

npx playwright show-report --port 9323

Then open in VS Code Simple Browser: http://127.0.0.1:9323

Method 2: VS Code Task

Use the VS Code task "Test: E2E Playwright - View Report" to start the report server as a background task, then open http://127.0.0.1:9323 in Simple Browser.

Method 3: Direct File Access

Open playwright-report/index.html directly in a browser.

Examples

Example 1: Quick Smoke Test

.github/skills/scripts/skill-runner.sh test-e2e-playwright --grep="smoke"

Example 2: Debug Failing Test

.github/skills/scripts/skill-runner.sh test-e2e-playwright --headed --grep="failing-test-name"

Example 3: Cross-Browser Validation

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

Test Structure

Tests are located in the tests/ directory and follow Playwright conventions:

tests/
├── auth.setup.ts          # Authentication setup (runs first)
├── dashboard.spec.ts      # Dashboard tests
├── dns-records.spec.ts    # DNS management tests
├── login.spec.ts          # Login flow tests
└── ...

Error Handling

Common Errors

Error: Target page, context or browser has been closed

Solution: Ensure the application is running at the configured base URL. Rebuild if needed:

.github/skills/scripts/skill-runner.sh docker-rebuild-e2e

Error: page.goto: net::ERR_CONNECTION_REFUSED

Solution: Start the Charon application before running tests:

.github/skills/scripts/skill-runner.sh docker-rebuild-e2e

Error: browserType.launch: Executable doesn't exist

Solution: Run npx playwright install to install browser binaries

Error: Timeout waiting for selector

Solution: The application may be slow or in an unexpected state. Try:

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

# Or debug the test to see what's happening
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --grep="failing test"

Error: Authentication state is stale

Solution: Remove stored auth and let setup recreate it:

rm -rf playwright/.auth/user.json
.github/skills/scripts/skill-runner.sh test-e2e-playwright

Troubleshooting Workflow

When E2E tests fail, follow this workflow:

1. Check container health:

   docker ps --filter "name=charon-playwright"
   docker logs charon-playwright --tail 50
   

2. Verify the application is accessible:

   curl -sf http://localhost:8080/api/v1/health
   

3. Rebuild with clean state if needed:

   .github/skills/scripts/skill-runner.sh docker-rebuild-e2e --clean
   

4. Debug specific failing test:

   .github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --grep="test name"
   

5. View the HTML report for details:

   npx playwright show-report --port 9323
   

Key File Locations

Path	Purpose
tests/	All E2E test files
tests/auth.setup.ts	Authentication setup fixture
playwright.config.js	Playwright configuration
playwright/.auth/user.json	Stored authentication state
playwright-report/	HTML test reports
test-results/	Test artifacts and traces
.docker/compose/docker-compose.playwright.yml	E2E Docker compose config
Dockerfile	Application Docker image

Related Skills

• docker-rebuild-e2e - Rebuild Docker image and restart E2E container
• test-e2e-playwright-debug - Debug E2E tests in headed mode
• test-e2e-playwright-coverage - Run E2E tests with coverage
• test-frontend-unit - Frontend unit tests with Vitest
• docker-start-dev - Start development environment
• integration-test-all - Run all integration tests

Notes

• Authentication: Tests use stored auth state from playwright/.auth/user.json
• Parallelization: Tests run in parallel locally, sequential in CI
• Retries: CI automatically retries failed tests twice
• Traces: Traces are collected on first retry for debugging
• Report: HTML report is generated at playwright-report/index.html

---

Last Updated: 2026-01-15 Maintained by: Charon Project Team Source: tests/ directory