{"id":15327,"library":"fetch-test-server","title":"Node.js Fetch Test Server","description":"fetch-test-server is a utility library for Node.js integration testing, enabling developers to test their HTTP servers (including frameworks like Express and Koa) using the modern Fetch API. As of version 1.2.0, it leverages native ES6 features and promises, providing an async/await-friendly alternative to callback-based testing libraries such as SuperTest. The library operates by starting the user's HTTP server on a random available port, internally using `node-fetch` to make requests. It intelligently defers server startup until the first request is made, streamlining the test setup process. Its release cadence appears moderate, with recent updates focusing on modern JavaScript features. This package differentiates itself by offering a familiar browser-like API for server interactions directly within Node.js test environments.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/amacneil/fetch-test-server","tags":["javascript","express","fetch","http","integration","koa","server","test","testing"],"install":[{"cmd":"npm install fetch-test-server","lang":"bash","label":"npm"},{"cmd":"yarn add fetch-test-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add fetch-test-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal implementation of the Fetch API for Node.js environments.","package":"node-fetch","optional":false}],"imports":[{"note":"Since v1.1.0, the package uses natively supported ES6 features and is primarily designed for ES Module imports. CommonJS `require()` will not work.","wrong":"const TestServer = require('fetch-test-server')","symbol":"TestServer","correct":"import { TestServer } from 'fetch-test-server'"}],"quickstart":{"code":"/* file: myapp.js */\nimport express from 'express';\n\nconst app = express();\napp.use(express.json()); // For parsing application/json\n\napp.get('/user', (req, res) => {\n  res.status(200).json({ name: 'Adrian' });\n});\n\napp.post('/users', (req, res) => {\n  res.status(201).json({ status: 'created', data: req.body });\n});\n\nexport default app;\n\n/* file: test.js (run with Mocha or Jest) */\nimport { assert } from 'chai';\nimport { TestServer } from 'fetch-test-server';\nimport app from './myapp.js'; // Ensure .js extension for ESM\n\n// Optionally, if your TestServer might be a default export in some setups\n// import TestServer from 'fetch-test-server'; \n\ndescribe('API Integration Test', () => {\n  let server;\n\n  before(() => {\n    server = new TestServer(app);\n  });\n\n  after(async () => {\n    await server.close(); // Clean up the server after tests\n  });\n\n  it('responds to /user with async/await', async () => {\n    const res = await server.fetch('/user');\n    const body = await res.json();\n    assert.strictEqual(res.status, 200);\n    assert.strictEqual(body.name, 'Adrian');\n  });\n\n  it('sends JSON body and custom headers with post', async () => {\n    const res = await server.post('/users', {\n      headers: { 'X-Auth': 'secret-token' },\n      body: { item: 'new-user' }, // Automatically JSON-encoded\n    });\n    const body = await res.json();\n    assert.strictEqual(res.status, 201);\n    assert.deepStrictEqual(body.data, { item: 'new-user' });\n  });\n\n  it('allows manual server startup and exposes address', async () => {\n    await server.listen();\n    assert.match(server.address, /^http:\\/\\/127\\.0\\.0\\.1:\\d+$/);\n  });\n});\n\n// To run this example:\n// npm init -y\n// npm install --save-dev fetch-test-server express mocha chai","lang":"javascript","description":"This quickstart demonstrates setting up an Express server and testing its API endpoints using `fetch-test-server` with `async/await` syntax, showing GET and POST requests with JSON bodies and custom headers. It also includes server lifecycle management."},"warnings":[{"fix":"Migrate your test files and project configuration to use ES Modules. This typically involves changing `require()` to `import` statements and ensuring your `package.json` has `\"type\": \"module\"` or using `.mjs` file extensions for your test files.","message":"Version 1.1.0 introduced a rewrite using 'natively supported ES6 features', which implies a transition to ES Modules. This breaks compatibility for projects using CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Be aware that server resources are not consumed until the first request. If you need the server address or explicit control over startup, call `await server.listen()` before making requests or accessing `server.address`.","message":"The `TestServer` instance does not immediately start listening on a port upon instantiation. The HTTP server only starts when the first request is made via `server.fetch()` or explicitly by calling `server.listen()`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Instead of `new TestServer(app)`, use `new TestServer(app.callback())` for Koa applications.","message":"When testing Koa applications, you must pass `app.callback()` to the `TestServer` constructor, not the Koa `Application` instance directly. This is due to Koa's architecture expecting a middleware function for HTTP server integration.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Switch to ES Module `import` syntax: `import { TestServer } from 'fetch-test-server';`. Ensure your `package.json` specifies `\"type\": \"module\"` or use `.mjs` file extensions for ES Modules.","cause":"Attempting to use CommonJS `require()` in an ES Module environment (or with a version of `fetch-test-server` that is ESM-only).","error":"ReferenceError: require is not defined in ES module scope\n    at file://<path>/test.js:1:19\n    at ModuleJob.run (node:internal/modules/esm/module_job:194:25)"},{"fix":"For Koa apps, instantiate `TestServer` with `new TestServer(app.callback())`.","cause":"Occurs when passing a Koa `Application` object directly to `TestServer` constructor instead of its `callback()` method.","error":"TypeError: The 'listener' argument must be of type function. Received an instance of Application"}],"ecosystem":"npm"}