Start Server and Test Utility

3.0.2 · active · verified Sun Apr 19

start-server-and-test is a command-line utility designed to streamline common development and continuous integration (CI) workflows. It starts a specified server process, robustly waits for a given URL to become available (indicating the server is ready), and then executes a designated test command. Upon completion of the test command, it automatically shuts down the initially started server process, ensuring clean resource management. The current stable version is 3.0.2, released in April 2026. The package maintains an active release cadence, with frequent updates addressing bug fixes and performance, alongside periodic major versions that introduce significant internal improvements, particularly for cross-platform compatibility. Its key differentiators include seamless integration with npm scripts, intelligent process management, and robust service readiness checks, making it an essential tool for automating e2e and integration tests.

Common errors

```
Error: wait-on timed out after Xms
```
cause The target server did not respond to the specified URL within the default or configured timeout duration. This could be due to the server failing to start, starting on a different port/URL, or network configuration issues preventing `wait-on` from reaching it.

fix Verify that your server start command is correct and the server is indeed listening on the specified URL. Increase the `wait-on` timeout if the server takes longer to warm up (e.g., `start-server-and-test <server> <url> --wait-on-timeout 60000 <test>`).
```
command not found: start-server-and-test
```
cause The `start-server-and-test` executable is not in your system's PATH, or you are attempting to run it directly without `npx` when it's installed locally as a `devDependency`.

fix Ensure the package is installed (`npm install --save-dev start-server-and-test`). If running from the command line, use `npx start-server-and-test ...`. When used in `package.json` scripts, `npm` automatically adds `./node_modules/.bin` to the PATH, so `start-server-and-test ...` should work directly.
```
The system cannot find the path specified. (WMIC related errors on Windows)
```
cause Prior to v3.0.0, `start-server-and-test` (via its dependency `ps-tree`) relied on the `wmic.exe` utility on Windows for process management, which is deprecated and no longer installed by default on newer Windows Server/Desktop releases, leading to command not found errors.

fix Upgrade to `start-server-and-test` version 3.0.0 or newer. This version explicitly removes the dependency on `wmic.exe` and uses a more robust, platform-agnostic method for process termination on Windows.

Warnings

breaking Version 3.0.0 removed the requirement for the deprecated WMI command-line tool (wmic.exe) on Windows. This was achieved by replacing the internal `ps-tree` dependency with `tree-kill`, improving Windows compatibility and removing a dependency on a tool no longer installed by default on newer Windows Server/Desktop releases (affecting Windows Server 2025, Windows 11 24H2 & 25H2).
Fix: Upgrade to v3.0.0 or newer. No specific user action is typically required, as this change improves internal behavior.
breaking Starting with version 2.1.3, the package's internal `wait-on` dependency was updated to v9.0.3, which requires a minimum Node.js version of 20. Older Node.js versions (below 20) are no longer supported by `start-server-and-test` from this version onwards.
Fix: Ensure your Node.js environment is version 20 or higher. The package's `engines` field now explicitly reflects a requirement of `^22 || >=24`.
breaking When upgrading from v1 to v2, if you were previously specifying only a port number (e.g., `3000`) for a local server, you must now provide the explicit full URL (e.g., `http://localhost:3000`) instead.
Fix: Update your scripts to use the full URL, like `http://localhost:xxxx` instead of just `xxxx`.
gotcha It is highly recommended to specify the full URL (e.g., `http://127.0.0.1:8080`) rather than just a port number (e.g., `8080`) or an unqualified `localhost:port`. This helps avoid potential issues related to how different operating systems and network configurations resolve `localhost` (e.g., `0.0.0.0` vs `127.0.0.1`), ensuring more reliable server waiting.
Fix: Always use a full, explicit URL like `http://127.0.0.1:port` or `http://0.0.0.0:port` to ensure reliable server readiness checks.

Install

npm install start-server-and-test npm
yarn add start-server-and-test yarn
pnpm add start-server-and-test pnpm

Imports

start-server-and-test
wrong:
```
import { startServerAndTest } from 'start-server-and-test'
```
correct:
```
start-server-and-test <start-command> <url> <test-command>
```
This package is a command-line interface (CLI) utility, not a JavaScript module for direct programmatic import. It is executed via npx or as a script in package.json.
server-test
wrong:
```
const serverTest = require('start-server-and-test')
```
correct:
```
server-test <start-command> <url> <test-command>
```
`server-test` is an alias for the main `start-server-and-test` command, primarily used in npm scripts for brevity. It is a CLI tool and not importable as a module.
start-test
wrong:
```
import * as startTest from 'start-server-and-test'
```
correct:
```
start-test <start-command> <url> <test-command>
```
`start-test` is another CLI alias for `start-server-and-test`. It is used directly in the command line or npm scripts, not via JavaScript `import` or `require` statements.

Quickstart

Demonstrates how to integrate `start-server-and-test` into a `package.json` script to orchestrate starting a server, waiting for it to be ready, and then executing test commands.

{ "scripts": {
    "start-server": "npm start",
    "test": "mocha e2e-spec.js",
    "ci": "start-server-and-test start-server http://localhost:8080 test"
  }
}

view raw JSON →