How to Set Up WireMock on macOS: A Step-by-Step Guide With Start/Stop Scripts

If you’re working with microservices, APIs, or contract testing, chances are you’ve run into a situation where the backend service you need just isn’t ready. That’s where WireMock shines — a powerful tool that lets you mock HTTP APIs, simulate service behavior, and test independently.

In this guide, we’ll walk through setting up WireMock on macOS, understand why each step matters, and finish with handy bash scripts to start and stop WireMock containers like a pro.

🧠 Why Use WireMock?

WireMock is perfect when:

• Your backend APIs are under development or flaky.

• You want to test edge cases, delays, or failures.

• You need consistent test environments.

Instead of relying on real services, you can simulate them with JSON stubs, making your integration testing faster and more reliable.

🛠️ Prerequisites

Before we begin, ensure you have:

• macOS (Intel or Apple Silicon)

• Docker Desktop for Mac

• Basic Terminal experience

🧪 Step-by-Step Setup

Step 1: Install Docker

First, download and install Docker Desktop for macOS if you haven’t already:

brew install --cask docker

Then launch Docker from Spotlight (Cmd + Space, then type "Docker") and ensure it’s running.

Note:

If Docker is already installed but behaving strangely, or you just want a fresh start, use the script below. It will:

• Detect existing Docker installations

• Stop Docker if it's running

• Remove old binaries and configs

• Reinstall Docker Desktop via Homebrew

🔧 install-clean-docker.sh

#!/bin/bash

echo "🔍 Checking if Docker is installed..."

# Check for Docker
if command -v docker &> /dev/null; then
    echo "🐳 Docker is already installed. Removing existing installation..."

    # Stop Docker if it's running
    echo "🛑 Stopping Docker services..."
    osascript -e 'quit app "Docker"'

    sleep 3

    # Uninstall Docker components
    echo "🧹 Removing Docker binaries and support files..."
    brew uninstall --cask docker || echo "⚠️ Docker not installed via brew, skipping brew uninstall."

    sudo rm -rf /Applications/Docker.app
    sudo rm -rf ~/Library/Containers/com.docker.docker
    sudo rm -rf ~/.docker
    sudo rm -rf ~/Library/Application\ Support/Docker*
    sudo rm -rf /usr/local/bin/docker /usr/local/bin/docker-compose /usr/local/bin/docker-credential-desktop /usr/local/bin/docker-credential-osxkeychain
    sudo rm -rf /usr/local/bin/com.docker.cli

    echo "✅ Docker has been removed."
else
    echo "✅ Docker is not installed. Proceeding to install..."
fi

# Install Docker Desktop via Homebrew
echo "📦 Installing Docker Desktop using Homebrew..."
brew install --cask docker

echo "🚀 Launching Docker Desktop..."
open /Applications/Docker.app

echo "✅ Docker installation script complete. Please wait for Docker Desktop to initialize fully before use."

🧪 To use this script:

chmod +x install-clean-docker.sh
./install-clean-docker.sh

This gives you a fresh, clean Docker environment — perfect for running WireMock with no hidden config issues.

---

Refer to manual installation guide if above steps fail:

Manually Install docker on MacOS

---

Step 2: Create a WireMock Project Folder

Let’s organize our mock API configuration.

mkdir wiremock-mockapi && cd wiremock-mockapi
mkdir mappings __files

• mappings/: JSON files defining request/response behavior

• __files/: Optional files (e.g., response payloads)

Step 3: Add Sample Stub Mapping

Here’s an example stub to mock GET /hello:

mappings/hello-get.json

{
  "request": {
    "method": "GET",
    "url": "/hello"
  },
  "response": {
    "status": 200,
    "body": "Hello from WireMock!",
    "headers": {
      "Content-Type": "text/plain"
    }
  }
}

You can add many such mappings for your testing needs.

Step 4: Run WireMock in Docker

Now let’s run WireMock with our mappings mounted into the container:

docker run --rm -d \
  --name wiremock \
  -p 8080:8080 \
  -v "$(pwd)/mappings":/home/wiremock/mappings \
  -v "$(pwd)/__files":/home/wiremock/__files \
  wiremock/wiremock:3.3.1

✅ Open your browser and visit:
http://localhost:8080/hello
You should see: “Hello from WireMock!”

🧹 Step 5: Stop the WireMock Container

When you’re done:

docker stop wiremock

This stops and removes the container

🚀 Bonus: Start and Stop Scripts

Save time with two handy bash scripts!

wiremock-start.sh

#!/bin/bash
echo "✅ Starting WireMock on http://localhost:8080..."
docker run --rm -d \
  --name wiremock \
  -p 8080:8080 \
  -v "$(pwd)/mappings":/home/wiremock/mappings \
  -v "$(pwd)/__files":/home/wiremock/__files \
  wiremock/wiremock:3.3.1

wiremock-stop.sh

#!/bin/bash
echo "🛑 Stopping WireMock..."
docker stop wiremock

Make them executable:

chmod +x wiremock-start.sh wiremock-stop.sh

Now you can easily run:

./wiremock-start.sh
# do your testing...
./wiremock-stop.sh

---

✅ Recap

---

💡 Final Thoughts

WireMock helps decouple testing from real APIs. With just a few JSON files and Docker, you can mock almost any HTTP interaction.

This setup is perfect for:

• Test automation

• CI pipelines

• Simulating third-party services

Happy mocking!