{"id":15409,"library":"wiremock-captain","title":"WireMock Captain","description":"WireMock Captain is a Node.js library (supporting TypeScript and JavaScript) designed to simplify integration testing of HTTP APIs by providing a programmatic interface to the WireMock simulator. Currently at version 4.1.3, this library is actively maintained and used in commercial products, emphasizing a stable release cadence. Its core differentiator lies in offering a native TypeScript/JavaScript experience for configuring and interacting with the Java-based WireMock service, which typically runs in a Docker container. This approach bypasses the limitations of in-process mocks (which often lack real-world accuracy) and the complexities of testing against live non-production service instances, providing a fast, full-featured, and debuggable solution for API mocking without requiring Java tooling for the test runner.","status":"active","version":"4.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/wbd-open-source/wiremock-captain","tags":["javascript","api","captain","integration","jest","test","testing","typescript","wiremock"],"install":[{"cmd":"npm install wiremock-captain","lang":"bash","label":"npm"},{"cmd":"yarn add wiremock-captain","lang":"bash","label":"yarn"},{"cmd":"pnpm add wiremock-captain","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime dependency; WireMock Captain interfaces with an external WireMock instance, typically run as a Docker container.","package":"WireMock (Docker)","optional":false},{"reason":"Commonly used testing framework, although WireMock Captain is framework-agnostic.","package":"Jest","optional":true},{"reason":"Used for development and type safety, though the library also supports plain JavaScript.","package":"TypeScript","optional":true}],"imports":[{"note":"The primary class for connecting to and configuring a running WireMock instance. Prefer ESM `import` syntax in modern Node.js environments.","wrong":"const { WireMock } = require('wiremock-captain');","symbol":"WireMock","correct":"import { WireMock } from 'wiremock-captain';"},{"note":"TypeScript interface for defining the structure of a WireMock request stub. Use `import type` for type-only imports to avoid bundling issues.","wrong":"import { IWireMockRequest } from 'wiremock-captain';","symbol":"IWireMockRequest","correct":"import type { IWireMockRequest } from 'wiremock-captain';"},{"note":"TypeScript interface for defining the structure of a WireMock response stub. Use `import type` for type-only imports.","wrong":"import { IWireMockResponse } from 'wiremock-captain';","symbol":"IWireMockResponse","correct":"import type { IWireMockResponse } from 'wiremock-captain';"}],"quickstart":{"code":"import { WireMock } from 'wiremock-captain';\nimport axios from 'axios'; // Example HTTP client\n\ndescribe('API Integration Test with WireMock Captain', () => {\n  const wiremockEndpoint = 'http://localhost:8080';\n  let mock: WireMock;\n\n  // Ensure WireMock Docker container is running before tests\n  // docker run -itd --rm -p 8080:8080 --name mocked-service wiremock/wiremock:3.9.1\n\n  beforeAll(() => {\n    mock = new WireMock(wiremockEndpoint);\n  });\n\n  beforeEach(async () => {\n    await mock.resetAll(); // Clear all previous stubs and scenarios\n  });\n\n  afterAll(async () => {\n    await mock.resetAll();\n    // Optionally, stop the WireMock container if managed by the test runner\n    // e.g., using 'docker stop mocked-service'\n  });\n\n  test('should mock a GET request and receive the predefined response', async () => {\n    const request = {\n      method: 'GET',\n      endpoint: '/api/resource/123',\n      headers: { 'Accept': 'application/json' }\n    };\n    const mockedResponse = {\n      status: 200,\n      body: { id: '123', name: 'Mocked Resource' },\n      headers: { 'Content-Type': 'application/json' }\n    };\n\n    await mock.register(request, mockedResponse);\n\n    const response = await axios.get(`${wiremockEndpoint}/api/resource/123`);\n\n    expect(response.status).toBe(200);\n    expect(response.data).toEqual({ id: '123', name: 'Mocked Resource' });\n    \n    // Verify WireMock received the request (optional but good practice)\n    const receivedRequests = await mock.getAllRequests();\n    expect(receivedRequests.length).toBe(1);\n    expect(receivedRequests[0].url).toContain('/api/resource/123');\n  });\n\n  test('should handle a POST request with specific body matching', async () => {\n    const postRequest = {\n      method: 'POST',\n      endpoint: '/api/items',\n      body: { item: 'new item' }\n    };\n    const postResponse = {\n      status: 201,\n      body: { message: 'Item created' },\n      headers: { 'Content-Type': 'application/json' }\n    };\n\n    await mock.register(postRequest, postResponse);\n\n    const response = await axios.post(`${wiremockEndpoint}/api/items`, { item: 'new item' });\n\n    expect(response.status).toBe(201);\n    expect(response.data).toEqual({ message: 'Item created' });\n  });\n});","lang":"typescript","description":"Demonstrates how to set up, register stubs for GET and POST requests, and verify interactions with a WireMock instance using WireMock Captain in a typical Jest testing environment. Requires an external WireMock Docker container."},"warnings":[{"fix":"Ensure Docker is installed and a WireMock container is running and accessible on the configured endpoint (e.g., `http://localhost:8080`) before running tests.","message":"WireMock Captain requires an external WireMock instance to be running, typically in a Docker container (e.g., `docker run -p 8080:8080 wiremock/wiremock:3.9.1`). It does not bundle or manage the WireMock server itself. Failure to start WireMock will result in connection errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the official WireMock 4.x migration guide for the specific WireMock version you are using. Review WireMock Captain's documentation for any updates or adapters related to WireMock 4.x.","message":"The underlying WireMock Java library (which WireMock Captain interacts with) has undergone significant changes in its 4.x beta releases, including breaking API changes, refactoring of core dependencies, and changes to HTTP header normalization. While WireMock Captain abstracts many of these, direct interactions with WireMock's API via its JSON DSL or specific features might require adjustments.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade your Node.js runtime to version 22.11.0 or newer to ensure full compatibility. Consider using a Node.js version manager (e.g., `nvm`) to easily switch between versions.","message":"The library specifies Node.js engine requirement `>=22.11.0`. Using older Node.js versions might lead to compatibility issues or unexpected runtime errors, particularly with modern JavaScript features or module resolution.","severity":"gotcha","affected_versions":"<22.11.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Start the WireMock Docker container: `docker run -itd --rm -p 8080:8080 --name my-mocked-service wiremock/wiremock:3.9.1`. Verify the `wiremockEndpoint` in your tests matches the running WireMock service.","cause":"WireMock Docker container is not running or is not accessible on the specified host and port (e.g., `http://localhost:8080`).","error":"connect ECONNREFUSED 127.0.0.1:8080"},{"fix":"Instantiate the `WireMock` class using the `new` keyword: `const mock = new WireMock(wiremockEndpoint);`.","cause":"Attempted to call `WireMock` as a function (e.g., `WireMock(endpoint)`) instead of instantiating it with `new`.","error":"TypeError: Class constructor WireMock cannot be invoked without 'new'"},{"fix":"Update your import statements to use ES module syntax: `import { WireMock } from 'wiremock-captain';`. Ensure your `package.json` has `\"type\": \"module\"` if you intend to use ESM globally, or name your files `.mjs`.","cause":"Attempting to import `wiremock-captain` using CommonJS `require()` syntax in an ESM-only context, or in a project configured for ESM.","error":"Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: ...wiremock-captain/dist/index.js"}],"ecosystem":"npm"}