Decoy

What is Decoy?

Decoy is a native macOS mock server for developers who need to simulate HTTP endpoints and webhook behavior locally. It lets you define routes, inspect incoming requests, and return controlled mock responses so you can test API wrappers, request handling, redirects, and failure modes without standing up external services.

The core purpose of Decoy is local, on-demand testing: you point your client to Decoy’s local domain and port, watch each request as it arrives, and adjust endpoint responses so your code can be exercised against the scenarios you choose.

Key Features

• Native macOS app with instant startup: Runs as a SwiftUI application and starts quickly without requiring Docker, cloud tunnels, or setup steps.
• Endpoint and request/response controls: Define method + path pairs, grouped into projects, then choose response status codes, body type, headers, and optional delay.
• Live request inspection: Every incoming request is displayed with headers, body, source IP, timestamps, and request identifiers (UUID). JSON bodies are auto-formatted.
• Parameterized paths and projects: Support path parameters (e.g., /users/:id matches /users/42) and organize endpoints into projects.
• Response formats for common web scenarios: Choose among plain text, JSON, HTML, XML, file, empty, or redirect; configure Location headers automatically for redirects.
• Browser and CORS support: Browser-based requests “just work,” with CORS headers added automatically. Redirect status codes (301, 302, 307, 308) are supported.
• Request/response snapshots and exports: View what was actually sent back for each request and export requests as cURL, JavaScript fetch, or Ruby.
• Durable request logging via SQLite: Requests are written to SQLite immediately so data isn’t lost if the app quits unexpectedly.

How to Use Decoy

1. Install Decoy from the Mac App Store, then launch the app on macOS 14 Sonoma or later.
2. Create or select a project, then define endpoints using a method and a path pair.
3. Configure each endpoint’s mocked response: set a status code, choose a body type (including JSON, HTML, XML, or file), add headers, and optionally set a delay.
4. Point your app or test tool to the Decoy local domain and port (decoy.my:8998 is referenced in the product description).
5. Send requests from your client or browser. Decoy will display each incoming request details and apply response changes on the next request.

Use Cases

• Testing webhook handling and edge cases: Send webhook requests to Decoy to confirm how your code processes different status codes, response bodies, headers, and simulated latency.
• Verifying API wrapper logic: Exercise an API client against mock endpoints you control, adjusting response payloads and headers while observing each incoming request.
• Reproducing redirect behavior: Configure endpoints to return redirects (with the appropriate Location header) to test how your application follows or reacts to 301/302/307/308.
• Serving static-like content during development: Use file responses to serve images, PDFs, or other files directly, or serve complete HTML pages by setting the body type to HTML.
• Capturing and reusing real request/response interactions: Use request snapshots and export generated cURL or fetch/Ruby equivalents to reproduce issues or share examples.

FAQ

Does Decoy require Docker, cloud tunnels, or configuration files? No. The product description states it runs without Docker, cloud tunnels, or config files.

What platforms and versions are supported? Decoy requires macOS 14 Sonoma or later.

How are changes to mocked responses applied? Edits (such as updating JSON, headers, or status codes) take effect on the next incoming request.

Can Decoy handle browser requests and CORS? Yes. Browser-based requests are supported, and CORS headers are added automatically.

Where is request data stored? Requests are written to SQLite immediately, and the product description notes that nothing is lost if the app quits unexpectedly.

Alternatives

• Local HTTP mock servers (generic tools): Tools in this category also provide local endpoints and controllable responses, typically using configuration files or containers; Decoy’s emphasis is a native macOS UI without Docker.
• Dedicated API mocking platforms (hosted services): These can simulate endpoints over the network, but they usually require external setup and deployment rather than running a local mock server.
• Request/response stubbing libraries or test frameworks: Some teams use code-based stubs within their test suite; this differs from Decoy’s standalone local server with a UI for inspecting requests and editing responses.
• API testing tools with mocking support: Some interactive API clients support mocking or local simulations; workflows may differ, especially around dedicated request inspection, projects, and response snapshot/export features.