From fd6b3513c5a8c6a0b7a59d3a4a07a0137f9ebff1 Mon Sep 17 00:00:00 2001 From: John McLear Date: Fri, 3 Apr 2026 20:23:40 +0100 Subject: [PATCH] docs: add local test running guide to AGENTS.md (#7442) * docs: add detailed local test running guide to AGENTS.md Expand the Testing & Validation section with step-by-step instructions for running backend (Mocha), frontend E2E (Playwright), and admin panel tests locally, including prerequisites and single-file examples. Co-Authored-By: Claude Opus 4.6 (1M context) * docs: add Playwright browser prerequisite check to AGENTS.md Agents and developers should verify Playwright browsers and system dependencies are installed before running frontend/admin tests to avoid silent failures and timeouts (especially webkit). Co-Authored-By: Claude Opus 4.6 (1M context) * docs: fix plugin test path and browser list per review - Plugin tests are at repo-root node_modules/, not src/node_modules/ - Playwright runs chromium and firefox only (webkit is disabled) Co-Authored-By: Claude Opus 4.6 (1M context) * docs: fix install-deps working directory to run from src/ Playwright is a devDependency of the src workspace, so install-deps must also run from src/ to match the correct Playwright version. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- AGENTS.MD | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 79 insertions(+), 3 deletions(-) diff --git a/AGENTS.MD b/AGENTS.MD index 5bd1af2ab..491c76550 100644 --- a/AGENTS.MD +++ b/AGENTS.MD @@ -55,13 +55,89 @@ pnpm --filter ep_etherpad-lite run prod # Start production server ### Testing & Validation - **Requirement:** Every bug fix MUST include a regression test in the same commit. -- **Backend Tests:** `pnpm --filter ep_etherpad-lite run test` -- **Frontend E2E Tests:** `pnpm --filter ep_etherpad-lite run test-ui` -- **Admin Tests:** `pnpm --filter ep_etherpad-lite run test-admin` +- **Always run tests locally before pushing to CI.** - **Linting:** `pnpm run lint` - **Type Check:** `pnpm --filter ep_etherpad-lite run ts-check` - **Build:** `pnpm run build:etherpad` before production deployment +#### Running Backend Tests Locally + +Backend tests use Mocha with tsx and run against a real server instance (started automatically by the test harness). No separate server process is needed. + +```bash +# Run ALL backend tests (includes plugin tests) +pnpm --filter ep_etherpad-lite run test + +# Run only utility tests (faster, ~5s timeout) +pnpm --filter ep_etherpad-lite run test-utils + +# Run a single test file directly +cd src && cross-env NODE_ENV=production npx mocha --import=tsx --timeout 120000 tests/backend/specs/YOUR_TEST.ts + +# Run unit tests (Vitest) +cd src && npx vitest +``` + +- Tests run with `NODE_ENV=production`. +- Default timeout is 120 seconds per test. +- Test files live in `src/tests/backend/specs/`. +- Plugin backend tests live in `node_modules/ep_*/static/tests/backend/specs/` (at repo root) and are included automatically by the test script. + +#### Running Frontend E2E Tests Locally + +Frontend tests use Playwright. **You must have a running Etherpad server** before launching them — the Playwright config does not auto-start the server. + +**Before running frontend or admin tests, ensure Playwright browsers are installed.** Check and install if needed: + +```bash +# Check which browsers are installed +cd src && npx playwright install --dry-run + +# Install all browsers and their system dependencies (must run from src/) +cd src && npx playwright install +cd src && sudo npx playwright install-deps +``` + +If `sudo` is unavailable, install system dependencies for webkit manually: +```bash +# Check which system libraries are missing for webkit +ldd ~/.cache/ms-playwright/webkit-*/minibrowser-wpe/MiniBrowser 2>&1 | grep "not found" +``` + +If browsers or system dependencies are missing, tests will fail silently or timeout — **always verify browser installation before debugging test failures.** + +```bash +# 1. Start the dev server in a separate terminal +pnpm --filter ep_etherpad-lite run dev + +# 2. Run frontend E2E tests +pnpm --filter ep_etherpad-lite run test-ui + +# 3. Run with interactive Playwright UI (useful for debugging) +pnpm --filter ep_etherpad-lite run test-ui:ui + +# Run a single test file +cd src && cross-env NODE_ENV=production npx playwright test tests/frontend-new/specs/YOUR_TEST.spec.ts +``` + +- Tests expect the server at `localhost:9001`. +- Test files live in `src/tests/frontend-new/specs/`. +- Runs against chromium and firefox by default (webkit is disabled). +- Playwright config is at `src/playwright.config.ts`. + +#### Running Admin Panel Tests Locally + +```bash +# Requires a running server and Playwright browsers installed (same as frontend tests) +pnpm --filter ep_etherpad-lite run test-admin + +# Interactive UI mode +pnpm --filter ep_etherpad-lite run test-admin:ui +``` + +- Admin tests run with `--workers 1` (sequential) on chromium and firefox only. +- Test files live in `src/tests/frontend-new/admin-spec/`. + ### Backend Test Auth Tests use JWT authentication, not API keys. Pattern: ```typescript