Mocks section

The Mocks section is where you define the simulated responses Aseptic serves when a dependency is resolved as mock. It lets you work without a cloud connection and without launching the core your micro calls.

You don’t need to start anything to edit mocks: the catalog lives on disk (.aseptic/mocks/<service>.json) and is served with hot reload, so a change is applied instantly even if the scenario is running.

The tree: services → endpoints

The side shows a tree of services (the mockable cores) and, within each one, its endpoints in a flat list, sorted alphabetically by path. Each row shows the full path relative to the service base, so two endpoints with the same ending (/orders/lines and /invoices/lines) are never confused. To narrow a large catalog, the side search filters by service name or by path.

A service is mockable if it is a dependency of some micro (or if you create its file in .aseptic/mocks). You can show or hide the services that don’t have stubs yet.

Create a stub

Press New stub (or the “⋮” menu) and choose the target service —one from the catalog or a new one that is created on save—. An endpoint is defined with:

Method and path (relative to the service’s base path).
One or more response variants.

There are two ways to fill the body:

From OpenAPI: if the service declares an OpenAPI specification (in the micro’s manifest, or derived from its cloud URL), select the operation and Aseptic generates a template of the body.
Manual: if there is no OpenAPI, you write the JSON body by hand.

The OpenAPI icon next to the service opens the specification in a viewer of its own, with its operations browsable, instead of dropping the raw file in front of you.

Groups and services

Every service in the tree has its own panel (“Edit service” in its menu, or the gear in a stub’s editor). In a group you created yourself —to gather stubs that belong to no dependency, such as every /notice/...— you edit the name, the prefix, the base URL (the real address the prefix stands for, which is where a real call goes) and the OpenAPI. For a dependency you edit everything but the name, which is its id in the manifests: the prefix and the base URL are saved in the manifest of every micro that declares it, and stubs under the previous prefix move to the new one.

When you pick an OpenAPI operation, Aseptic works out the path the client calls even if the specification declares another prefix (its servers, the context path, a segment shared with the service prefix). If that operation already has a stub, no second one is created: the existing one opens with a new variant from the OpenAPI.

When you create a new stub, besides starting from an OpenAPI operation you can start from a call that already reached the mock without a stub: it takes its method and path.

The mock server port and the OpenAPI token (sent as Authorization: Bearer when downloading protected specs) live in Mock settings, in the section’s “⋮” menu.

Variants: the unit of work

An endpoint can have several variants (for example a 200 and a 500). Each variant has its label, status code, body, headers and an optional latency in milliseconds to simulate slowness.

The selected variant expands inline with its body, headers and settings together. The variant that is served is marked separately with a toggle (it’s independent of the one you’re editing): it’s the response Aseptic will return to whoever calls that endpoint.

Above the body there are three buttons: Format indents it (and saves that indentation), Fill template generates it from the OpenAPI, and View formatted opens it in a large viewer, which edits nothing and is there to read a response that does not fit in the box.

You can duplicate a variant to start from a similar one. An endpoint you no longer want served is deleted from its menu.

Any kind of body: images, PDFs, files

Above each variant’s body you choose Text, No body, File or Stream:

Text: with a format picker —JSON, plain text, HTML, XML, JavaScript, CSS, CSV, YAML, Markdown or form— that sets the Content-Type being served and gives each one its highlighting and its Format (a form is compacted to a=1&b=2). A type typed by hand in the variant’s settings falls into its family (application/problem+json is JSON).
File: an image, a PDF, a zip, an audio clip… anything. Click Choose file or drop it on top, and it is served byte for byte. If it’s a small image you’ll see a thumbnail.
No body: just the status and headers, for a 204 or a 304; no Content-Type is made up.
Stream: the response arrives in chunks, each after its pause, to test a client that renders or counts while it arrives. You choose how each chunk is written: SSE events (text/event-stream, with an optional event name and id), NDJSON (one JSON per line) or Chunked text.

