{"id":14973,"library":"test-server-sdk","title":"TypeScript SDK for Test Server","description":"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.","status":"active","version":"0.2.9","language":"javascript","source_language":"en","source_url":"https://github.com/google/test-server","tags":["javascript","test-server","testing","http","proxy","record","replay","typescript"],"install":[{"cmd":"npm install test-server-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add test-server-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add test-server-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM is the recommended import style for this TypeScript SDK. CommonJS `require` might work but is not idiomatic and can lead to type issues.","wrong":"const TestServer = require('test-server-sdk').TestServer;","symbol":"TestServer","correct":"import { TestServer } from 'test-server-sdk';"},{"note":"This type defines configuration for the `TestServer` instance. Ensure you're importing the correct interface name, typically suffixed with 'Options' or 'Config'.","wrong":"import { Options } from 'test-server-sdk';","symbol":"TestServerOptions","correct":"import { TestServerOptions } from 'test-server-sdk';"},{"note":"An enum used to specify the operational mode of the TestServer (e.g., Record, Replay, Passthrough). This helps control server behavior during testing.","symbol":"RecordingMode","correct":"import { RecordingMode } from 'test-server-sdk';"}],"quickstart":{"code":"import { TestServer, RecordingMode, TestServerOptions } from 'test-server-sdk';\nimport fetch from 'node-fetch'; // For example HTTP client\nimport * as path from 'path';\nimport * as fs from 'fs';\n\nasync function runTestScenario() {\n  const recordingsDir = path.join(__dirname, 'recordings');\n  if (!fs.existsSync(recordingsDir)) {\n    fs.mkdirSync(recordingsDir);\n  }\n\n  const serverOptions: TestServerOptions = {\n    port: 9000,\n    recordingPath: recordingsDir,\n    mode: RecordingMode.Record, // Start in recording mode\n    // Assume health check path for the test server itself\n    healthPath: '/health'\n  };\n\n  const testServer = new TestServer(serverOptions);\n\n  try {\n    console.log('Starting Test Server in Record mode...');\n    await testServer.start();\n    console.log(`Test Server listening on http://localhost:${serverOptions.port}`);\n\n    // Make a request to be recorded\n    console.log('Making a request to the test server...');\n    const response = await fetch(`http://localhost:${serverOptions.port}/api/data?id=123`);\n    const data = await response.json();\n    console.log('Received data:', data);\n\n    // In a real test, you'd assert on `data` or switch to replay mode for subsequent runs.\n\n  } catch (error) {\n    console.error('Test scenario failed:', error);\n  } finally {\n    console.log('Stopping Test Server...');\n    await testServer.stop();\n    console.log('Test Server stopped.');\n  }\n}\n\nrunTestScenario().catch(err => console.error('Unhandled scenario error:', err));\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.2.6"},{"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.","message":"The 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).","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Dynamic 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.","severity":"gotcha","affected_versions":">=0.2.8"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The specified port for the `TestServer` is already in use by another process on your system.","error":"Error: listen EADDRINUSE :::9000"},{"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.","cause":"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.","error":"TypeError: TestServer is not a constructor"},{"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.","cause":"The `recordingPath` specified in `TestServerOptions` either does not exist or the process lacks the necessary write permissions to create or access files within it.","error":"Error: ENOENT: no such file or directory, stat './recordings/some-test.json'"}],"ecosystem":"npm"}