{"id":18933,"library":"wiremock-rest-client","title":"WireMock REST Client","description":"Lightweight TypeScript REST client for interacting with a running WireMock server (v1.11.0) via its OpenAPI 3.0 endpoints. Provides programmatic access to stub mappings, recordings, requests, and scenarios. Supports TypeScript types, global reset, shutdown, and bulk operations from files/directories. Actively maintained with monthly releases. Key differentiators: full API coverage, TypeScript-first, file-based mapping creation, and proxy/header configuration.","status":"active","version":"1.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/kwoding/wiremock-rest-client","tags":["javascript","wiremock","mock","stub","automation","test","typescript"],"install":[{"cmd":"npm install wiremock-rest-client","lang":"bash","label":"npm"},{"cmd":"yarn add wiremock-rest-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add wiremock-rest-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only; CommonJS require will fail. Default export is not available.","wrong":"const WireMockRestClient = require('wiremock-rest-client')","symbol":"WireMockRestClient","correct":"import { WireMockRestClient } from 'wiremock-rest-client'"},{"note":"TypeScript type for stub mapping objects. Also exported: DelayDefinition, RecordSpec, RequestPattern, ContentPattern.","symbol":"StubMapping","correct":"import { StubMapping } from 'wiremock-rest-client'"},{"note":"When only using type annotations, prefer type import to avoid runtime side effects.","wrong":"import { WireMockRestClient } from 'wiremock-rest-client' (for type-only usage)","symbol":"WireMockRestClient (with type import)","correct":"import type { WireMockRestClient } from 'wiremock-rest-client'"},{"note":"Constructor requires WireMock server base URL as first argument. Optional config object second.","wrong":"new WireMockRestClient()","symbol":"new WireMockRestClient(url)","correct":"new WireMockRestClient('http://localhost:8080')"}],"quickstart":{"code":"import { WireMockRestClient } from 'wiremock-rest-client';\n\nasync function main() {\n  const wireMock = new WireMockRestClient('http://localhost:8080');\n\n  // Reset all state\n  await wireMock.global.resetAll();\n\n  // Create a stub mapping\n  const stubMapping = {\n    request: {\n      method: 'GET',\n      urlPathPattern: '/api/hello'\n    },\n    response: {\n      status: 200,\n      jsonBody: { message: 'Hello World' },\n      headers: {\n        'Content-Type': 'application/json'\n      }\n    }\n  };\n  const created = await wireMock.mappings.createMapping(stubMapping);\n  console.log('Created mapping:', created);\n\n  // Get all mappings\n  const allMappings = await wireMock.mappings.getAllMappings();\n  console.log('Total mappings:', allMappings.meta?.total || 'N/A');\n\n  // Create from file (relative to cwd)\n  await wireMock.mappings.createMappingFromFile('./stubs/hello.json');\n\n  // Shutdown server\n  await wireMock.global.shutdown();\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates client initialization, resetting server state, creating stub mappings via object and file, fetching all mappings, and graceful shutdown."},"warnings":[{"fix":"Update code to use await or .then(). All methods now return Promise.","message":"Version 1.0.0 changed all methods to return Promises. Synchronous calls will no longer work.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade Node.js to >=14.15.0 or >=16.0.0 (LTS).","message":"Version 2.0.0 (future) may drop Node.js 12 support. End-of-life Node versions are not tested.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use StubMapping type or follow OpenAPI spec shape explicitly.","message":"The mappings.createMapping method with plain object signature will be deprecated in favor of typed StubMapping.","severity":"deprecated","affected_versions":">=1.5.0"},{"fix":"Use absolute paths or ensure correct working directory. Call path.resolve(__dirname, 'stubs/hello.json') if needed.","message":"When using createMappingFromFile, the file path is relative to process.cwd(), not the source file location.","severity":"gotcha","affected_versions":"all"},{"fix":"Only call shutdown() in cleanup hooks (e.g., afterAll) and ensure no other tests depend on the same server.","message":"The global.shutdown() method will terminate the WireMock server process. Be careful in test suites where the server is shared.","severity":"gotcha","affected_versions":"all"},{"fix":"Start WireMock with --record-mappings or use snapshot functionality alternatively.","message":"Recording operations (startRecording, stopRecording, etc.) require WireMock server to be running in record mode. Not available in standalone jar without --record-mappings flag.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Change to ES module imports: use import { WireMockRestClient } from 'wiremock-rest-client' and set 'type': 'module' in package.json, or use dynamic import.","cause":"Attempting to require('wiremock-rest-client') in CommonJS project.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Ensure the client is instantiated before calling service methods. No async initialization needed; error typically due to null/undefined variable.","cause":"Accessing wireMock.mappings before client is fully initialized (async issue).","error":"TypeError: Cannot read properties of undefined (reading 'getAllMappings')"},{"fix":"Verify WireMock server is started on expected host/port. Default is http://localhost:8080. Use console to log the URL.","cause":"WireMock server not running or wrong base URL provided to constructor.","error":"HTTPError: Response code 404 (Not Found)"},{"fix":"Call resetAllMappings() before bulk imports, or use updateMapping() to overwrite specific IDs.","cause":"Duplicate stub mapping IDs when using createMappingFromDir or createMappingFromFile with previously stored mappings.","error":"Mapping already exists with ID: ..."},{"fix":"Increase timeout via config: new WireMockRestClient(url, { timeout: 10000 }). Check server logs.","cause":"WireMock server not responding or network issue. Default timeout is 5000ms.","error":"Timeout awaiting 'request' for 5000ms"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}