{"id":12070,"library":"start-server-and-test","title":"Start Server and Test Utility","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/bahmutov/start-server-and-test","tags":["javascript","ci","parallel","server","start","test","utility","wait"],"install":[{"cmd":"npm install start-server-and-test","lang":"bash","label":"npm"},{"cmd":"yarn add start-server-and-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add start-server-and-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { startServerAndTest } from 'start-server-and-test'","symbol":"start-server-and-test","correct":"start-server-and-test <start-command> <url> <test-command>"},{"note":"`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.","wrong":"const serverTest = require('start-server-and-test')","symbol":"server-test","correct":"server-test <start-command> <url> <test-command>"},{"note":"`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.","wrong":"import * as startTest from 'start-server-and-test'","symbol":"start-test","correct":"start-test <start-command> <url> <test-command>"}],"quickstart":{"code":"{ \"scripts\": {\n    \"start-server\": \"npm start\",\n    \"test\": \"mocha e2e-spec.js\",\n    \"ci\": \"start-server-and-test start-server http://localhost:8080 test\"\n  }\n}","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade to v3.0.0 or newer. No specific user action is typically required, as this change improves internal behavior.","message":"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).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment is version 20 or higher. The package's `engines` field now explicitly reflects a requirement of `^22 || >=24`.","message":"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.","severity":"breaking","affected_versions":">=2.1.3"},{"fix":"Update your scripts to use the full URL, like `http://localhost:xxxx` instead of just `xxxx`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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>`).","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.","error":"Error: wait-on timed out after Xms"},{"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.","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`.","error":"command not found: start-server-and-test"},{"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.","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.","error":"The system cannot find the path specified. (WMIC related errors on Windows)"}],"ecosystem":"npm"}