Registry / testing / test-server-sdk

test-server-sdk

JSON →
library0.2.9jsnpmunverified

The `test-server-sdk` is a TypeScript SDK designed to provide client-side interaction with a companion `test-server` for robust HTTP and WebSocket request recording and replaying. This package facilitates deterministic and isolated testing by allowing developers to capture network traffic and simulate server responses. It's currently on version 0.2.9 and exhibits a rapid release cadence with frequent minor updates, focusing on new features and bug fixes. Key functionalities include recording and replaying HTTP and WebSocket requests, supporting dynamic subdirectory recording paths, streaming capabilities, and redacting sensitive information from response bodies. A notable differentiator is its ability to manage recording formats, which was updated to a JSON serializable format in v0.2.6, enhancing interoperability and storage. This SDK is a core component for integrating `test-server` capabilities into TypeScript-based test environments.

npm install test-server-sdk
INSTALL
IMPORT
SIG · TEST-SERVER-SDK
T
test-server-sdk
testingjavascriptv0.2.9
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

TestServer
import { TestServer } from 'test-server-sdk';
const TestServer = require('test-server-sdk').TestServer;
ESM is the recommended import style for this TypeScript SDK. CommonJS `require` might work but is not idiomatic and can lead to type issues.
TestServerOptions
import { TestServerOptions } from 'test-server-sdk';
import { Options } from 'test-server-sdk';
This type defines configuration for the `TestServer` instance. Ensure you're importing the correct interface name, typically suffixed with 'Options' or 'Config'.
RecordingMode
import { RecordingMode } from 'test-server-sdk';
An enum used to specify the operational mode of the TestServer (e.g., Record, Replay, Passthrough). This helps control server behavior during testing.

This quickstart demonstrates how to initialize, start, and interact with the `TestServer` in `Record` mode to capture HTTP requests. It sets up a local directory for recordings, sends a sample request through the proxy, and ensures the server is properly shut down.

import { TestServer, RecordingMode, TestServerOptions } from 'test-server-sdk'; import fetch from 'node-fetch'; // For example HTTP client import * as path from 'path'; import * as fs from 'fs'; async function runTestScenario() { const recordingsDir = path.join(__dirname, 'recordings'); if (!fs.existsSync(recordingsDir)) { fs.mkdirSync(recordingsDir); } const serverOptions: TestServerOptions = { port: 9000, recordingPath: recordingsDir, mode: RecordingMode.Record, // Start in recording mode // Assume health check path for the test server itself healthPath: '/health' }; const testServer = new TestServer(serverOptions); try { console.log('Starting Test Server in Record mode...'); await testServer.start(); console.log(`Test Server listening on http://localhost:${serverOptions.port}`); // Make a request to be recorded console.log('Making a request to the test server...'); const response = await fetch(`http://localhost:${serverOptions.port}/api/data?id=123`); const data = await response.json(); console.log('Received data:', data); // In a real test, you'd assert on `data` or switch to replay mode for subsequent runs. } catch (error) { console.error('Test scenario failed:', error); } finally { console.log('Stopping Test Server...'); await testServer.stop(); console.log('Test Server stopped.'); } } runTestScenario().catch(err => console.error('Unhandled scenario error:', err));
Debug
Known issues
breakingThe internal recording format changed to a JSON serializable structure. Existing recordings made with versions prior to v0.2.6 may not be compatible with newer SDK versions for replay, requiring regeneration of test data.
fix
Review existing test recordings. If they were created with versions older than 0.2.6, regenerate them using the latest SDK version. Ensure your CI/CD pipelines use a consistent SDK version for recording and replay.
affects: >=0.2.6
gotchaThe SDK is designed to work with a separate `test-server` binary. This package provides the TypeScript client, but the actual proxying and recording functionality depends on the `test-server` process being run externally or managed by this SDK. Ensure the `test-server` is accessible and correctly configured (e.g., firewall rules, port availability).
fix
Verify that the `test-server` executable is installed and running, or that the SDK is configured to launch and manage it. Consult the `test-server`'s documentation for its setup and operational requirements.
affects: >=0.1.0
gotchaDynamic subdirectory recording paths were introduced, which might change default recording locations or require explicit configuration for managing test data. If you relied on a flat recording structure, this could lead to recordings not being found.
fix
Explicitly configure the `recordingPath` and verify the expected directory structure for your recordings. Update any test setup or teardown logic that relies on specific file paths or discovery mechanisms.
affects: >=0.2.8
Errors
Common errors & fixes
Error: listen EADDRINUSE :::9000
The specified port for the `TestServer` is already in use by another process on your system.
fix
Choose a different port for the `TestServer` or ensure no other application is listening on that port before running your tests. You can use a utility like `lsof -i :9000` (macOS/Linux) or `netstat -ano | findstr :9000` (Windows) to identify the conflicting process.
TypeError: TestServer is not a constructor
This error typically indicates an incorrect import statement, often when attempting to use CommonJS `require` syntax with an ESM-first TypeScript library, or attempting a default import when only named exports are available.
fix
Ensure you are using named imports with modern TypeScript/ESM syntax: `import { TestServer } from 'test-server-sdk';`. If using CommonJS, it might require `const { TestServer } = require('test-server-sdk');` but ESM is preferred.
Error: ENOENT: no such file or directory, stat './recordings/some-test.json'
The `recordingPath` specified in `TestServerOptions` either does not exist or the process lacks the necessary write permissions to create or access files within it.
fix
Ensure the directory specified by `recordingPath` exists before starting the `TestServer`. You can add `fs.mkdirSync(recordingsDir, { recursive: true });` in your setup code. Also, check that your application has read/write permissions for that directory.
Upgrade
Version history
0.2.9latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
16 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
test-server-sdk — npm install test-server-sdk · libregistry