{"id":13371,"library":"jest-dev-server","title":"Jest Dev Server","description":"jest-dev-server is a utility package designed to manage the lifecycle of a development server during Jest test runs. It enables users to automatically start a server process before their test suites execute and reliably tear it down afterward, ensuring a clean and consistent testing environment. While often used within the `jest-puppeteer` ecosystem for end-to-end testing, this package operates independently, capable of managing any server process. The current stable version is 11.0.0, with minor and patch updates released frequently and major versions typically aligning with Node.js LTS updates or significant Jest/Puppeteer compatibility requirements. Key differentiators include its focus on robust server lifecycle management, flexible configuration options for server commands, ports, and wait conditions, and its ability to integrate seamlessly with Jest's `globalSetup` and `globalTeardown` hooks for both JavaScript and TypeScript projects.","status":"active","version":"11.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/argos-ci/jest-puppeteer","tags":["javascript","jest","jest-environment","server","typescript"],"install":[{"cmd":"npm install jest-dev-server","lang":"bash","label":"npm"},{"cmd":"yarn add jest-dev-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest-dev-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Integrates directly with Jest's global setup and teardown hooks. This package is typically a peer dependency of a testing setup using Jest.","package":"jest","optional":false}],"imports":[{"note":"The `setup` function is primarily used in Jest's `globalSetup` configuration to start your development server before tests. It is an async function.","wrong":"const { setup } = require('jest-dev-server'); // CommonJS syntax, still valid but ESM preferred for modern Jest configs.","symbol":"setup","correct":"import { setup } from 'jest-dev-server';"},{"note":"The `teardown` function is primarily used in Jest's `globalTeardown` configuration to stop your development server after tests. It is an async function.","wrong":"const { teardown } = require('jest-dev-server'); // CommonJS syntax, still valid but ESM preferred for modern Jest configs.","symbol":"teardown","correct":"import { teardown } from 'jest-dev-server';"},{"note":"TypeScript type definition for the configuration object passed to `setup`. Useful for type-checking your `jest-dev-server` options.","symbol":"Config","correct":"import type { Config } from 'jest-dev-server';"}],"quickstart":{"code":"// jest.config.ts\nimport type { Config } from 'jest';\n\nconst config: Config = {\n  globalSetup: '<rootDir>/test/globalSetup.ts',\n  globalTeardown: '<rootDir>/test/globalTeardown.ts',\n  testEnvironment: 'node',\n  testMatch: ['<rootDir>/test/**/*.test.ts'],\n  roots: ['<rootDir>/src', '<rootDir>/test'],\n  transform: {\n    '^.+\\.tsx?$': 'ts-jest',\n  },\n  // Required for ESM imports in globalSetup/teardown when using ts-node\n  // See warnings/problems for more details\n  // globalSetup and globalTeardown are run outside the Jest environment\n  // and might need ts-node/register to process TypeScript files.\n};\n\nexport default config;\n\n// test/globalSetup.ts\nimport { setup as setupDevServer } from 'jest-dev-server';\n\n// Workaround for TypeScript globalSetup/teardown if 'ts-node/register' isn't configured globally\n// (e.g., if Jest is not running with --require ts-node/register)\nrequire('ts-node/register');\n\nconst globalSetup = async (): Promise<void> => {\n  await setupDevServer({\n    command: `node ${__dirname}/server.js --port=8080`,\n    port: 8080,\n    launchTimeout: 30000,\n    debug: true,\n    usedPortAction: 'kill',\n  });\n  console.log('Development server started on port 8080.');\n};\n\nexport default globalSetup;\n\n// test/globalTeardown.ts\nimport { teardown as teardownDevServer } from 'jest-dev-server';\n\n// Workaround for TypeScript globalSetup/teardown if 'ts-node/register' isn't configured globally\nrequire('ts-node/register');\n\nconst globalTeardown = async (): Promise<void> => {\n  await teardownDevServer();\n  console.log('Development server stopped.');\n};\n\nexport default globalTeardown;\n\n// test/server.js (simple HTTP server for demonstration)\nconst http = require('http');\nconst port = process.env.PORT || 8080;\n\nconst server = http.createServer((req, res) => {\n  res.statusCode = 200;\n  res.setHeader('Content-Type', 'text/plain');\n  res.end('Hello from Jest Dev Server!\\n');\n});\n\nserver.listen(port, () => {\n  // console.log(`Server running at http://localhost:${port}/`); // Commented to avoid noise during tests\n});\n\nprocess.on('SIGTERM', () => {\n  // console.log('Server shutting down...'); // Commented to avoid noise during tests\n  server.close(() => {\n    // console.log('Server closed.'); // Commented to avoid noise during tests\n    process.exit(0);\n  });\n});\n\n// test/example.test.ts\nimport axios from 'axios';\n\ndescribe('HTTP Server', () => {\n  it('should respond with \"Hello from Jest Dev Server!\"', async () => {\n    const response = await axios.get('http://localhost:8080');\n    expect(response.status).toBe(200);\n    expect(response.data).toBe('Hello from Jest Dev Server!\\n');\n  });\n});","lang":"typescript","description":"Demonstrates how to configure Jest with `jest-dev-server` to start and stop a basic HTTP server using TypeScript for the configuration and global hooks, and then run an example test against it."},"warnings":[{"fix":"Upgrade your Node.js version to 18 or higher (e.g., `nvm install 18 && nvm use 18`).","message":"Node.js v16 support has been dropped with the release of v10.0.0 and v11.0.0. Projects using Node.js v16 or older will need to upgrade their Node.js environment to at least v18.","severity":"breaking","affected_versions":">=10.0.0"},{"fix":"Explicitly set the `host` option in your `jest-dev-server` configuration to 'localhost' or '0.0.0.0' if a specific binding is required.","message":"In an earlier major version, the default `host` option for `jest-dev-server` changed from 'localhost' to `undefined`. This might affect how the server binds to network interfaces if not explicitly configured.","severity":"breaking","affected_versions":"<9.0.0"},{"fix":"Ensure `ts-node` is installed and either configure Jest to pre-load `ts-node/register` (e.g., `jest --require ts-node/register`) or add `require('ts-node/register');` at the top of your `globalSetup.ts` and `globalTeardown.ts` files.","message":"When using `globalSetup` and `globalTeardown` with TypeScript files (e.g., `globalSetup.ts`), Jest might fail to load these files if `ts-node/register` is not properly configured or required within the setup/teardown scripts themselves, leading to `SyntaxError: Cannot use import statement outside a module` or `TypeError`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly define `usedPortAction` in your `jest-dev-server` configuration, especially in CI/CD. For example, `usedPortAction: 'kill'` or `usedPortAction: 'error'` to prevent hangs or ensure clean state.","message":"The `usedPortAction` option dictates how `jest-dev-server` behaves if the specified port is already in use. The default action is 'ask', which can cause tests to hang in CI/CD environments. Setting it to 'kill' can force termination of existing processes, but 'error' or 'ignore' might be more appropriate depending on your setup.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `require('ts-node/register');` to the very top of your `globalSetup.ts` and `globalTeardown.ts` files, or ensure your Jest configuration includes `--require ts-node/register` or `module.exports = require('ts-node').register({ transpileOnly: true });` in your setup files.","cause":"Jest's `globalSetup` or `globalTeardown` files, written in TypeScript, are being loaded without `ts-node/register` or a similar loader to transpile them at runtime.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Configure `usedPortAction: 'kill'` in your `jest-dev-server` options to automatically terminate processes occupying the port, or ensure no other applications are running on the designated port. Alternatively, set `usedPortAction: 'error'` to fail fast or `usedPortAction: 'ignore'` to proceed if the server is expected to be already running.","cause":"The port specified for your development server is already occupied by another process, and `jest-dev-server` is configured to throw an error or implicitly 'ask' (which hangs).","error":"Error: listen EADDRINUSE: address already in use :::<port>"},{"fix":"Double-check your `jest.config.ts` or `jest.config.js` to ensure module type (`type: 'module'` in `package.json`) and loader configurations are consistent with how your `globalSetup` and `globalTeardown` files are written (ESM `import` vs. CJS `require`). Ensure `ts-node` is correctly configured for TypeScript files.","cause":"This error often occurs when Jest tries to load an ESM `globalSetup` or `globalTeardown` file using CommonJS `require` semantics, or vice-versa, due to incorrect module resolution or transpilation in a mixed environment.","error":"TypeError: (0 , jest_dev_server_1.setup) is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}