# vlatte

> Mock HTTP and gRPC APIs in Go tests, or serve mocks from files for apps in any language.

vlatte is an API mocking framework at `github.com/caffeine-projects/vlatte`. There are two ways to use it:

- In Go tests, `mockhttp` and `mockgrpc` start real HTTP and gRPC servers. A test adds mocks to a server and sends it requests through the code under test. The library requires Go 1.27 or later.
- The `vlatte` CLI, a binary or a Docker image, serves HTTP and gRPC mocks from YAML or JSON mock files for applications in any language, records a real service and plays it back, and takes new mocks over an admin API. Running the release binary or image needs no Go installation.

The installation commands and Docker examples use `v1.0.0`. Pin that version of the Go library, CLI or Docker image to match the examples. See [Installation](https://vlatte.dev/getting-started/installation.md).

A mock is matchers, which say which requests it answers, and a reply, which says how it answers. The matchers, from the `match` package, are the same for both protocols. Everything a mock file says, Go can say too. A request no mock matches gets HTTP `418` with a `VLatte-Error` header, or gRPC `NotFound`, and a list of the mocks that came closest.

## Getting started

- [Introduction](https://vlatte.dev/getting-started/index.md): VLatte mocks HTTP and gRPC APIs for tests and local development.
- [Installation](https://vlatte.dev/getting-started/installation.md): Use the library inside Go tests, or install the standalone CLI for apps in any language.
- [Quick start](https://vlatte.dev/getting-started/quick-start.md): Choose HTTP or gRPC to embed VLatte in a Go test.
- [Concepts](https://vlatte.dev/getting-started/concepts.md): Understand how servers, mocks and files fit together, where their working data lives, and what happens when no mock matches.
- [Settings](https://vlatte.dev/getting-started/settings.md): A server's settings, such as its address, its mock files or its log level, come from four places, each overriding the ones before it.

## Run

- [Overview](https://vlatte.dev/run/index.md): vlatte runs outside Go tests too: the `vlatte` command serves mock files, for apps in any language.
- [CLI](https://vlatte.dev/run/cli.md): `vlatte` serves the mock files under `testdata/vlatte/_mocks` in the working directory.
- [Configuration](https://vlatte.dev/run/configuration.md): A server's settings come from these sources, each overriding the ones before it.
- [Docker](https://vlatte.dev/run/docker.md): `ghcr.io/caffeine-projects/vlatte` is an image of the CLI for `linux/amd64` and `linux/arm64`, run by a non-root user (`65532`).

## Guides

- [Overview](https://vlatte.dev/guides/index.md): Each guide works through one task from start to end, with code you can run.
- [Testing a frontend client](https://vlatte.dev/guides/testing-a-frontend-client.md): Run VLatte as a local API for a web or mobile app, without installing Go.
- [Testing a REST client](https://vlatte.dev/guides/testing-a-rest-client.md): This guide tests a small Go client of a users API against a mock server: the happy path, an error answer, and what the client sent.
- [Mock files and the CLI](https://vlatte.dev/guides/mock-files-and-the-cli.md): This guide writes mock files with editor support, serves them with the `vlatte` command, changes them while it runs, and loads the same files in Go tests.
- [Record and replay](https://vlatte.dev/guides/record-and-replay.md): This guide records a real API once, commits what it answered as mock files, and replays them in every later test run, without the API.
- [Chaos testing](https://vlatte.dev/guides/chaos-testing.md): This guide checks that a client retries a failing server, survives a reset connection, and gives up on a slow one.
- [Stateful flows](https://vlatte.dev/guides/stateful-flows.md): This guide mocks a cart and checkout flow, where an answer depends on what came before, and runs its tests in parallel against one server.
- [Testing a gRPC streaming client](https://vlatte.dev/guides/grpc-streaming-client.md): This guide tests a client of a server stream: it reads every event, handles a stream that ends with an error status, and one whose server dies midway.
- [Docker Compose](https://vlatte.dev/guides/docker-compose.md): This guide runs vlatte next to an app under test with Docker Compose: the app calls a mocked payments API, a test changes the mocks over the admin API, and the admin API asks for a token.
- [Testing webhooks](https://vlatte.dev/guides/webhooks.md): This guide mocks a payment API that calls your service back once a payment is made, and checks that the callback came.
- [HTTPS and mTLS mocks](https://vlatte.dev/guides/https-mtls.md): This guide tests a client of an API that serves HTTPS only, first with a certificate the client trusts, then with mutual TLS, where the client must present a certificate of its own.
- [Testing an LLM streaming client](https://vlatte.dev/guides/llm-streaming.md): This guide tests a Go client of a chat API that streams its answers: it puts the answer together as the chunks arrive, fails when the stream drops midway, and fails on a rate limit.
- [Mocking a remote MCP server](https://vlatte.dev/guides/mcp-server.md): This guide mocks a remote MCP server, a weather server over Streamable HTTP, with mock files, and tests an MCP client against it: the client connects, calls a tool, gets its progress and its result.

## HTTP

- [Overview](https://vlatte.dev/http/index.md): `mockhttp` runs HTTP mock servers for tests, and is the server the `vlatte` command runs.
- [Mocks](https://vlatte.dev/http/mocks.md): A mock is built with a `*mockhttp.Builder` and added to a server with `m.Mock` or `m.MustMock`, which return a scope of the mocks they added.
- [Request matching](https://vlatte.dev/http/matching.md): A mock matches a request when every matcher it has matches.
- [Replies](https://vlatte.dev/http/replies.md): A mock's reply says how it answers.
- [Forms and multipart](https://vlatte.dev/http/forms-multipart.md): Go's `net/http` parses request bodies: `ParseForm` reads urlencoded forms and `ParseMultipartForm` reads `multipart/form-data`.
- [Proxying](https://vlatte.dev/http/proxying.md): vlatte sends requests on to real servers in three ways.
- [Pipes](https://vlatte.dev/http/pipes.md): Pipes are HTTP only, and Go only: in mock files, `pipes`, `wire_pipes` and `upstream_pipes` list faults.
- [Faults](https://vlatte.dev/http/faults.md): The `fault` package has pipes that make an HTTP mock answer wrong, to test how a client handles a server that fails, or a bad network.
- [Mock files](https://vlatte.dev/http/mock-files.md): Mocks can also live in YAML or JSON files (`.json`, `.yaml` or `.yml`).
- [TLS](https://vlatte.dev/http/tls.md): `m.MustStartTLS()` serves HTTPS, with no certificate to make: `m.URL()` starts with `https://`.
- [CORS](https://vlatte.dev/http/cors.md): Enable CORS when a browser app calls the mock API from another origin.
- [Troubleshooting](https://vlatte.dev/http/troubleshooting.md): Diagnose unmatched requests and serving failures through near misses, debug headers, logs and the request journal.

## gRPC

- [Overview](https://vlatte.dev/grpc/index.md): `mockgrpc` runs gRPC mock servers for tests, and for the `vlatte` command.
- [Methods](https://vlatte.dev/grpc/methods.md): `Method` takes a method by whole segments of its full method: `SayHello`, `Greeter/SayHello`, `greeter.Greeter/SayHello`, or the full method, such as `pb.Greeter_SayHello_FullMethodName`.
- [Request matching](https://vlatte.dev/grpc/matching.md): They read the call's metadata and its request, as protojson writes it, with the field names of the `.proto` file: enums by name, `int64` values as text, timestamps in RFC 3339.
- [Replies](https://vlatte.dev/grpc/replies.md): Build gRPC messages and status replies, sequence or randomize answers, and generate responses from the incoming call.
- [Streaming](https://vlatte.dev/grpc/streaming.md): A mock answers its method whatever its call type.
- [Cuts](https://vlatte.dev/grpc/cuts.md): A reply that returns an error matching `vlatte.ErrAbort` or `vlatte.ErrReset`, such as a `Func` reply, cuts the call, to test a client against a server that dies midway.
- [Descriptors and reflection](https://vlatte.dev/grpc/descriptors.md): A server without the generated code of a service serves it from its descriptors, with messages of dynamic types: `Setup().Descriptors("api.binpb")` loads descriptor sets, as `protoc --descriptor_set_out=api.binpb --include_imports` or `buf build -o api.binpb` write them, and `Setup().Files(files)` takes a `*protoregistry.Files`.
- [Proxying](https://vlatte.dev/grpc/proxying.md): Forward gRPC calls to an upstream service, including streaming calls, with configured targets and metadata.
- [Mock files](https://vlatte.dev/grpc/mock-files.md): `Setup().MockFiles("testdata/grpc/*.yaml")` loads gRPC mock files at `Start`, and `m.Reload()` again; `mockgrpc.FromFile` and `FromBytes` build one.
- [TLS](https://vlatte.dev/grpc/tls.md): `m.MustStartTLS()` serves gRPC over TLS, with a self-signed certificate for `localhost`, `127.0.0.1` and `::1`, and `m.Dial()` already trusts it.
- [Troubleshooting](https://vlatte.dev/grpc/troubleshooting.md): Use status codes, diagnostic metadata and the request journal to find why a call did not get its expected reply.

## Features

- [Overview](https://vlatte.dev/more/index.md): Use these features to describe realistic API behavior, reuse mocks across tests and tools, and check what an application sent.
- **SSE (Server-sent Events)**
  - [Overview](https://vlatte.dev/sse/index.md): An HTTP mock replies with server-sent events: a `text/event-stream` body, sent event by event, each flushed to the client as it goes.
  - [Events](https://vlatte.dev/sse/events.md): `NewEventStream(events...)` in Go, and `event_stream.events` in a mock file, list the events of a stream, sent in order.
  - [Timing and lifetime](https://vlatte.dev/sse/timing.md): A stream sends its events at once, unless they have delays, and ends after the last one, unless it keeps open.
  - [Reconnecting](https://vlatte.dev/sse/reconnecting.md): A client such as `EventSource` reconnects when a stream ends or its connection drops: it waits the `retry` time the stream set, and sends the id of the last event it got as the `Last-Event-ID` header.
  - [Testing a client's parser](https://vlatte.dev/sse/raw-events.md): Servers in the wild send streams the fields of an event can't write: CRLF or CR line endings, a byte order mark, fields without a space after the colon.
  - [With other features](https://vlatte.dev/sse/other-features.md): An event stream is a reply body, so the features of HTTP mocks work with it.
  - [Testing an LLM streaming client](https://vlatte.dev/guides/llm-streaming.md): This guide tests a Go client of a chat API that streams its answers: it puts the answer together as the chunks arrive, fails when the stream drops midway, and fails on a rate limit.
  - [Mocking a remote MCP server](https://vlatte.dev/guides/mcp-server.md): This guide mocks a remote MCP server, a weather server over Streamable HTTP, with mock files, and tests an MCP client against it: the client connects, calls a tool, gets its progress and its result.
- **Matchers**
  - [Overview](https://vlatte.dev/matchers/index.md): The `match` package holds the matchers every protocol shares.
  - [Equality and text](https://vlatte.dev/matchers/equality-text.md): Compare values, match text, check for missing values, and match URL paths or query strings.
  - [Numbers, dates and times](https://vlatte.dev/matchers/numbers-dates.md): Compare numeric values and timestamps, including request text that represents them.
  - [Lists and objects](https://vlatte.dev/matchers/lists-objects.md): Match collection sizes, items, keys and nested fields.
  - [JSON and XML](https://vlatte.dev/matchers/json-xml.md): These matchers read JSON and XML from request bodies, gRPC messages or other values, and inspect JWT headers and claims.
  - [Combining](https://vlatte.dev/matchers/combining.md): Combine matchers with AND, OR, NOT or XOR.
  - [Custom matchers](https://vlatte.dev/matchers/custom.md): Create matchers from Go functions, or register named matchers to use in mock files, admin API requests and journal queries.
  - [All matchers](https://vlatte.dev/matchers/reference.md): The matchers of the `match` package, by their Go name and their name in mock files, which ignores case.
- [Templating](https://vlatte.dev/templating/index.md): Replies can render parts of the response from the request: header values, the body, and the name or content of a body file.
- **Scenarios**
  - [Overview](https://vlatte.dev/scenarios/index.md): A scenario serves mocks in turn: each mock of a scenario matches while the scenario is in the state it requires, and moves the scenario to its new state when it is picked to answer.
  - [Stateful flows](https://vlatte.dev/guides/stateful-flows.md): This guide mocks a cart and checkout flow, where an answer depends on what came before, and runs its tests in parallel against one server.
- **Recording**
  - [Overview](https://vlatte.dev/recording/index.md): Record a real service once, then test without it.
  - [HTTP](https://vlatte.dev/recording/http.md): An HTTP server records what it proxies, or what it sends to a target, as mock files, then answers the same requests the same way, without the service.
  - [gRPC](https://vlatte.dev/recording/grpc.md): Record gRPC calls, including streams, as mock files and replay them without the original upstream.
  - [CLI](https://vlatte.dev/recording/cli.md): The `vlatte` command records a service until it stops, and serves the recordings on the next run.
  - [Settings](https://vlatte.dev/recording/settings.md): The `record` section of the configuration records from server start to close.
  - [Admin API](https://vlatte.dev/recording/admin-api.md): The admin API starts and stops recordings while the server runs.
  - [Files and secrets](https://vlatte.dev/recording/files-secrets.md): Find where recordings are written and how to keep credentials and sensitive payloads out of saved fixtures.
- **Verifying requests**
  - [Overview](https://vlatte.dev/verify/index.md): A test checks what the code under test sent: which requests came, how many, by when, and in what order.
  - [Selecting requests](https://vlatte.dev/verify/selecting.md): `m.VerifyRequests()` selects every request the journal holds, whatever its outcome.
  - [Counts and reports](https://vlatte.dev/verify/counting.md): An assertion counts the requests a selection holds, now or over a wait, and reports a failure with `t.Errorf`, as `testing.T` does, so the test goes on.
  - [Waiting](https://vlatte.dev/verify/waiting.md): A request is journaled as the server ends its answer, as hits count.
  - [Marks and order](https://vlatte.dev/verify/marks-and-order.md): Select requests after a mark and verify their order without counting traffic from earlier tests.
  - [Admin API and MCP](https://vlatte.dev/verify/admin-api.md): A client in any language, or an AI agent, checks the requests as a Go test does, through the admin API.
  - [Troubleshooting](https://vlatte.dev/verify/troubleshooting.md): A check never passes or fails on part of the requests it counts.
- **Webhooks and events**
  - [Overview](https://vlatte.dev/webhooks/index.md): Once a mock has replied, it runs its `on_complete` events: each names a listener of the server, which gets the request, the mock and the event's parameters.
  - [Testing webhooks](https://vlatte.dev/guides/webhooks.md): This guide mocks a payment API that calls your service back once a payment is made, and checks that the callback came.
- **TLS**
  - [Overview](https://vlatte.dev/tls/index.md): A mock server serves HTTPS, or gRPC over TLS, with one call and no certificate to make.
  - [HTTP](https://vlatte.dev/http/tls.md): `m.MustStartTLS()` serves HTTPS, with no certificate to make: `m.URL()` starts with `https://`.
  - [gRPC](https://vlatte.dev/grpc/tls.md): `m.MustStartTLS()` serves gRPC over TLS, with a self-signed certificate for `localhost`, `127.0.0.1` and `::1`, and `m.Dial()` already trusts it.
  - [HTTPS and mTLS](https://vlatte.dev/guides/https-mtls.md): This guide tests a client of an API that serves HTTPS only, first with a certificate the client trusts, then with mutual TLS, where the client must present a certificate of its own.
- **Recipes**
  - [Overview](https://vlatte.dev/recipes/index.md): A recipe prepares a server, for example by adding a set of mocks.
  - [Proxy all](https://vlatte.dev/recipes/proxy-all.md): `recipe/http/proxyall` prepares an HTTP server to send what no other mock matches to a real service.
  - [GitHub Auth](https://vlatte.dev/recipes/github-auth.md): `recipe/http/githubauth` prepares an HTTP server to stand in for "Sign in with GitHub": the OAuth web flow of an OAuth app, and the profile of the user who signs in.
  - [OpenID Connect](https://vlatte.dev/recipes/oidc.md): `recipe/http/oidc` prepares an HTTP server to stand in for an OpenID Connect provider, for "Sign in with ..." through the authorization code flow: discovery, a JWKS, ID tokens the server signs, PKCE and userinfo.
  - [Writing a recipe](https://vlatte.dev/recipes/writing.md): A recipe is a `vlatte.Recipe`: its `Prep(ctx, input)` gets the server in `input.Server`, and adds mocks or changes what it serves.
- [Mock lifecycle](https://vlatte.dev/more/mock-lifecycle.md): These features work the same on HTTP and gRPC mocks, in Go and in mock files.
- [Request journal](https://vlatte.dev/more/journal.md): A server can keep a journal of the requests its mocks get, whatever their outcome: a mock answered it (`matched`), none matched (`unmatched`), another server did (`proxied`), serving it failed (`failed`), or its client left first (`abandoned`).

## Admin API

- [Overview](https://vlatte.dev/admin-api/index.md): The admin API manages a server while it runs.
- [OpenAPI reference](https://vlatte.dev/openapi/admin.yaml)

## Coding Agents

- [Overview](https://vlatte.dev/agents/index.md): Use a coding agent to write vlatte tests and mock files, or connect it to a running mock server to inspect and change what it serves.
- [Documentation for agents](https://vlatte.dev/agents/documentation.md): vlatte publishes plain Markdown documentation and machine-readable API schemas.
- [MCP overview](https://vlatte.dev/mcp/index.md): vlatte speaks the Model Context Protocol: an AI agent, such as a coding assistant, can drive a mock server with the same operations the admin API serves over REST.
- [MCP setup](https://vlatte.dev/mcp/setup.md): Connect an agent to vlatte over stdio or Streamable HTTP, from the CLI or from Go.
- [MCP tools](https://vlatte.dev/mcp/tools.md): Each tool runs an admin API operation.

## Reference

- [Overview](https://vlatte.dev/reference/index.md): Find Go API contracts, mock file schemas, the Admin API OpenAPI reference and the complete CLI settings.
- [Go API](https://vlatte.dev/reference/go-api.md): The Go API is documented on pkg.go.dev, from the doc comments of the code.
- [Mock file schemas](https://vlatte.dev/reference/schemas.md): Mock files have JSON Schemas, served at stable addresses, so editors complete and check them as you write.
- [Admin API (OpenAPI)](https://vlatte.dev/openapi/admin.yaml)
- [Settings](https://vlatte.dev/reference/settings.md): Every setting of the `vlatte` command, as `vlatte --help` lists it: its flag, its environment variable and its key in a `.vlatterc` file.

## Contributing

- [Contributing](https://vlatte.dev/contributing.md): VLatte is developed on GitHub.

## Optional

- [Every page in one file](https://vlatte.dev/llms-full.txt): the pages above, in the same order.
- [HTTP mock file schema](https://vlatte.dev/schemas/http.schema.json): the JSON Schema of HTTP mock files.
- [gRPC mock file schema](https://vlatte.dev/schemas/grpc.schema.json): the JSON Schema of gRPC mock files.
- [Admin API](https://vlatte.dev/openapi/admin.yaml): the OpenAPI document of the admin API.
- [Go API](https://pkg.go.dev/github.com/caffeine-projects/vlatte): the doc comments of every package, on pkg.go.dev.