https://github.com/imposter-project/imposter-js
JavaScript bindings for the Imposter mock engine.
https://github.com/imposter-project/imposter-js
mock nodejs openapi rest-api soap testing wsdl
Last synced: 7 months ago
JSON representation
JavaScript bindings for the Imposter mock engine.
- Host: GitHub
- URL: https://github.com/imposter-project/imposter-js
- Owner: imposter-project
- Created: 2021-09-15T15:05:30.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-05-29T12:03:18.000Z (8 months ago)
- Last Synced: 2025-06-03T16:02:36.468Z (8 months ago)
- Topics: mock, nodejs, openapi, rest-api, soap, testing, wsdl
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@imposter-js/imposter
- Size: 896 KB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Imposter Mock Engine [](https://github.com/imposter-project/imposter-js/actions/workflows/ci.yaml)
Bindings for using the [Imposter mock engine](https://www.imposter.sh) in JavaScript/Node.js.
Embed live HTTP mocks within your tests, based on OpenAPI specification files or plain REST APIs.
## Usage
```js
const {mocks} = require('@imposter-js/imposter');
// start a mock from an OpenAPI spec file on a specific port
await mocks.builder()
.withPort(8080)
.withOpenApiSpec('/path/to/openapi_spec.yaml')
.start();
// call one of the endpoints defined in the OpenAPI spec
const response = await axios.get('http://localhost:8080/products');
// print JSON returned from the mock
console.log(response.data);
```
This is just a simple example. Your mocks can have dynamic responses, request validation against an OpenAPI schema, data capture, performance delays etc...
> See the [examples](https://github.com/imposter-project/imposter-js/tree/main/examples) directory for a Node.js project with many examples.
## Quickstart
Imposter is available as an [npm package](https://www.npmjs.com/package/@imposter-js/imposter).
Install with npm:
npm install --save-dev @imposter-js/imposter
Or add to your `package.json` as a dev dependency:
```json
"devDependencies": {
"@imposter-js/imposter": "*"
}
```
> See available versions on the [npm registry](https://www.npmjs.com/package/@imposter-js/imposter?activeTab=versions)
## Prerequisites
- Node.js 20+ installed.
- Install **[Imposter CLI](https://github.com/imposter-project/imposter-cli/blob/main/docs/install.md)**. Supports macOS, Linux, Windows.
- 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)).
## Examples
> See the [examples](https://github.com/imposter-project/imposter-js/tree/main/examples) directory for a Node.js project with many examples.
### Example with Jest
Here's an example using Jest:
```js
const {mocks} = require('@imposter-js/imposter');
jest.setTimeout(30000);
beforeAll(async () => {
// path to Imposter config directory
const configDir = `/path/to/order-api`;
// start a mock on a specific port
await mocks.start(configDir, 8080);
});
afterAll(async () => {
mocks.stopAll();
});
it('places an order', async () => {
// configure the unit under test
const orderService = new OrderService('http://localhost:8080/orders');
// call your unit under test, which invokes the mock
const confirmation = await orderService.placeOrder('product-05');
// assert values returned by the mock
expect(confirmation.total).toEqual(18.00);
});
```
### Example using just an OpenAPI file
Here's an example mock that just uses an OpenAPI file:
```js
// start a mock from a bare OpenAPI spec file
// requests are validated against the spec
const mock = await mocks.builder()
.withOpenApiSpec('/path/to/pet-names-api.yaml')
.withRequestValidation()
.start();
// call the mock
const response = await axios.get(`${mock.baseUrl()}/names`);
// Output: [ 'Fluffy', 'Paws' ]
// This is driven by either the 'examples' property
// in the OpenAPI spec, or the schema of the response.
console.log(response.data);
```
### Example with no config file
Here's an example mock that doesn't require any configuration file:
```js
const builder = mocks.builder().withPlugin('rest');
// add a POST resource with a path parameter
const resource = builder.addResource('/users/{userName}', 'POST');
// capture the userName path parameter from the request
// for later use in the response
resource.captures().fromPath('userName');
// respond with a templated message indicating the user
// was created by name
resource.responds(201)
.withTemplateData('${request.userName} registered')
.withHeader('Content-Type', 'text/plain');
// spin it up
const mock = await builder.start();
// call the mock
const response = await axios.post(`${mock.baseUrl()}/users/alice`);
// Output: alice registered
// This will vary dynamically, based on the request.
console.log(response.data);
```
## Documentation
- [Imposter user documentation](https://docs.imposter.sh) - this is the main documentation
- [Mock engine configuration](https://github.com/imposter-project/imposter-js/blob/main/docs/config.md) - configuration for different engine types
## Features
* run standalone mocks in place of real systems
* turn an OpenAPI/Swagger file into a mock API for testing or QA (even before the real API is built)
* turn a SOAP/WSDL file into a mock API you can run locally or in your CI/CD pipeline
* decouple your integration tests from the cloud/various back-end systems and take control of your dependencies
* validate your API requests against an OpenAPI specification
Send dynamic responses:
- Provide mock responses using static files or customise behaviour based on characteristics of the request.
- Power users can control mock responses with JavaScript.
## Acknowledgements
This project is only possible thanks to the following:
- [Imposter](https://www.imposter.sh)
- [Jest](https://jestjs.io/)