webapp-server-runner

Core Rules

1. Atomic Socket Readiness Polling: Never launch end-to-end tests using fixed sleep timers. Always poll server port sockets via with_server.py before beginning test execution.
2. Multi-Server Lifecycle Coordination: Manage backend APIs, frontend dev servers, and mock services concurrently via repeatable --server and --port CLI arguments.
3. Guaranteed Process Termination: All background server processes must be launched in isolated process groups (os.setsid) and terminated cleanly via atexit handlers (SIGTERM followed by SIGKILL). Zero orphan processes are tolerated.
4. Exit Code Propagation: The runner must strictly exit with the exact return code emitted by the executed test command, preserving CI test pass/fail semantics.
5. Tripartite Evidence Collection on Failure: On test failure, capture screenshot, DOM snapshot, and browser console logs via playwright-evidence-qa.

Suggested Process