Size decides where it’s stored: up to 256 KB it lives inside the catalog, so it travels with it; anything bigger is copied to .aseptic/mocks/files/<service>/ and the variant references it. Without a Content-Type, it is inferred from the extension (.png → image/png, .pdf → application/pdf); any other header —Content-Disposition to force a download, Cache-Control…— goes under Headers as usual. When you export a service or a scenario, the files are embedded, so what you share doesn’t depend on that folder.

Rules: answering according to the request

Above the variants there is a Rules block. Each rule says «when these conditions hold, serve this variant», and they are evaluated in order: the first one that matches wins. If none matches, the active variant is served — so an endpoint without rules behaves exactly as before. The last, fixed row of the block says precisely that.

A condition looks at one piece of the request, with no syntax to learn: query or header by name, or body by a dotted path (order.customer.tier; a number enters a list, order.lines.0.sku). It compares with equals, differs from, exists or does not exist. All conditions of one rule must hold together; for an «or», add a second rule — that is what the ordered list is for. The order is changed with each rule’s arrows: moving a rule is changing its priority.

A rule points at a variant by its label, not its position, so reordering variants cannot silently change what gets served. That is why, in an endpoint with rules, two variants cannot share a label. If you rename a variant a rule pointed at, the rule is flagged and stops being served until you fix it.

Test simulates a request right there — query, headers and body — and says which variant would come out and which rule chose it. The scenario does not need to be running. And when it is, the Mock calls dock marks each call with the rule that decided it, so two identical calls with different answers explain themselves.

From the terminal it is the same: aseptic mock probe POST "/v1/orders?tier=premium", with -H 'X-Vip: 1' for headers and -d '{...}' for the body.

Automatic saving

The mock editor saves on its own, with a small delay, while you type; you’ll see a “Saved” indicator. Safeguards:

Only valid states are persisted: a half-written JSON body does not break the served mock —the last valid one is kept on disk and the error is marked inline—.
A new stub is not persisted until it has a usable method and path.
Deletion is always explicit, with confirmation.

Mock Studio: from a real call to a stub

When a scenario runs and a micro calls a mock that doesn’t have a response yet, that call appears in the Mock calls dock. From there you can create a stub with one click from the observed call: you go straight to the endpoint you want to complete, without searching for it. You can also test what the mock would respond without launching anything.

Real call: capture the service’s response

Sometimes you don’t want to invent the body: you want the one the real service returns. Every endpoint has a Real call toggle. While it is on, that endpoint stops serving its variant: the request goes out to the real service, its response is returned verbatim to the caller and recorded as a «Real» variant with its status code, which becomes active. Turn it off and the mock replays what the service last said, without going out again.

Where it calls: the scenario’s microservice if it is running, otherwise the dependency’s cloud URL. The toggle’s «i» icon states the exact target; if the service has none, the toggle stays off and explains why.
Verbs that change data: turning it on for a POST, PUT or DELETE asks for confirmation and names the target. It isn’t forbidden —capturing the response of a creation is a legitimate case— but it really runs there.
One variant per status code: Real 200, Real 404… Capturing a thousand calls doesn’t create a thousand variants; it refreshes the one for the code that arrives.
Anything that isn’t text (an image, a PDF) is recorded as the variant’s file; anything larger than 1 MB is served but not recorded.

Endpoints in capture mode are marked with a real badge in the tree, so you don’t leave one going out to the network without noticing.

Import and export

With the panel’s import/export icons:

Export a service’s endpoints (or several) to a JSON file.
Import your own JSON or a Postman collection (its folders map to services).

Useful to share a mock catalog or reuse it across scenarios.

The same from the CLI

All of this also exists in the CLI: aseptic mock services, mock catalog, mock save, mock set-active, mock skeleton, mock from-call, mock probe, mock capture, mock put-file, mock import / export. See the CLI reference.