|
| 1 | +--- |
| 2 | +title: Dynamic Mocking |
| 3 | +content_type: reference |
| 4 | +layout: reference |
| 5 | + |
| 6 | +products: |
| 7 | + - insomnia |
| 8 | + |
| 9 | +tags: |
| 10 | +- mock-servers |
| 11 | + |
| 12 | +description: Use dynamic mocking in Insomnia mock servers to return request-aware responses and realistic mock data with self-hosted mocks. |
| 13 | + |
| 14 | +breadcrumbs: |
| 15 | + - /insomnia/ |
| 16 | + |
| 17 | +related_resources: |
| 18 | + - text: Mocks |
| 19 | + url: /insomnia/mock-servers/ |
| 20 | + - text: Self-hosted mocks |
| 21 | + url: /insomnia/self-hosted-mocks/ |
| 22 | + - text: Storage options |
| 23 | + url: /insomnia/storage/ |
| 24 | + - text: Requests |
| 25 | + url: /insomnia/requests/ |
| 26 | + - text: Template tags |
| 27 | + url: /insomnia/template-tags/ |
| 28 | +--- |
| 29 | + |
| 30 | +Dynamic mocking extends Insomnia’s existing mock server feature by evaluating templates at request time so responses can change based on the incoming request or defined template logic. You configure routes in Insomnia and serve them from Self-hosted mock servers. Headers and status codes remain configured per route, which ensures consistency while response data updates dynamically. |
| 31 | + |
| 32 | +Traditional mocks return static, predefined payloads, while dynamic mocks generate context-aware, variable outputs. |
| 33 | + |
| 34 | +For adding random values, Insomnia provides [**Faker template tags**](/insomnia/template-tags/) that you can insert anywhere that tags are supported. |
| 35 | + |
| 36 | +Use dynamic mocking to: |
| 37 | +- **Serve request-aware responses**: Configure a mock route that adapts to request headers and shape the response based on the incoming request. For example, echoing identifiers or switching fields. You manage this for each route. |
| 38 | +- **Insert random data with template tags**: Use Insomnia’s Faker template tags to generate values like names, emails, timestamps, and UUIDs. |
| 39 | + |
| 40 | +## Dynamic capabilities |
| 41 | + |
| 42 | +<!-- vale off --> |
| 43 | +{% table %} |
| 44 | +columns: |
| 45 | + - title: Use case |
| 46 | + key: option |
| 47 | + - title: Description |
| 48 | + key: description |
| 49 | +rows: |
| 50 | + - option: Use request data |
| 51 | + description: | |
| 52 | + Access details from the incoming request and reflect them in the mock response. For example, echo a query parameter or include a field from the request body. |
| 53 | + This makes the mock behave more like a live API. |
| 54 | + - option: Apply conditional logic |
| 55 | + description: | |
| 56 | + Use simple Liquid conditions to vary the response based on the request. |
| 57 | + Only a limited set of Liquid tags are supported for safety. |
| 58 | + - option: Generate fake data |
| 59 | + description: | |
| 60 | + Insert random but realistic data, such as names, emails, or timestamps. |
| 61 | + Use [**Faker template tags**](/insomnia/template-tags/) anywhere template tags are supported. |
| 62 | + - option: Combine request and fake data |
| 63 | + description: | |
| 64 | + Mix request data with generated values for realistic scenarios. For example, include the requester’s ID with random profile data. |
| 65 | +{% endtable %} |
| 66 | +<!-- vale on --> |
| 67 | + |
| 68 | +## Template reference examples |
| 69 | + |
| 70 | +Dynamic mocking in Insomnia supports a limited but powerful set of Liquid template tags and logic controls. These enable variable responses, conditional behavior, and safe data generation. |
| 71 | + |
| 72 | +Faker usage follows Insomnia’s template tag model. You can use Faker functions anywhere template tags are supported to generate realistic mock data like names, emails, or timestamps. |
| 73 | + |
| 74 | +For a complete list of available Faker properties, go to [**faker-functions.ts**](https://github.com/Kong/insomnia/blob/develop/packages/insomnia/src/templating/faker-functions.ts). |
| 75 | + |
| 76 | +### Liquid logic control |
| 77 | + |
| 78 | +Logic control in dynamic mocking is based on Liquid’s templating language; it only supports a subset of built-in tags for safety and simplicity. |
| 79 | + |
| 80 | +<!-- vale off --> |
| 81 | +{% table %} |
| 82 | +columns: |
| 83 | + - title: Tag |
| 84 | + key: tag |
| 85 | + - title: Description |
| 86 | + key: description |
| 87 | + - title: Reference |
| 88 | + key: ref |
| 89 | +rows: |
| 90 | + - tag: "`assign`" |
| 91 | + description: "Creates or updates a variable within the template scope." |
| 92 | + ref: "[LiquidJS Assign](https://liquidjs.com/zh-cn/tags/assign.html)" |
| 93 | + - tag: "`if`" |
| 94 | + description: "Conditionally renders a block of content when a statement evaluates as true." |
| 95 | + ref: "[LiquidJS If](https://liquidjs.com/zh-cn/tags/if.html)" |
| 96 | + - tag: "`unless`" |
| 97 | + description: "Renders a block when a statement evaluates as false; acts as the inverse of `if`." |
| 98 | + ref: "[LiquidJS Unless](https://liquidjs.com/zh-cn/tags/unless.html)" |
| 99 | + - tag: "`raw`" |
| 100 | + description: "Prevents Liquid from interpreting enclosed content. Use this to escape template syntax within mock responses." |
| 101 | + ref: "[LiquidJS Raw](https://liquidjs.com/zh-cn/tags/raw.html)" |
| 102 | +{% endtable %} |
| 103 | +<!-- vale on --> |
| 104 | + |
| 105 | +For additional implementation details and syntax behavior, go to the [**LiquidJS documentation**](https://liquidjs.com/zh-cn/). |
| 106 | + |
| 107 | +### Use data from requests |
| 108 | + |
| 109 | +You can access values from incoming requests and include them in your mock responses. |
| 110 | + |
| 111 | +**Format to output a variable:** |
| 112 | + |
| 113 | +```liquid |
| 114 | +{%- raw -%} |
| 115 | +{{ req.headers['Content-Type'] }} |
| 116 | +{{ req.body.name }}{% endraw %} |
| 117 | +``` |
| 118 | + |
| 119 | +**Format to define a default value:** |
| 120 | + |
| 121 | +```liquid |
| 122 | +{% raw %}{{ req.body.name | default: "George" }}{% endraw %} |
| 123 | +``` |
| 124 | + |
| 125 | +**Available variables** |
| 126 | + |
| 127 | +- `req.headers.*` — Reference a specific request header |
| 128 | +- `req.queryParams.*` — Reference query parameters in the URL |
| 129 | +- `req.pathSegments[*]` — Reference specific segments of the URL path |
| 130 | +- `req.body` — Returns the full request body (only when the body is not a binary stream) |
| 131 | +- `req.body.*` — When the content type is `application/json`, `application/x-www-form-urlencoded`, or `multipart/form-data`, Insomnia parses the body and exposes each field |
| 132 | + |
| 133 | +### Generate random data |
| 134 | + |
| 135 | +Use Faker template tags to generate random but realistic data in mock responses. |
| 136 | + |
| 137 | +**Format to output random data:** |
| 138 | + |
| 139 | +```liquid |
| 140 | +{% raw %}{{ faker.randomFullName }}{% endraw %} |
| 141 | +``` |
| 142 | + |
| 143 | +{:.info} |
| 144 | +> Self-hosted mocks run the published container image from the repository. |
| 145 | +
|
| 146 | +### Basic test options |
| 147 | + |
| 148 | +{% table %} |
| 149 | +columns: |
| 150 | + - title: Option |
| 151 | + key: option |
| 152 | + - title: Description |
| 153 | + key: description |
| 154 | + - title: When to use |
| 155 | + key: when |
| 156 | +rows: |
| 157 | + - option: "Send now" |
| 158 | + description: "Immediately send a request to the mock server and display the response in the Response pane." |
| 159 | + when: "Use this option for quick validation that your mock routes, dynamic templates, or environment variables resolve correctly. Ideal during early setup or after modifying a mock definition." |
| 160 | + - option: "Generate client code" |
| 161 | + description: "Produce a client-side code snippet that reproduces the current mock request in multiple languages. For example, `curl`, JavaScript `fetch`, or Python `requests`." |
| 162 | + when: "Use this when you want to share or automate the mock request outside Insomnia. For example, add it to test scripts, CI jobs, or SDK examples." |
| 163 | +{% endtable %} |
| 164 | + |
| 165 | +### Advanced test options |
| 166 | + |
| 167 | +{% table %} |
| 168 | +columns: |
| 169 | + - title: Option |
| 170 | + key: option |
| 171 | + - title: Description |
| 172 | + key: description |
| 173 | + - title: When to use |
| 174 | + key: when |
| 175 | +rows: |
| 176 | + - option: "Send after delay" |
| 177 | + description: "Schedules the request to execute after a specified delay in milliseconds. The request is queued and sent automatically once the delay expires." |
| 178 | + when: "Use this option to simulate **network latency**, **rate-limited APIs**, or **background task timing**. It helps validate client-side behavior when responses are delayed." |
| 179 | + - option: "Repeat on interval" |
| 180 | + description: "Sends the same request repeatedly on a fixed interval until stopped. Each cycle executes independently, allowing you to observe variable or time-sensitive responses from the dynamic mock." |
| 181 | + when: "Use this to test **dynamic responses**, such as mocks that use Faker data, timestamp generation, or conditional logic. It’s also useful for load, polling, or long-running integration tests." |
| 182 | +{% endtable %} |
0 commit comments