Map Local

Map Local answers matching requests from your Mac instead of the server. The response can be one you type into the rule, a file on disk, or a file picked from a folder by the request’s path. The server is never contacted. Use it to work on a screen before its API exists, to test how an app handles odd data, or to serve a local build of a web app’s scripts.

Mock a response from a captured request

1. Make the request once in your app so it appears in the traffic list.

2. Right-click it and choose Tools › Map Local….

   Cloak Proxy creates a rule that matches the request’s method and URL (without the query string), copies the captured response into it, turns Map Local on and opens the rule.

3. Edit the status code, headers or body under Respond with.

4. Make the request again. The app gets your response, and the traffic list shows a Map Local badge on it.

1234

A Map Local rule created from a captured response, ready to edit.

1. Where the response comes from: Inline, File or Directory.
2. Status code sent to the app.
3. Add, edit or remove response headers.
4. The body, with JSON validation, Format and Minify.

×

Start from a captured response

When you create a rule from a request that has a response, Cloak Proxy fills it in for you:

Field	Copied from the captured response
Matcher	The request’s method and URL without its query string, with subpaths off. It matches the same path with any query.
Status code	The response’s status.
Headers	Only headers that change how an app treats a response: Content-Type, Cache-Control, Set-Cookie, Location, Content-Disposition, WWW-Authenticate, Retry-After and every Access-Control-* header. Server and CDN headers are left out.
Body	The decompressed body. JSON is pretty-printed. Other text is copied as is.

If the body isn’t text, such as an image, Cloak Proxy saves it to a file in ~/Library/Application Support/CloakProxy/MapLocal/ and sets the rule to File with that path.

Choose where the response comes from

Pick a source under Respond with. Every source uses the Status code field (200 by default); the reason phrase next to it updates as you type.

Inline

The response is written in the rule.

Field	Notes
Status code	Any number.
Headers	A new rule starts with Content-Type: application/json; charset=utf-8. Click Add for more; click the minus button to remove one.
Body	Any text. JSON bodies show Valid JSON with Format and Minify, or Invalid JSON if a body starting with { or [ doesn’t parse.

File

The body is read from a file each time a request matches, so you can edit the file in your own editor and the next request picks up the change.

Field	Notes
Path	Type a path (a leading ~ works) or click Choose…. A green check means the file exists; an orange warning means it doesn’t.
Status code	Any number.
Headers	Your headers are sent as you set them. If you don’t set Content-Type, Cloak Proxy guesses it from the file extension.

If the file can’t be read when a request arrives, the app gets a 500 with the text Cloak Proxy Map Local: can't read … and the path.

Directory

The request’s path picks a file inside a folder. Use it to serve a whole static site or a folder of fixtures.

Field	Notes
Path	The folder. Type it or click Choose….
Status code	Sent with every file.

The part of the request path after the rule’s URL picks the file. With the rule https://cdn.example.com/static/* and the folder ~/site, a request for /static/js/app.js serves ~/site/js/app.js.

• A path that ends in / (or nothing at all after the rule’s URL) serves index.html from that folder.
• Content-Type is always guessed from the file’s extension.
• Paths containing .. are refused, so a request can’t read files outside the folder.
• If there’s no file for the path, the request goes to the real server (through Mock Sets and Map Remote, if they match). Later Map Local rules aren’t tried.

Content types guessed from extensions

For File (when you don’t set Content-Type) and Directory, Cloak Proxy uses the file extension:

Extension	Content-Type
.json	application/json; charset=utf-8
.html, .htm	text/html; charset=utf-8
.js, .mjs	application/javascript; charset=utf-8
.css	text/css; charset=utf-8
.xml	application/xml; charset=utf-8
.txt	text/plain; charset=utf-8
.png	image/png
.jpg, .jpeg	image/jpeg
.gif	image/gif
.webp	image/webp
.svg	image/svg+xml
.ico	image/x-icon
.woff2	font/woff2
.woff	font/woff
.mp4	video/mp4
.pdf	application/pdf
.wasm	application/wasm
Anything else	application/octet-stream

• Directorysite/

  • index.html served for /static/
  • Directoryjs/

    • app.js served for /static/js/app.js
  • Directorycss/

    • app.css served for /static/css/app.css

How Map Local responses are sent

• Cloak Proxy sets Content-Length from the body, so you never need to add it. Any Content-Length header in the rule is ignored.
• The body is sent exactly as written: it isn’t compressed. Don’t add a Content-Encoding header unless the file really is compressed.
• Map Local answers before Mock Sets and Map Remote, so a matching Map Local rule wins over both.
• The response still goes through No Caching, response scripts, the response breakpoint and the download delay of Network Conditions.
• Map Local matches the request after request scripts and the request breakpoint have run. If a script changes the URL, Map Local sees the new URL.

Tip

The inline body is plain text, so you can’t paste binary data into it. For images, fonts and other binary files, use File or Directory.

Caution

Map Local keeps answering after you’ve forgotten about it, including after a restart. If an app shows stale data, check the status bar for a Map Local chip and turn the rule off.

Related

Mock SetsReplay many recorded responses at once, offline.

Map RemoteSend requests to another server instead of answering locally.

ScriptingChange part of a real response instead of replacing it.

Mock a backendA step-by-step guide to mocking an API.