name: e2e-tests
description: "Detect and run end-to-end or integration tests, ensuring a clean environment (no zombie processes, free ports). Handles the known dev-server-crash issue when running after a production build. Use as Phase 5 of the deployment pipeline."

Integration / E2E Tests

Run end-to-end or integration tests that exercise the full application.

Detect

Look for e2e test configuration:

• npm run test:e2e or similar script in package.json
• Playwright config (playwright.config.ts, playwright.config.js)
• Cypress config (cypress.config.ts, cypress.json)
• pytest with integration markers
• Docker Compose files for service dependencies
• Emulator configurations (database emulators, auth emulators, etc.)

Before Running

Ensure all required services are stopped from prior runs. Verify ports are free. E2E tests need a clean environment — stale emulators and dev servers cause flaky failures.

# Example: find and kill processes on common ports
lsof -ti :3000 | xargs kill -9 2>/dev/null   # dev server
lsof -ti :9000 | xargs kill -9 2>/dev/null   # emulator

Known Issue: Dev Server Crash After Production Build

If the project uses a chained command (e.g., npm run test:all) that runs the production build then immediately starts e2e tests, the build output can destabilize the dev server that the test runner spawns.

Symptoms: ERR_CONNECTION_REFUSED on localhost after the first few tests pass.

Preferred approach: Run the unit-tests, build, and e2e-tests phases as separate commands rather than one chained script. This avoids the build/dev-server conflict entirely.

If using a chained command and it fails with connection refused: Kill all processes, verify ports are free, and re-run e2e alone — the unit test and build results from the same run are still valid.

Collect

• Test count (passed / failed / skipped)
• Test names and durations
• Any console errors or page crashes
• Total duration
• Exit code

Stop Conditions

STOP if: Any test fails. If tests fail on the second run with the same error, diagnose the root cause — don't retry again.