# Mock API Testing

{% hint style="info" %}
**Who is this for?** SDETs, QA engineers, and developers who want to isolate UI tests from backend variability by recording and replaying API responses.
{% endhint %}

Mock API testing lets ContextQA automatically capture every API response made during a test run and replay selected responses on subsequent runs. This eliminates flaky failures caused by slow or unreliable backend services and makes test execution faster by skipping live network calls for known endpoints.

The feature operates in two modes:

* **Recording (store)** — the test executes against the live backend. Every fetch and XHR call is intercepted, and its response is saved to the mock configuration for that test case.
* **Replaying (restore)** — on future runs, matching API calls receive the previously recorded response instead of hitting the live backend.

You control which APIs are mocked and which remain live on a per-test-case basis through the **Mock Config** drawer.

## Prerequisites

* Mock API testing is enabled at the organization level (see [Enable mock API testing](#enable-mock-api-testing-organization-level) below).
* You have at least one test case that has been executed at least once so that API responses have been captured.

***

## Enable mock API testing (organization level)

An organization administrator enables mock API testing for the entire workspace. Once enabled, ContextQA automatically captures API responses on the first execution of each new test case.

### Steps

1. Navigate to **Settings → Organization Setting**.
2. Select the **AI Configuration** tab (or scroll to the **Mock API Testing** section).
3. Enable the **Enable Mock API Testing** toggle.
4. Click **Save**.

A confirmation banner appears: *"Mock API Testing is enabled. Users can configure per-API mock settings on individual test cases."*

| Setting                     | Description                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Enable Mock API Testing** | When enabled, ContextQA automatically captures API responses on the first execution of each new test case and replays them in future runs. |

{% hint style="warning" %}
Disabling mock API testing at the organization level stops new API responses from being captured. Existing mock configurations on individual test cases are preserved but not replayed until the setting is re-enabled.
{% endhint %}

***

## View mock API results in a test run

After a test case executes with mock API testing enabled, the run results screen includes a **Mockup APIs** tab alongside the existing **Analysis**, **Configuration**, and **Recent Runs** tabs. This tab appears only when the run has mock API activity.

### What the Mockup APIs tab shows

**Run header** — displays the run status (Passed, Failed, Aborted, Queued, Stopped, or Not Executed), run number, execution date, and duration.

**Mode pill** — indicates the mock mode for this run:

| Pill label       | Meaning                                                                     |
| ---------------- | --------------------------------------------------------------------------- |
| **Recording**    | API responses were captured and saved during this run (store mode).         |
| **Replaying**    | Saved mock responses were replayed for matching API calls (restore mode).   |
| **Auto-capture** | Mock API capture is enabled and responses are being recorded automatically. |
| **Capture off**  | Mock API capture is disabled for this test case.                            |

**API capture summary card** — shows three metrics:

| Metric                  | Description                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Browser calls**       | Total number of browser-initiated network calls during the run.                                                                                        |
| **Total APIs captured** | Number of fetch/XHR calls recorded as mocks (in recording mode) or served from mocks (in replay mode). Click the count to jump to the **Network** tab. |
| **REST step calls**     | Number of API calls made from dedicated REST test steps.                                                                                               |

A footer note links to **Mock Config** where you can select which APIs to replay as mocks on future runs.

{% hint style="info" %}
If the test case failed, the Mockup APIs tab shows a placeholder message instead of the summary card: *"Mock API results are not available. This test case failed during execution, so mock API responses were not captured or stored."*
{% endhint %}

***

## Network log mock status

The **Network** tab in the run results now includes a **Mock Status** column for each network request. Each request displays one of three badges:

| Badge        | Color | Meaning                                                             |
| ------------ | ----- | ------------------------------------------------------------------- |
| **Recorded** | Blue  | This API response was captured and saved as a mock during this run. |
| **Mocked**   | Green | This API response was served from a previously stored mock.         |
| **Live**     | Grey  | This API call hit the live backend and was not mocked.              |

Use the mock status column to verify which endpoints are being mocked and which are still hitting the live server.

***

## Configure mocks per test case

The **Mock Config** drawer lets you choose exactly which captured APIs should be replayed as mocks on future runs. You access it from the test case detail side panel.

### Open the Mock Config drawer

1. Open a test case from **Test Development → Test Cases**.
2. In the test case detail side panel, locate the **API Mocking** card.
3. Click **Configure** (or the equivalent button on the card) to open the Mock Config drawer.

### Mock Config drawer layout

The drawer displays:

* **Header** — title, mocked count (e.g., "12 / 45 mocked"), and a close button.
* **Stats row** — four summary cards:
  * **Captured from** — the run number and date the mocks were captured.
  * **Total APIs** — total number of captured API endpoints.
  * **Mocked** — number of APIs currently set to mock.
  * **Coverage** — a progress bar showing the percentage of APIs mocked.

### Filter and search

Use the toolbar to filter the API list:

| Filter          | Options                               |
| --------------- | ------------------------------------- |
| **Mock status** | **All**, **Mocked**, **Live**         |
| **HTTP method** | **GET**, **POST**, **PUT**            |
| **Search**      | Search by URL, method, or status code |

### Toggle mocking for individual APIs

Each row in the table shows the HTTP method, URL, status code, call count, and a **Use Mock** toggle. Enable the toggle to mock that API on future runs; disable it to let the call hit the live backend.

### Bulk actions

* **Mock all** — enables mocking for every captured API.
* **Clear all** — disables mocking for every captured API.

### Save your configuration

1. Review the selected mock/live assignments.
2. Click **Save Configuration** to persist your choices.
3. Click **Cancel** to discard changes and close the drawer.

The mocked API count on the test case side panel updates to reflect the saved configuration.

***

## Toggle capture vs. replay mode

Each test case has a **Renew API responses** toggle on the API Mocking card in the side panel. This toggle controls the mock mode for the next run:

| Toggle state     | Next run behavior                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------ |
| **On** (restore) | Matching API calls receive previously recorded responses. New or unmatched calls hit the live backend. |
| **Off** (store)  | All API responses are captured fresh, overwriting previously stored mocks.                             |

The toggle saves automatically when changed outside of edit mode. If you are editing the test case details, the toggle change is saved when you click **Save Changes**.

***

## How it works end-to-end

1. **Enable** mock API testing in **Settings → Organization Setting**.
2. **Run** a test case for the first time. ContextQA records all API responses (store mode).
3. **Review** the captured APIs in the **Mockup APIs** tab of the run results.
4. **Configure** which APIs to mock by opening the **Mock Config** drawer from the test case side panel.
5. **Toggle** the test case to restore mode (Renew API responses on).
6. **Re-run** the test case. Mocked APIs return recorded responses; other calls hit the live backend.
7. **Verify** in the Network tab that the expected requests show a **Mocked** badge.

***

## Tips and best practices

* **Start with full capture, then prune.** Let the first run capture all APIs, then disable mocking for endpoints that return dynamic data (timestamps, random IDs) that your assertions do not validate.
* **Re-record after backend changes.** When the backend API contract changes, turn off the Renew API responses toggle and run the test case once to capture fresh responses, then re-enable replay.
* **Use the Network tab to troubleshoot.** If a test fails unexpectedly in replay mode, check the Mock Status column. A **Live** badge on an endpoint you expected to be mocked may indicate the request signature changed (different URL parameters, headers, or body).
* **Combine with API chaining.** Mock API testing works alongside API chaining. Responses captured from chained API steps are also eligible for mocking.

## Troubleshooting

**The Mockup APIs tab does not appear in the run results** Mock API testing may not be enabled at the organization level, or the test run did not make any fetch/XHR calls. Verify the organization setting is enabled and that the test case includes steps that trigger API calls.

**Mocked responses are outdated and causing test failures** Turn off the **Renew API responses** toggle on the test case, run the test once to capture fresh responses, then re-enable the toggle. Open the Mock Config drawer to verify the updated status codes and response data.

**The Mock Config drawer shows "No mock configurations found"** Adjust the active filters or search term. If no filters are active, the test case may not have been run with mock API testing enabled. Run the test case at least once with the organization-level setting enabled.

**Coverage percentage is lower than expected** Some API calls may not be eligible for mocking (for example, WebSocket connections or non-HTTP requests). The coverage metric reflects only fetch and XHR calls.

## Related pages

* [API Testing Overview](/api-testing/api-testing.md)
* [Creating API Tests](/api-testing/creating-api-tests.md)
* [API Chaining](/api-testing/api-chaining.md)
* [Running Tests](/execution/running-tests.md)
* [Debugging Tests](/execution/debugging-tests.md)

{% hint style="info" %}
**Eliminate flaky tests caused by unreliable backends.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See how ContextQA's mock API testing stabilizes your test suite.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learning.contextqa.com/api-testing/mock-api-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.