start-server-and-test

start-server-and-test is a small CLI utility built for one specific CI headache: running end-to-end tests against a server that has to be booted first. Instead of hand-writing shell glue to launch a server in the background, poll it until it’s ready, run the test suite, and remember to kill the server afterward, you wire three npm scripts together and let the tool orchestrate the whole sequence.

Under the hood it combines wait-on for HTTP polling with execa for process management and tree-kill for reliably terminating the server (and any child processes it spawned) once tests finish, whether they pass or fail. It supports single or multiple services started in sequence, custom expected HTTP status codes, proxy configuration, and both HEAD and GET-based readiness checks for servers like webpack-dev-server that don’t respond to HEAD requests.

The project is maintained by Gleb Bahmutov (a longtime Cypress core contributor) and is a near-universal dependency in Cypress and Playwright CI setups, with millions of weekly downloads. It ships as start-server-and-test, server-test, and start-test — three aliases for the same binary — and requires no configuration file, only npm script names or shell commands passed as CLI arguments.

What You Get

• Automatic server lifecycle management - starts the server process, waits for a successful HTTP response before proceeding, and tears it down (including child processes) once tests complete or fail
• Three interchangeable CLI aliases - start-server-and-test, server-test, and start-test all resolve to the same binary so you can pick whichever reads best in your scripts
• Multi-service sequencing - start and wait on two servers in sequence (e.g. an API and a frontend) before running tests, using the 5-argument invocation form
• Configurable readiness checks - override the expected HTTP status code with --expect, force GET instead of HEAD probes with the http-get:// URL prefix, or wait on multiple URLs separated by |
• Proxy support - route the readiness ping through a proxy host/port with optional username/password authentication
• Insecure HTTPS mode - disable strict SSL certificate validation via START_SERVER_AND_TEST_INSECURE for self-signed local certs

Common Use Cases

• Running Cypress or Playwright e2e tests against a locally started dev server in CI
• Booting a webpack-dev-server or Vite dev server, waiting for the GET-only response, then running a test suite
• Starting a backend API and a frontend server in sequence before running integration tests against both
• Testing a server that requires HTTP Basic Auth or returns a non-200 status by design, using --expect
• Running the same start/wait/test/shutdown sequence identically across local dev machines and CI runners

Under The Hood

Architecture The package is a thin, single-purpose layering: src/bin/start.js parses process.argv via the arg library and hands off to src/index.js’s startAndTest, which recursively walks a services array — starting one server, waiting on its URL with wait-on, then either running the test command (via execa) or recursing into the next service. Cleanup is chained with .finally(stopServer), guaranteeing the server and any child processes are killed through tree-kill regardless of whether the test command succeeds, fails, or throws. src/utils.js is deliberately separated to hold pure parsing/normalization logic (URL/port normalization, npm-script-name detection, quoted-argument reassembly), keeping side-effecting process orchestration isolated from testable pure functions.

Tech Stack Built as a CommonJS Node package (type: commonjs, Node 22/24+ via engines) with a minimal runtime dependency set: execa for child-process spawning, wait-on for HTTP readiness polling, tree-kill for cross-platform process-tree termination, arg for CLI argument parsing, and lazy-ass/check-more-types for lightweight runtime assertions. Prettier handles formatting, Husky wires a pre-commit hook, and renovate.json keeps dependencies patched automatically — reflected in the changelog’s heavy renovate-bot commit volume.

Code Quality Tests run under Mocha with the snap-shot-it snapshot-testing library and sinon/sinon-chai for stubbing, covering both the CLI-argument utilities and the end-to-end startAndTest flow against real fixture servers in test/. CI (GitHub Actions) runs the suite across both ubuntu-latest and windows-latest, plus a battery of npm run demo* scripts that exercise real start/wait/test/shutdown cycles — directly guarding the Windows-specific process-termination error handling in stopServer. Files use @ts-check JSDoc annotations for lightweight type safety without a full TypeScript build step.

What Makes It Unique It doesn’t reimplement HTTP polling or process management — it composes three already-trusted single-purpose packages (wait-on, execa, tree-kill) behind a CLI ergonomic enough to drop into a single npm script line. Its main technical contribution is the recursive multi-service sequencing and the exhaustively handled cross-platform “process already exited” detection in stopServer, covering distinct English, German, and POSIX error signatures — a level of edge-case coverage most hand-rolled CI shell scripts never reach.