chore: git cache cleanup
This commit is contained in:
GitHub Actions
350
.github/skills/test-e2e-playwright.SKILL.md
vendored
Normal file
350
.github/skills/test-e2e-playwright.SKILL.md
vendored
Normal file
@@ -0,0 +1,350 @@
|
||||
---
|
||||
# agentskills.io specification v1.0
|
||||
name: "test-e2e-playwright"
|
||||
version: "1.0.0"
|
||||
description: "Run Playwright E2E tests against the Charon application with browser selection and filtering"
|
||||
author: "Charon Project"
|
||||
license: "MIT"
|
||||
tags:
|
||||
- "testing"
|
||||
- "e2e"
|
||||
- "playwright"
|
||||
- "integration"
|
||||
- "browser"
|
||||
compatibility:
|
||||
os:
|
||||
- "linux"
|
||||
- "darwin"
|
||||
shells:
|
||||
- "bash"
|
||||
requirements:
|
||||
- name: "node"
|
||||
version: ">=18.0"
|
||||
optional: false
|
||||
- name: "npx"
|
||||
version: ">=1.0"
|
||||
optional: false
|
||||
environment_variables:
|
||||
- name: "PLAYWRIGHT_BASE_URL"
|
||||
description: "Base URL of the Charon application under test"
|
||||
default: "http://localhost:8080"
|
||||
required: false
|
||||
- name: "PLAYWRIGHT_HTML_OPEN"
|
||||
description: "Controls HTML report auto-open behavior (set to 'never' for CI/non-interactive)"
|
||||
default: "never"
|
||||
required: false
|
||||
- name: "CI"
|
||||
description: "Set to 'true' when running in CI environment"
|
||||
default: ""
|
||||
required: false
|
||||
parameters:
|
||||
- name: "project"
|
||||
type: "string"
|
||||
description: "Browser project to run (chromium, firefox, webkit, all)"
|
||||
default: "chromium"
|
||||
required: false
|
||||
- name: "headed"
|
||||
type: "boolean"
|
||||
description: "Run tests in headed mode (visible browser)"
|
||||
default: "false"
|
||||
required: false
|
||||
- name: "grep"
|
||||
type: "string"
|
||||
description: "Filter tests by title pattern (regex)"
|
||||
default: ""
|
||||
required: false
|
||||
outputs:
|
||||
- name: "playwright-report"
|
||||
type: "directory"
|
||||
description: "HTML test report directory"
|
||||
path: "playwright-report/"
|
||||
- name: "test-results"
|
||||
type: "directory"
|
||||
description: "Test artifacts and traces"
|
||||
path: "test-results/"
|
||||
metadata:
|
||||
category: "test"
|
||||
subcategory: "e2e"
|
||||
execution_time: "medium"
|
||||
risk_level: "low"
|
||||
ci_cd_safe: true
|
||||
requires_network: true
|
||||
idempotent: 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.
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright
|
||||
```
|
||||
|
||||
### Browser Selection
|
||||
|
||||
Run tests in a specific browser:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright --headed
|
||||
```
|
||||
|
||||
### Filter Tests
|
||||
|
||||
Run only tests matching a pattern:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
.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:
|
||||
|
||||
```yaml
|
||||
- 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright --grep="smoke"
|
||||
```
|
||||
|
||||
### Example 2: Debug Failing Test
|
||||
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright --headed --grep="failing-test-name"
|
||||
```
|
||||
|
||||
### Example 3: Cross-Browser Validation
|
||||
|
||||
```bash
|
||||
.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:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e
|
||||
```
|
||||
|
||||
#### Error: page.goto: net::ERR_CONNECTION_REFUSED
|
||||
**Solution**: Start the Charon application before running tests:
|
||||
```bash
|
||||
.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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
docker ps --filter "name=charon-playwright"
|
||||
docker logs charon-playwright --tail 50
|
||||
```
|
||||
|
||||
2. **Verify the application is accessible**:
|
||||
```bash
|
||||
curl -sf http://localhost:8080/api/v1/health
|
||||
```
|
||||
|
||||
3. **Rebuild with clean state if needed**:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh docker-rebuild-e2e --clean
|
||||
```
|
||||
|
||||
4. **Debug specific failing test**:
|
||||
```bash
|
||||
.github/skills/scripts/skill-runner.sh test-e2e-playwright-debug --grep="test name"
|
||||
```
|
||||
|
||||
5. **View the HTML report for details**:
|
||||
```bash
|
||||
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](./docker-rebuild-e2e.SKILL.md) - Rebuild Docker image and restart E2E container
|
||||
- [test-e2e-playwright-debug](./test-e2e-playwright-debug.SKILL.md) - Debug E2E tests in headed mode
|
||||
- [test-e2e-playwright-coverage](./test-e2e-playwright-coverage.SKILL.md) - Run E2E tests with coverage
|
||||
- [test-frontend-unit](./test-frontend-unit.SKILL.md) - Frontend unit tests with Vitest
|
||||
- [docker-start-dev](./docker-start-dev.SKILL.md) - Start development environment
|
||||
- [integration-test-all](./integration-test-all.SKILL.md) - 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
|
||||
Reference in New Issue
Block a user