liumusicforever avatar

webapp-test-docker-demo

Dedicated test Agent responsible for managing all E2E tests for the webapp-test-docker-demo project.

作者 liumusicforever|オープンソース

E2E Testing Framework

Demo

An end-to-end testing framework using Playwright.

⚠️ Important Notice

This project assumes users have already started docker-compose and set the base URL for the web page to be tested.

Please ensure:

  1. Docker-compose services are already started
  2. TEST_BASE_URL environment variable is set
export TEST_BASE_URL=http://localhost:8080

🎯 Using Cursor / Claude Code for Testing

Most users will use Cursor or Claude Code for interaction. Here is the complete setup and usage workflow:

Step 1: Download and Install Tools

Install Cursor (Recommended)

  1. Visit Cursor website to download
  2. Install and launch Cursor
  3. Cursor has built-in AI assistant, ready to use

Or Use Claude Code (Web Version)

  1. Visit Claude Code
  2. Log in with your account
  3. Upload project files or connect to project

Step 2: Download Project

Method A: Using Git (Recommended)

git clone <project-url>
cd webapp-test-docker-demo

Method B: Download ZIP

  1. Download project ZIP file
  2. Extract to local directory
  3. Open the directory in Cursor/Claude Code

Step 3: Open Project in Cursor / Claude Code

Using Cursor

  1. Open Cursor
  2. Click File → Open Folder (or Cmd+O / Ctrl+O)
  3. Select project folder webapp-test-docker-demo
  4. Wait for Cursor to load the project

Using Claude Code

  1. Log in to Claude Code
  2. Click "Upload Project" or "Connect Project"
  3. Select project folder or ZIP file
  4. Wait for Claude Code to analyze project structure

Step 4: Initial Setup

In the Cursor/Claude Code dialog, directly tell the AI:

Install project dependencies

The AI will automatically execute:

npm install
npx playwright install

Step 5: Setup Test Environment

Start Docker Services

Ensure your docker-compose services are started (this project assumes users manage docker-compose themselves)

If you need to reference example Docker configuration, please check the instructions in the example-docker directory.

Set Test URL

In Cursor/Claude Code, tell the AI:

Set test URL to http://localhost:8080

The AI will automatically set the TEST_BASE_URL environment variable

Or manually execute in terminal:

export TEST_BASE_URL=http://localhost:8080

Step 6: Start Using AI for Testing

Now you can directly use natural language to give instructions to the AI in the Cursor/Claude Code dialog:

List All Tests

List all tests

The AI will automatically execute npm run test:list or python scripts/test_manager.py list, and display the test list

Create New Test

Create a login test for me
Create a shopping cart feature test

The AI will automatically:

  1. Execute npm run test:new <test_name>
  2. Create new test file based on template
  3. Tell you the file location and next steps

Run Tests

Run all tests
Run login test

The AI will automatically:

  1. Check if TEST_BASE_URL environment variable is set
  2. If not set, prompt you to set it
  3. Execute tests (default head mode, browser will open)
  4. Display test results and report location

Run Tests (Headless Mode)

Run tests in CICD mode
Run tests in headless mode

The AI will automatically set TEST_IS_CICD=true and execute headless mode tests

View Test Report

Show test report
Open test report

The AI will automatically execute npx playwright show-report and display the report link

Other Common Commands

Show me the test file login.spec.ts
Modify login test, add error handling
Run all tests with @smoke tag
Show screenshots of failed tests

Tips

  • Natural Language Interaction: Just say what you want to do, no need to remember complex commands
  • Context Awareness: AI remembers project structure and previous conversation content
  • Auto-completion: AI automatically completes relevant file paths and commands
  • Error Handling: If errors occur, AI automatically provides solutions

Quick Start

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Started docker-compose services (managed by user)

Start Docker Services

This project assumes users will use their own docker-compose configuration. If you need to reference example configuration, please check the example-docker directory.

Install Dependencies

npm install
npx playwright install

Test Management

List All Tests

npm run test:list
# or
python scripts/test_manager.py list

Create New Test

npm run test:new <test_name>
# or
python scripts/test_manager.py new <test_name>

# Examples
npm run test:new login
npm run test:new user-profile

New test files will be created in the tests/e2e/ directory, using templates/test_template.spec.ts as the template.

Run Tests

# Run all tests (default head mode, browser will open)
export TEST_BASE_URL=http://localhost:8080
npm run test:run

# Run specific test file
npm run test:run login.spec.ts

# CICD mode (headless mode, browser won't open)
TEST_IS_CICD=true npm run test:run

Note:

  • Default is head mode (browser window will open), suitable for local development and debugging
  • When environment variable TEST_IS_CICD=true is set, it will automatically switch to headless mode, suitable for CI/CD environments

Other Test Commands

# Use Playwright UI mode (recommended, can see test process)
npm run test:ui

# Debug mode (will pause tests for debugging)
npm run test:debug

Test Mode Explanation

Head Mode (Default)

By default, tests run in head mode, browser window will open, and you can see the test process. Suitable for:

  • Local development and debugging
  • Visual verification of test flow
  • Observing behavior when developing new tests

Headless Mode (CICD)

When environment variable TEST_IS_CICD=true is set, tests run in headless mode, browser window won't open. Suitable for:

  • CI/CD environments
  • Automated test workflows
  • Scenarios where visual observation is not needed
# Run in headless mode
TEST_IS_CICD=true npm test
# or
TEST_IS_CICD=true npm run test:run

Project Structure

webapp-test-docker-demo/
├── tests/
│   └── e2e/               # E2E test files
├── templates/
│   └── test_template.spec.ts  # Test template
├── scripts/
│   └── test_manager.py    # Unified test management script
├── playwright.config.ts   # Playwright configuration
└── package.json

Test Tags

Tests can be categorized using tags:

  • @smoke: Smoke tests (core functionality)
  • @regression: Regression tests (edge cases)

Example:

test('Successful login @smoke', async ({ page }) => {
  // ...
});

test('Login failure - wrong password @regression', async ({ page }) => {
  // ...
});

Run Tests with Specific Tags

# Run only tests with @smoke tag
npx playwright test --grep @smoke

# Run only tests with @regression tag
npx playwright test --grep @regression

# Exclude tests with @regression tag
npx playwright test --grep-invert @regression

View Test Reports

# View HTML report
npx playwright show-report

# View trace (if test failed)
npx playwright show-trace test-results/your-test/trace.zip

Configuration

Environment Variables

  • TEST_BASE_URL: Base URL of the web page to test (required)
  • TEST_IS_CICD: When set to true, run tests in headless mode
  • CI: When set to true, also use headless mode (Playwright handles automatically)

Playwright Configuration

Main configuration is in playwright.config.ts:

  • Default mode: Head mode (browser visible)
  • CICD mode: Automatically switch to headless mode when TEST_IS_CICD=true is set
  • Timeout settings:
    • Test timeout: 30 seconds
    • Action timeout: 10 seconds
    • Navigation timeout: 30 seconds
  • Viewport size: 1280x720
  • Auto screenshot and video on failure: Enabled

Important Notes

  1. Must set TEST_BASE_URL: Environment variable must be set before running tests
  2. Ensure services are started: Please ensure docker-compose services are started and accessible
  3. Default head mode: Browser will open by default, if not needed please set TEST_IS_CICD=true
  4. Example Docker configuration: Example Docker configuration files are located in example-docker/ directory, can be used as reference

License

MIT

Skill をダウンロード