Registry / testing / test-listen

test-listen

JSON →
library1.1.0jsnpmunverified

test-listen is a JavaScript utility for generating URLs with ephemeral ports, specifically designed for testing HTTP servers. It accepts an instance of Node.js's native `http.Server` and returns a promise that resolves to a unique URL string, typically in the format `http://localhost:{port}`. This mechanism is crucial for ensuring isolated and repeatable test environments, as each test run can utilize a distinct, automatically assigned port, thereby preventing conflicts and ensuring test integrity. The current stable version is 1.1.0, and the package generally maintains a stable release cadence with updates focused on minor improvements and maintenance. Its primary strength lies in its simplicity and direct integration with standard Node.js HTTP servers, providing an `async`/`await`-ready solution that streamlines the setup for robust server test suites. It differentiates itself by offering a straightforward, minimal API for a very specific and common testing requirement without introducing complex abstractions.

testing
npm install test-listen
github ↗package ↗
INSTALL
IMPORT
SIG · TEST-LISTEN
T
test-listen
testingjavascriptv1.1.0
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.

listen
✓ import listen from 'test-listen'
✗ import { listen } from 'test-listen'
The primary export is a default export, typically used for ESM.
listen
✓ const listen = require('test-listen')
✗ const { listen } = require('test-listen')
CommonJS usage for the default export. Destructuring will result in `undefined`.

Demonstrates how to start an HTTP server, get an ephemeral URL using `test-listen`, and verify the URL format, ensuring the server is properly closed.

const http = require('http'); const listen = require('test-listen'); const assert = require('assert'); async function setupTestServer() { const server = http.createServer((req, res) => { res.writeHead(200, { 'Content-Type': 'text/plain' }); res.end('Hello from ephemeral server!'); }); let url; try { url = await listen(server); console.log(`Test server is listening at: ${url}`); assert.ok(url.startsWith('http://localhost:'), 'URL should start with http://localhost:'); assert.ok(/\d+$/.test(url.split(':')[2]), 'URL should contain a port number'); // Simulate a request to the server (e.g., in a test runner) // In a real test, you'd make an actual HTTP request here and assert its response } catch (error) { console.error('Failed to start test server:', error); process.exit(1); } finally { // Ensure the server is closed after tests complete server.close(() => console.log('Test server closed.')); } } // Run the quickstart example setupTestServer().catch(console.error);
Debug
Known issues
gotcha`test-listen` returns a Promise. Forgetting to `await` its call will result in a Promise object being returned instead of the URL string, leading to unexpected behavior or an UnhandledPromiseRejectionWarning.
fix
Always use `await listen(server)` within an `async` function, or chain with `.then()`.
affects: >=1.0.0
gotchaThe port number returned by `test-listen` is ephemeral and non-deterministic. Do not hardcode port numbers in your tests; instead, parse the returned URL to extract the port if needed, or rely on URL functions.
fix
Assert against the URL's structure (e.g., `startsWith('http://localhost:')`) rather than a specific port number.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: listen is not a function
Attempting to destructure the `test-listen` module in CommonJS (`const { listen } = require('test-listen')`) or importing named in ESM (`import { listen } from 'test-listen'`) when it exports a default function.
fix
For CommonJS: `const listen = require('test-listen')`. For ESM: `import listen from 'test-listen'`.
UnhandledPromiseRejectionWarning: Unhandled promise rejection.
Calling `listen(server)` without `await` in an `async` context, or without `.then().catch()` handlers in a Promise-based context, leading to an unhandled promise.
fix
Ensure `await listen(server)` is used, or attach `.then()` and `.catch()` handlers to the promise returned by `listen(server)`.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
githubhttps://github.com/zeit/test-listen ↗
packagehttps://www.npmjs.com/package/test-listen ↗
test-listen — npm install test-listen · libregistry