serve-once

library3.0.2jsnpmunverified

A utility for testing Express middleware by serving exactly one HTTP request then closing the server. It creates an HTTP server on a free port, runs the middleware, serves one request, and resolves with the response body. The current stable version is 3.0.2, released in early 2024. It supports GET, POST, PUT, DELETE, HEAD, and other methods. The package was rewritten in v3 to remove node-fetch dependency and requires Node >=18. It returns responses as string, JSON, buffer, or stream. It is lightweight and similar to supertest but simpler and focused on single-request testing.

testing http-networking web-framework

npm install serve-once

github ↗package ↗

INSTALL

IMPORT

SIG · SERVE-ONCE

serve-once

testingjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

request

✓ import { createRequire } from 'module'; const require = createRequire(import.meta.url); const { request } = require('serve-once')(middleware)

✗ import { request } from 'serve-once'

serve-once is a factory function that takes middleware and returns an object with request methods. It is not a named export in ESM. Use CommonJS require or wrap with createRequire.

request.get

✓ const { request } = require('serve-once')(middleware); request.get('/path')

✗ const request = require('serve-once')(middleware).request.get

request is a function with methods like .get, .put, .post attached. Destructure or call as above.

factory function

✓ const serveOnce = require('serve-once'); const { request } = serveOnce(middleware, defaultOptions)

✗ const request = require('serve-once')(middleware).request

The default export is a factory that takes middleware and optional default options. It returns an object with a request function.

Demonstrates basic usage: create server with middleware, make GET request, get response as string. Also shows request.get() with custom options.

import { createRequire } from 'module'; const require = createRequire(import.meta.url); const pullout = require('pullout'); const serveOnce = require('serve-once'); const middleware = (options = 'hello') => (req, res) => { res.end(JSON.stringify(options)); }; const { request } = serveOnce(middleware); const response = await request('get', '/'); console.log(response); // 'hello' const result2 = await request.get('/', { options: 'world' }); console.log(result2); // 'world'

Debug

Known issues

breakingv3 drops support for Node < 18. Requires Node >= 18.

fix

Upgrade Node to version 18 or later.

affects: >=3.0.0

deprecatedv3 removed node-fetch dependency; internal HTTP client uses native fetch (available in Node 18+).

fix

Ensure your environment supports global fetch (Node 18+).

affects: >=3.0.0

gotchaThe default export is not a class but a factory function. CommonJS require is typical as there is no named import.

fix

Use const serveOnce = require('serve-once'); const {request} = serveOnce(middleware);

affects: >=1.0.0

gotchaThe request function returns a response body as a string by default. To get JSON, set type option to 'json'.

fix

const result = await request('get', '/', { type: 'json' });

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: request.get is not a function

Calling request.get before initializing the factory or using wrong import.

fix

Ensure you call require('serve-once')(middleware) which returns an object with request method. Use const {request} = serveOnce(middleware); then request.get('/path')

ERR_MODULE_NOT_FOUND: Cannot find module 'serve-once'

Importing serve-once as a named export in ESM.

fix

Use CommonJS require via createRequire or use dynamic import: const serveOnce = (await import('serve-once')).default;

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

pulloutrequiredUsed to extract the request body as a stream for methods like PUT/POST

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/coderaiser/node-serve-once ↗

packagehttps://www.npmjs.com/package/serve-once ↗