Skip to content

API Mocking

Use WireMock to decouple local development and integration tests from external APIs, including error and resilience scenarios that are hard to reproduce against a live service.

Workflow Guide
Download WireMock Cloud definitions and run them locally through Aspire WireMock Hosting
Orchestrate several mock services as one AppHost resource WireMock Runner Hosting, an experimental API
Capture API interactions and save them to a cloud project WireMock Recording

Cloud-hosted mocks require a WireMock Cloud account. WireMock CLI hosting runs the CLI as a local executable, while WireMock Runner hosting runs a container, so complete Docker Desktop provisioning before you use the runner. Each hosting guide lists the prerequisites specific to its workflow; cloud-managed definitions can also be downloaded for local work.

Both hosting options register each mock as an Aspire resource, so your application resolves the mock's endpoint through Aspire service discovery once it calls WithReference(mock), and the Aspire dashboard shows each mock's status.

Mocks belong in development and testing, not production. They verify your application's response to the defined behavior, not whether the external API still behaves that way. Keep sensitive data out of recordings before saving or sharing them.

See the working WireMock CLI example and WireMock Runner example, the WireMock Cloud documentation, and the WireMock CLI documentation.

Shared prerequisites

Both hosting guides assume you have:

  • The .NET 10.0 SDK installed.
  • An API project with one or more external API dependencies you want to mock.
  • An Aspire AppHost project that sets up your application and its dependencies.

Find your mock API ID

AddMock takes a wiremockProjectId when it should pull an existing WireMock Cloud mock API:

  1. Open the mock API in WireMock Cloud.
  2. Copy the URL from your browser, for example https://app.wiremock.cloud/mock-apis/abc123xyz/stubs/....
  3. Use the identifier after mock-apis/ as the wiremockProjectId. In this example, the ID is abc123xyz.