# jest-dev-server

> Starts a server before your Jest tests and tears it down after.

Latest version **11.0.0** (published 2024-12-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install jest-dev-server
pnpm add jest-dev-server
yarn add jest-dev-server
bun add jest-dev-server
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 11.0.0 |
| Published | 2024-12-21 |
| First published | 2018-05-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 7 |
| Unpacked size | 16.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3544 |
| Maintainers | neoziro, tonybrix |
| Keywords | jest, jest-environment, server |

## Links

- npm: https://www.npmjs.com/package/jest-dev-server
- Repository: https://github.com/argos-ci/jest-puppeteer
- Homepage: https://github.com/argos-ci/jest-puppeteer/tree/main/packages/jest-dev-server#readme
- Issues: https://github.com/argos-ci/jest-puppeteer/issues
- npm.io page: https://npm.io/package/jest-dev-server

## Dependencies (7)

- [cwd](https://npm.io/package/cwd.md) ^0.10.0
- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [spawnd](https://npm.io/package/spawnd.md) ^11.0.0
- [prompts](https://npm.io/package/prompts.md) ^2.4.2
- [wait-on](https://npm.io/package/wait-on.md) ^8.0.1
- [tree-kill](https://npm.io/package/tree-kill.md) ^1.2.2
- [find-process](https://npm.io/package/find-process.md) ^1.4.7

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 11.0.0 (latest) — 2024-12-21
- 10.1.4 — 2024-10-26
- 10.1.1 — 2024-09-06
- 10.1.0 — 2024-08-17
- 10.0.0 — 2024-02-10
- 9.0.2 — 2023-12-06
- 9.0.1 — 2023-10-01
- 9.0.0 — 2023-05-24
- 8.0.5 — 2023-03-09
- 8.0.3 — 2023-03-07
- 8.0.2 — 2023-03-06
- 8.0.0 — 2023-03-06
- 7.0.1 — 2023-02-15
- 7.0.0 — 2023-02-03
- 6.2.0 — 2022-12-11
- … 24 more at https://npm.io/package/jest-dev-server/versions

## README

# jest-dev-server

[![npm version](https://img.shields.io/npm/v/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)
[![npm dm](https://img.shields.io/npm/dm/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)
[![npm dt](https://img.shields.io/npm/dt/jest-dev-server.svg)](https://www.npmjs.com/package/jest-dev-server)

Starts a server before your Jest tests and tears it down after.

## Why

`jest-puppeteer` works great for running tests in Jest using Puppeteer.
It's also useful for starting a local development server during the tests without letting Jest hang.
This package extracts just the local development server spawning without any ties to Puppeteer.

## Install

```bash
npm install --save-dev jest-dev-server
```

## Usage

`jest-dev-server` exports `setup` and `teardown` functions.

```js
// global-setup.js
const { setup: setupDevServer } = require("jest-dev-server");

module.exports = async function globalSetup() {
  globalThis.servers = await setupDevServer({
    command: `node config/start.js --port=3000`,
    launchTimeout: 50000,
    port: 3000,
  });
  // Your global setup
};
```

```js
// global-teardown.js
const { teardown: teardownDevServer } = require("jest-dev-server");

module.exports = async function globalTeardown() {
  await teardownDevServer(globalThis.servers);
  // Your global teardown
};
```

### Specify several servers

You can specify several servers using an array of configs:

```js
// global-setup.js
const { setup: setupDevServer } = require("jest-dev-server");

module.exports = async function globalSetup() {
  globalThis.servers = await setupDevServer([
    {
      command: "node server.js",
      port: 4444,
    },
    {
      command: "node server2.js",
      port: 4445,
    },
  ]);
  // Your global setup
};
```

## Options

### `command`

Type: `string`, required.

Command to execute to start the port.
Directly passed to [`spawnd`](https://www.npmjs.com/package/spawnd).

```js
const options = {
  command: "npm run start",
};
```

### `debug`

Type: `boolean`, default to `false`.

Log server output, useful if server is crashing at start.

```js
const options = {
  command: "npm run start",
  debug: true,
};
```

### `launchTimeout`

Type: `number`, default to `5000`.

How many milliseconds to wait for the spawned server to be available before giving up.
Defaults to [`wait-port`](https://www.npmjs.com/package/wait-port)'s default.

```js
const options = {
  command: "npm run start",
  launchTimeout: 30000,
};
```

---

Following options are linked to [`spawnd`](https://www.npmjs.com/package/spawnd).

### `host`

Type: `string`, if not specified it will used Node.js default port.

Host to wait for activity on before considering the server running.
Must be used in conjunction with `port`.

```js
const options = {
  command: "npm run start --port 3000",
  host: "customhost.com",
  port: 3000,
};
```

### `path`

Type: `string`, default to `null`.

Path to resource to wait for activity on before considering the server running.
Must be used in conjunction with `host` and `port`.

```js
const options = {
  command: "npm run start --port 3000",
  host: "customhost.com",
  port: 3000,
  path: "thing",
};
```

### `protocol`

Type: `string`, (`https`, `http`, `tcp`, `socket`) default to `tcp`.

To wait for an HTTP or TCP endpoint before considering the server running, include `http` or `tcp` as a protocol.
Must be used in conjunction with `port`.

```js
const options = {
  command: "npm run start --port 3000",
  protocol: "http",
  port: 3000,
};
```

### `port`

Type: `number`, default to `null`.

Port to wait for activity on before considering the server running.
If not provided, the server is assumed to immediately be running.

```js
const options = {
  command: "npm run start --port 3000",
  port: 3000,
};
```

### `usedPortAction`

Type: `string` (`ask`, `error`, `ignore`, `kill`) default to `ask`.

It defines the action to take if port is already used:

- `ask`: a prompt is shown to decide if you want to kill the process or not
- `error`: an errow is thrown
- `ignore`: your test are executed, we assume that the server is already started
- `kill`: the process is automatically killed without a prompt

```js
const options = {
  command: "npm run start --port 3000",
  port: 3000,
  usedPortAction: "kill",
};
```

### `waitOnScheme`

`jest-dev-server` use the [`wait-on`](https://www.npmjs.com/package/wait-on) npm package to wait for resources to become available before calling callback.

Type: `object`, default to `{}`.

- `delay`: optional initial delay in ms, default 0
- `interval`: optional poll resource interval in ms, default 250ms
- `log`: optional flag which outputs to stdout, remaining resources waited on and when complete or errored
- `reverse`: optional flag to reverse operation so checks are for resources being NOT available, default false
- `timeout`: optional timeout in ms, default Infinity. Aborts with error
- `tcpTimeout`: optional tcp timeout in ms, default 300ms
- `verbose`: optional flag which outputs debug output, default false
- `window`: optional stabilization time in ms, default 750ms. Waits this amount of time for file sizes to stabilize or other resource availability to remain unchanged

**Note:** http(s) specific options, see https://github.com/request/request#readme for specific details

```js
const options = {
  command: "npm run start --port 3000",
  port: 3000,
  usedPortAction: "kill",
  waitOnScheme: {
    delay: 1000,
  },
};
```

## Troubleshooting

- If using `port` makes the terminal to ask for root password although the port is valid and accessible then use `usePortAction: 'ignore'`.

---
_Source: https://npm.io/package/jest-dev-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._