> For the complete documentation index, see [llms.txt](https://docs.does.qa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.does.qa/guides/use-mock-servers-with-doesqa.md).

# Use mock servers with DoesQA

When a dependency must return canned JSON, run a **mock server** and call it from [Integration API steps](/test-steps/integration/post.md) in your Flow. DoesQA sends HTTP requests to whatever URL you configure. You maintain stub routes and responses in Mockoon, WireMock, or a similar tool.

For APIs your team owns, [seed data with Integration steps](/guides/seed-and-clean-up-with-api-steps.md) against a test environment first. Mock servers fit third-party services and contract-style stubs.

## When to use a mock server

| Situation                                 | Mock server helps                        |
| ----------------------------------------- | ---------------------------------------- |
| Third-party API (payments, CRM, weather)  | Stable responses without live accounts   |
| Backend not ready                         | UI tests against agreed contracts        |
| Parallel tests must not share one backend | Isolated stubs per environment or tenant |
| Error paths                               | Return 4xx or 5xx on demand              |

## Pattern in DoesQA

1. Run **Mockoon** or **WireMock** however your team prefers (desktop, CLI, Docker, or their cloud offerings).
2. Create an Account Value for the mock base URL, for example `$MOCK_API_URL`.
3. Add Integration steps whose **URL** uses that Value: `$MOCK_API_URL/v1/orders`
4. Store responses in the [Value Store](/values/value-store.md) when later UI or API steps need fields from the stub.
5. Run the browser steps against your application as usual.

[Hosted DoesQA Runs](/runs/start-a-run.md) call `$MOCK_API_URL` from DoesQA infrastructure, so the URL must be one those runners can reach.

Overwrite `$MOCK_API_URL` per environment with a [Run Recipe](/configuration/run-recipes.md) or CI [Values](/configuration/ci-cd.md) when staging uses a real API and another Recipe points at a mock.

```mermaid
flowchart LR
  flow["DoesQA Flow"] --> browser["Browser → your app"]
  flow --> api["Integration API steps"]
  api --> mock["Mockoon or WireMock"]
```

## Mockoon

[Mockoon](https://mockoon.com/) runs as a desktop app, through the [CLI](https://mockoon.com/cli/) and [Docker image](https://hub.docker.com/r/mockoon/cli), or on [Mockoon Cloud](https://mockoon.com/cloud/). Pick the option that fits how you work.

Typical setup:

1. Define routes and JSON bodies in Mockoon.
2. Set `$MOCK_API_URL` to the mock's base URL.
3. Call routes from **GET** or **POST** steps. Assert with [**Check JSON Value**](/test-steps/check/check-json-value.md).

## WireMock

[WireMock](https://wiremock.org/) serves stubs from mappings (JSON or Java), self-hosted or on [WireMock Cloud](https://wiremock.io/cloud/). From DoesQA, Integration steps target the WireMock base URL.

Typical setup:

1. Deploy WireMock with your stub mappings.
2. Store the base URL in `$MOCK_API_URL` or per-service Values.
3. Use Integration steps for setup calls the UI depends on, or configure your application (via Account Values) to call WireMock when running against a test build.

## Browser and API traffic

**Integration API steps** call the mock directly. This suits setup, webhooks, or backends your UI calls server-side.

The **browser** loads your application URL from **Open**. When the app must call the mock from the browser, set the application's API base URL Value for that environment so traffic reaches the mock during the Run.

{% hint style="info" %}
**Pro tip:** Keep mock base URLs in Account Values or Recipe overwrites so staging can point at a real API while a dev Recipe points at a mock.
{% endhint %}

## Related

* [Test data in DoesQA](/guides/test-data-in-doesqa.md)
* [Seed and clean up with API steps](/guides/seed-and-clean-up-with-api-steps.md)
* [Test APIs in a Flow](/guides/test-apis-in-a-flow.md)
* [Run across environments](/better-coverage/run-across-environments.md)