WireMock on LocalStack

This repo contains a LocalStack Extension that facilitates developing WireMock-based applications locally.

The extension supports two modes:

• OSS WireMock: Uses the open-source wiremock/wiremock image (default)
• WireMock Runner: Uses wiremock/wiremock-runner with WireMock Cloud integration (requires API token)

Prerequisites

• Docker
• LocalStack Pro (free trial available)
• localstack CLI
• make
• WireMock CLI (for WireMock Runner mode)

Install from GitHub repository

This extension can be installed directly from this Github repo via:

localstack extensions install "git+https://github.com/localstack/localstack-extensions.git#egg=localstack-wiremock&subdirectory=wiremock"

Install local development version

To install the extension into LocalStack in developer mode, you will need Python 3.11, and create a virtual environment in the extensions project.

In the newly generated project, simply run

make install

Then, to enable the extension for LocalStack, run

localstack extensions dev enable .

You can then start LocalStack with EXTENSION_DEV_MODE=1 to load all enabled extensions:

EXTENSION_DEV_MODE=1 localstack start

Usage

OSS WireMock Mode (Default)

Start LocalStack without any special configuration:

localstack start

The WireMock server will be available at http://wiremock.localhost.localstack.cloud:4566.

You can import stubs using the WireMock Admin API (assuming a stubs.json exists in the local working directory):

curl -X POST -H "Content-Type: application/json" \
  --data-binary "@stubs.json" \
  "http://wiremock.localhost.localstack.cloud:4566/__admin/mappings/import"

WireMock Runner Mode (Cloud Integration)

To use WireMock Runner with WireMock Cloud, you need:

1. A WireMock Cloud API token
2. A .wiremock directory with your mock API configuration

Step 1: Get your WireMock Cloud API Token

1. Sign up at WireMock Cloud
2. Go to Settings → API Tokens
3. Create a new token

Step 2: Create your Mock API configuration

First, create a Mock API in WireMock Cloud, then pull the configuration locally:

# Install WireMock CLI if not already installed
npm install -g @wiremock/cli

# Login with your API token
wiremock login

# Pull your Mock API configuration
# Find your Mock API ID from the WireMock Cloud URL (e.g., https://app.wiremock.cloud/mock-apis/zwg1l/...)
wiremock pull mock-api <mock-api-id>

This creates a .wiremock directory with your wiremock.yaml configuration.

Step 3: Start LocalStack with WireMock Runner

LOCALSTACK_WIREMOCK_API_TOKEN="your-api-token" \
LOCALSTACK_WIREMOCK_CONFIG_DIR="/path/to/your/project" \
localstack start

Environment Variables:

• WIREMOCK_API_TOKEN: Your WireMock Cloud API token (required for runner mode)
• WIREMOCK_CONFIG_DIR: Path to the directory containing your .wiremock folder (required for runner mode)
• WIREMOCK_IMAGE: Custom Docker image name for the Wiremock OSS image (default: wiremock/wiremock)
• WIREMOCK_IMAGE_RUNNER: Custom Docker image name for the Wiremock Cloud runner image (default: wiremock/wiremock-runner)

Note: When using the LocalStack CLI, prefix environment variables with LOCALSTACK_ to forward them to the container.

Sample Application

See the sample-app-runner/ directory for a complete example using Terraform that demonstrates:

• Creating an API Gateway
• Lambda function that calls WireMock stubs
• Integration testing with mocked external APIs

Change Log

• 0.1.1: Add environment variables to customize the WireMock image names
• 0.1.0: Initial release of the extension

License

This project is licensed under the Apache License, Version 2.0.