{"id":29013359,"url":"https://github.com/imposter-project/imposter-js","last_synced_at":"2026-04-04T21:05:23.737Z","repository":{"id":45278772,"uuid":"406815346","full_name":"imposter-project/imposter-js","owner":"imposter-project","description":"JavaScript bindings for the Imposter mock engine.","archived":false,"fork":false,"pushed_at":"2025-05-29T12:03:18.000Z","size":918,"stargazers_count":2,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-03T16:02:36.468Z","etag":null,"topics":["mock","nodejs","openapi","rest-api","soap","testing","wsdl"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@imposter-js/imposter","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imposter-project.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-09-15T15:05:30.000Z","updated_at":"2025-05-29T12:02:21.000Z","dependencies_parsed_at":"2023-12-27T16:27:19.999Z","dependency_job_id":"adcca4e3-25d7-4443-8320-f707cde2f5e0","html_url":"https://github.com/imposter-project/imposter-js","commit_stats":{"total_commits":86,"total_committers":2,"mean_commits":43.0,"dds":0.2325581395348837,"last_synced_commit":"76784fa118bd3ff48601a12213fea628662c17ad"},"previous_names":["imposter-project/imposter-js","gatehill/imposter-js"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/imposter-project/imposter-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imposter-project%2Fimposter-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imposter-project%2Fimposter-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imposter-project%2Fimposter-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imposter-project%2Fimposter-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imposter-project","download_url":"https://codeload.github.com/imposter-project/imposter-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imposter-project%2Fimposter-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261940790,"owners_count":23233603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mock","nodejs","openapi","rest-api","soap","testing","wsdl"],"created_at":"2025-06-25T19:32:16.191Z","updated_at":"2026-04-04T21:05:23.729Z","avatar_url":"https://github.com/imposter-project.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Imposter Mock Engine [![CI](https://github.com/imposter-project/imposter-js/actions/workflows/ci.yaml/badge.svg)](https://github.com/imposter-project/imposter-js/actions/workflows/ci.yaml)\n\nBindings for using the [Imposter mock engine](https://www.imposter.sh) in JavaScript/Node.js.\n\nEmbed live HTTP mocks within your tests, based on OpenAPI specification files or plain REST APIs.\n\n## Usage\n\n```js\nconst {mocks} = require('@imposter-js/imposter');\n\n// start a mock from an OpenAPI spec file on a specific port\nawait mocks.builder()\n    .withPort(8080)\n    .withOpenApiSpec('/path/to/openapi_spec.yaml')\n    .start();\n\n// call one of the endpoints defined in the OpenAPI spec\nconst response = await axios.get('http://localhost:8080/products');\n\n// print JSON returned from the mock\nconsole.log(response.data);\n```\n\nThis is just a simple example. Your mocks can have dynamic responses, request validation against an OpenAPI schema, data capture, performance delays etc...\n\n\u003e See the [Examples](#examples) section for complete sample projects.\n\n## Quickstart\n\nImposter is available as an [npm package](https://www.npmjs.com/package/@imposter-js/imposter).\n\nInstall with npm:\n\n    npm install --save-dev @imposter-js/imposter\n\nOr add to your `package.json` as a dev dependency:\n\n```json\n\"devDependencies\": {\n  \"@imposter-js/imposter\": \"*\"\n}\n```\n\n\u003e See available versions on the [npm registry](https://www.npmjs.com/package/@imposter-js/imposter?activeTab=versions)\n\n## Prerequisites\n\n- Node.js 20+ installed.\n- Install **[Imposter CLI](https://github.com/imposter-project/imposter-cli/blob/main/docs/install.md)**. Supports macOS, Linux, Windows.\n- Ensure you satisfy the CLI requirements (either [Docker installed](https://docs.docker.com/get-docker/) and running, or a [JVM installed](https://github.com/imposter-project/imposter-cli/blob/main/docs/jvm_engine.md)).\n\n## Examples\n\nThe following example projects are available:\n\n- [JavaScript with Jest](https://github.com/imposter-project/imposter-js/tree/main/examples/example-javascript)\n- [TypeScript (ESM) with Jest](https://github.com/imposter-project/imposter-js/tree/main/examples/example-typescript-esm)\n- [TypeScript with Vitest](https://github.com/imposter-project/imposter-js/tree/main/examples/example-vitest)\n\n### Example with Jest\n\nHere's an example using Jest:\n\n```js\nconst {mocks} = require('@imposter-js/imposter');\n\njest.setTimeout(30000);\n\nbeforeAll(async () =\u003e {\n    // path to Imposter config directory\n    const configDir = `/path/to/order-api`;\n\n    // start a mock on a specific port\n    await mocks.start(configDir, 8080);\n});\n\nafterAll(async () =\u003e {\n    mocks.stopAll();\n});\n\nit('places an order', async () =\u003e {\n    // configure the unit under test\n    const orderService = new OrderService('http://localhost:8080/orders');\n\n    // call your unit under test, which invokes the mock\n    const confirmation = await orderService.placeOrder('product-05');\n\n    // assert values returned by the mock\n    expect(confirmation.total).toEqual(18.00);\n});\n```\n\n### Example using just an OpenAPI file\n\nHere's an example mock that just uses an OpenAPI file:\n\n```js\n// start a mock from a bare OpenAPI spec file\n// requests are validated against the spec\nconst mock = await mocks.builder()\n    .withOpenApiSpec('/path/to/pet-names-api.yaml')\n    .withRequestValidation()\n    .start();\n\n// call the mock\nconst response = await axios.get(`${mock.baseUrl()}/names`);\n\n// Output: [ 'Fluffy', 'Paws' ]\n// This is driven by either the 'examples' property\n// in the OpenAPI spec, or the schema of the response.\nconsole.log(response.data);\n```\n\n### Example with no config file\n\nHere's an example mock that doesn't require any configuration file:\n\n```js\nconst builder = mocks.builder().withPlugin('rest');\n\n// add a POST resource with a path parameter\nconst resource = builder.addResource('/users/{userName}', 'POST');\n\n// capture the userName path parameter from the request\n// for later use in the response\nresource.captures().fromPath('userName');\n\n// respond with a templated message indicating the user\n// was created by name\nresource.responds(201)\n    .withTemplateData('${stores.request.userName} registered')\n    .withHeader('Content-Type', 'text/plain');\n\n// spin it up\nconst mock = await builder.start();\n\n// call the mock\nconst response = await axios.post(`${mock.baseUrl()}/users/alice`);\n\n// Output: alice registered\n// This will vary dynamically, based on the request.\nconsole.log(response.data);\n```\n\n## Documentation\n\n- [Imposter user documentation](https://docs.imposter.sh) - this is the main documentation\n- [Mock engine configuration](https://github.com/imposter-project/imposter-js/blob/main/docs/config.md) - configuration for different engine types\n\n## Features\n\n* run standalone mocks in place of real systems\n* turn an OpenAPI/Swagger file into a mock API for testing or QA (even before the real API is built)\n* turn a SOAP/WSDL file into a mock API you can run locally or in your CI/CD pipeline\n* decouple your integration tests from the cloud/various back-end systems and take control of your dependencies\n* validate your API requests against an OpenAPI specification\n\nSend dynamic responses:\n\n- Provide mock responses using static files or customise behaviour based on characteristics of the request.\n- Power users can control mock responses with JavaScript.\n\n## Acknowledgements\n\nThis project is only possible thanks to the following:\n\n- [Imposter](https://www.imposter.sh)\n- [Jest](https://jestjs.io/)\n- [Vitest](https://vitest.dev/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimposter-project%2Fimposter-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimposter-project%2Fimposter-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimposter-project%2Fimposter-js/lists"}