Mockoon: The Easiest Way to Mock REST APIs Locally

API mocking is one of those techniques that transforms development speed. When backend services are unavailable, slow, or expensive to call in tests, a local mock server lets you develop and test against realistic API responses without any network dependency.

Mockoon is the simplest tool available for this job. It's a desktop application and CLI that spins up mock REST API servers in minutes, with no code required.

What Is Mockoon?

Mockoon is an open-source API mocking tool with both a graphical desktop application and a CLI. You define routes, response bodies, status codes, and headers through a point-and-click interface, then run the mock server locally.

Unlike code-based mocking libraries, Mockoon runs as an actual HTTP server. Any client — a browser, a mobile app, a terminal curl command — can hit it. This makes it useful far beyond unit tests.

Key characteristics:

• No coding required for basic usage
• Runs as a real local HTTP server
• Supports static and dynamic responses
• Exports to JSON (shareable, version-controllable)
• Available as desktop app (Windows, macOS, Linux) and CLI

Installing Mockoon

Desktop app: Download from mockoon.com. Install the package for your OS and launch.

CLI:

npm install -g @mockoon/cli

The CLI is useful for CI environments and automated testing pipelines where you want a mock server to start and stop programmatically.

Setting Up Your First Mock API

Creating an environment

In the Mockoon desktop app, environments are collections of routes served on a specific port. Click New environment to create one. Give it a name and set a port (default: 3000).

Adding routes

Click the + button in the Routes panel to add a new route. Configure:

• HTTP method: GET, POST, PUT, DELETE, PATCH, etc.
• Path: e.g., /users, /users/:id, /products
• Response status: 200, 201, 404, 500, etc.
• Body: JSON, XML, plain text, or any content type

Example: mocking a user endpoint

Method: GET
Path: /users/:id
Status: 200
Content-Type: application/json
Body:
{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

Running the server

Click Start to launch the server. Your API is now available at http://localhost:3000/users/123.

Dynamic Responses with Faker.js

Static JSON gets repetitive quickly. Mockoon integrates Faker.js for generating realistic dynamic data. Use double curly braces to insert templated values:

{
  "id": "{{faker 'datatype.uuid'}}",
  "name": "{{faker 'name.fullName'}}",
  "email": "{{faker 'internet.email'}}",
  "createdAt": "{{faker 'date.past'}}"
}

Every time this endpoint is called, it returns different data. This is useful for testing how your frontend handles varied inputs.

Response rules and multiple responses

Routes can return different responses based on request conditions. In the route settings, add a Response rule to match:

• Request headers
• Query parameters
• Body content
• Request path parameters

Example: return 404 when the id parameter is 999:

• Add a new response with status 404 and body {"error": "User not found"}
• Set a rule: path param id equals 999

The default response handles all other requests.

CLI Mode for Automated Testing

The Mockoon CLI is designed for integration into test pipelines.

Starting a mock server from the CLI

First, export your environment from the desktop app (File → Export). You get a JSON file describing all routes and settings.

mockoon-cli start --data ./my-environment.json --port 3000

Start the server in the background:

mockoon-cli start --data ./my-environment.json --port 3000 --daemon-off &

Using with Jest

Here's a typical test setup that starts Mockoon before tests run:

// jest.setup.js
const { spawn } = require('child_process');

let mockoonProcess;

beforeAll(async () => {
  mockoonProcess = spawn('mockoon-cli', [
    'start',
    '--data', './mocks/api.json',
    '--port', '3001'
  ]);
  
  // Wait for server to be ready
  await new Promise(resolve => setTimeout(resolve, 1000));
});

afterAll(() => {
  mockoonProcess.kill();
});

Then in tests, configure your HTTP client to point to http://localhost:3001:

// api.test.js
const axios = require('axios');

const client = axios.create({ baseURL: 'http://localhost:3001' });

test('fetches user data', async () => {
  const response = await client.get('/users/1');
  expect(response.status).toBe(200);
  expect(response.data).toHaveProperty('name');
});

Importing OpenAPI Specifications

Mockoon can import OpenAPI (Swagger) specs and automatically generate routes from them. This is a major time-saver when you have an existing API specification.

1. In the desktop app, go to File → Import/Export → Import OpenAPI specification
2. Select your .yaml or .json OpenAPI file
3. Mockoon creates routes for every operation defined in the spec, using example values from the spec as response bodies

The imported routes use your OpenAPI examples as static responses. You can then modify them, add dynamic data, or configure response rules as needed.

Generating specs programmatically

If your team uses Swagger Codegen or similar tools, you can automate the workflow:

# Generate OpenAPI spec from your service
swagger-codegen generate -i http://localhost:8080/api-docs -l openapi

<span class="hljs-comment"># Import to Mockoon CLI
mockoon-cli start --data generated-spec.json --port 3001

Proxy Mode for Selective Mocking

Mockoon supports a proxy mode where it forwards requests to a real upstream API but intercepts specific routes. This is useful during development when you want to mock only the endpoints that aren't built yet.

Enable proxy mode in environment settings:

1. Go to Environment → Proxy
2. Enable proxy and set the upstream URL (e.g., http://api.yourapp.com)
3. Add routes for endpoints you want to intercept

Requests matching your routes return mocked responses. Everything else is forwarded to the upstream server.

Using Mockoon in CI/CD

For CI pipelines, install the CLI and use environment JSON files checked into your repository.

# GitHub Actions example
- name: Start mock server
  run: |
    npm install -g @mockoon/cli
    mockoon-cli start --data ./mocks/api.json --port 3001 &
    npx wait-on http://localhost:3001/health

- name: Run integration tests
  run: npm test

Check the environment JSON into version control so the mock definitions evolve with your codebase.

Sharing Environments with Your Team

Mockoon environment files are plain JSON. Check them into your repository and everyone on the team uses the same mock definitions.

Suggested structure:

project/
  mocks/
    api.json           # Main API mock
    payment-service.json  # Payment service mock
    auth-service.json  # Auth service mock

When the real API changes, update the mock file and commit. Your CI pipeline and teammates stay in sync.

Handling CORS

If your frontend makes requests to the mock server from a different origin, you'll hit CORS errors. Mockoon handles this with a single toggle.

In environment settings, enable CORS under the Headers section. Mockoon will add the appropriate Access-Control-Allow-Origin headers to all responses.

Recording Real API Responses

Mockoon can record actual API responses and save them as mock definitions. This is useful for capturing complex response shapes without manually writing JSON.

1. Enable Recording mode in the environment settings
2. Set the upstream URL to your real API
3. Make requests through Mockoon
4. Stop recording — all captured request/response pairs are saved as routes

This builds a library of realistic mock responses without manual effort.

When to Use Mockoon vs Code-Based Mocks

HelpMeTest Integration

Once you have Mockoon serving a mock API locally, you can write HelpMeTest tests that run against it — validating your application against realistic API behavior without depending on the real service.

Use the proxy feature to start the local Mockoon server, then point your HelpMeTest scenarios at it. When the real API is ready, swap the URL and your tests continue to work without modification.

Conclusion

Mockoon removes the friction from API mocking. The desktop GUI makes it accessible to non-developers. The CLI integrates cleanly into automated pipelines. OpenAPI import means you don't start from scratch when a spec already exists.

For teams that want a fast, shareable, code-free approach to API mocking, Mockoon is worth adding to your testing toolkit.

Start at mockoon.com — the basic version is free and covers most use cases.