Mock a backend

The backend isn’t ready, or you need to see how the app handles an error, an empty list, or a slow 500. This guide answers a captured request with a response you control using Map Local, then shows two ways to mock a whole API: Mock Sets (record real traffic, replay it offline) and an API-client mock server (serve saved examples from a collection).

What you need

Cloak Proxy capturing the app, with HTTPS decrypted	See Debug a mobile app or SSL Proxying
At least one captured request to the endpoint you want to mock	Map Local and Mock Sets are built from real traffic

Mock one endpoint with Map Local

Map Local answers matching requests with a response you write. The real server is never contacted.

1. Capture the request once so you have a real response to start from. Right-click it and choose Tools → Map Local….

   Cloak Proxy copies the captured status, the important headers (Content-Type, caching, cookies, CORS), and the body into a new rule, and turns the tool on.

   12345

   A Map Local rule prefilled from a captured response.

   1. Tool on/off
   2. Matcher: method and URL
   3. Inline, File or Directory
   4. Status code
   5. Valid JSON check, Format and Minify

   ×

   

2. Choose where the response comes from:

   Source	What it does
   Inline	A status, headers and body you type here
   File	A file on disk. Content-Type is guessed from the extension if you don’t set one
   Directory	A folder of files picked by request path. Missing files fall through to the real server

3. Edit the response. For Inline, set the Status code, adjust the Headers, and edit the Body (JSON gets a Valid JSON check, Format and Minify).

4. Repeat the request from the app, or right-click and choose Repeat. The response now comes from your rule, tagged Map Local in the traffic list.

Tip

The rule’s matcher created from a request is exact (that method and path, query ignored). Loosen it with * to cover more, for example https://api.example.com/v1/users/*. See Rules and matching.

Cover error and empty states

Map Local is the quickest way to see how the app handles responses it rarely gets. Duplicate the rule (right-click → Duplicate) and change the copy:

To simulate	Set
A server error	Status code 500, body {"error":"Simulated failure"}
Rate limiting	Status code 429, header Retry-After: 30
An empty list	Status 200, body [] or {"items":[]}
Not found	Status code 404
Unauthorized	Status code 401

Enable one rule at a time with its checkbox to flip between states. Rules run top to bottom; the first match wins.

Note

To change only part of a response (one field, a flag) while keeping the rest from the real server, use Scripting’s onResponse instead of Map Local.

Replay a whole API offline with Mock Sets

A Mock Set is a snapshot of an API’s responses. While it’s on, matching requests are answered from the snapshot with no network, so you can demo, test or debug the app exactly as it behaved when recorded.

1. Capture the flows you want to replay by using the app normally.

2. Make a set. Select the requests and choose Tools → Mock Sets → From Selected Requests, or right-click a domain in the sidebar and choose Mock host Offline to snapshot every captured response from that host.

   1234

   A Mock Set. Each recorded response is editable.

   1. Tool on/off
   2. Offline: answer unrecorded requests with 404
   3. Ignore query strings when matching
   4. Recorded responses; select one to edit it

   ×

   

3. Set how it matches:

   Option	Effect
   Offline: answer unrecorded requests to these hosts with 404	Nothing reaches the real host, so you test exactly what was recorded. Off: unrecorded requests go to the server
   Ignore query strings when matching	/users?page=2 is answered with a recording of /users?page=1

4. Select any response in the table to edit its status, headers or body, the same as Map Local. The most recent recording of a request wins when it was captured more than once.

5. Turn the set on with the switch. Disconnect from the network and the app keeps working from the snapshot.

Tip

You can also build a set from a recording: Tools → Mock Sets → Import HAR or Session… turns a .har, .cloaksession or Charles .chlsj file into a set. The CI recorder’s cloakctl run --record run.har then --mock run.har does the same thing headlessly — see Demo offline with mock sets.

The API-client alternative: a mock server

When your mocks live as saved examples in an API-client collection rather than captured traffic, run a mock server. It serves the collection’s examples on localhost, so you can point a dev build at it.

1. In the API Client (<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>O</kbd>), save some responses as examples (Save as Example on a response), or import an OpenAPI spec that has examples.

2. Open Mocks, pick the collection, and click Start Mock Server.

   1234

   A mock server serving a collection's examples on localhost, with routes and a call log.

   1. Mocks section
   2. Port, delay, CORS, and the localhost URL
   3. Routes from the saved examples
   4. Live calls

   ×

   

3. Point your app at the printed http://localhost:PORT. Routes match by method and path (:params match anything). Send x-mock-response-name or x-mock-response-code to pick a specific example.

Note

The mock server runs while the app is open. For CI or a shared host, run it from the command line with cloakctl mock <Collection> --port 4010 — no app needed. See Mock servers.

Clean up

1. Turn off Map Local, Mock Sets (and Scripting if used) in the Tools window so real traffic flows again.

2. In the API Client’s Mocks view, click Stop on any running mock server.

3. If you pointed a dev build at localhost:PORT, point it back at the real backend.

Related

Map LocalInline, file and directory responses for matching requests.

Mock SetsRecord and replay responses offline, with strict mode and query matching.

Mock serversServe a collection's examples on localhost.

ScriptingChange part of a response with onResponse.