Hoverfly — Lightweight API Simulation and Service Virtualization

Introduction

Hoverfly is a lightweight HTTP(S) proxy written in Go that captures and simulates API interactions. It sits between your application and external services, recording real responses during development and replaying them during testing — eliminating flaky tests caused by third-party dependencies.

What Hoverfly Does

• Captures real HTTP traffic and stores it as replayable simulations
• Simulates APIs by matching requests and returning recorded responses
• Modifies responses on the fly with middleware and templating
• Introduces network latency and failure scenarios for chaos testing
• Provides a web admin UI and REST API for simulation management

Architecture Overview

Hoverfly operates as a forward or reverse proxy. In capture mode, it passes requests through to real services while recording request-response pairs. In simulate mode, it matches incoming requests against stored simulations using configurable matchers (exact, glob, regex, xpath, jsonpath) and returns the paired response without hitting the real service.

Self-Hosting & Configuration

• Single binary install via brew, apt, or direct download
• Run as a proxy or in webserver mode (no proxy config needed)
• Manage via hoverctl CLI or REST admin API on port 8888
• Import/export simulations as JSON for version control
• Configure request matching strategies per endpoint

Key Features

• Record-and-replay workflow for deterministic API testing
• Request matching with glob, regex, XPath, and JSONPath matchers
• Response templating with dynamic data (timestamps, UUIDs, request fields)
• Middleware support for custom response modification logic
• Stateful simulations for multi-step workflow testing

Comparison with Similar Tools

• WireMock — Java-based, more features for enterprise mocking; Hoverfly is lighter and language-agnostic
• MockServer — Broader protocol support; Hoverfly focuses on HTTP simplicity
• Mountebank — Multi-protocol (TCP, SMTP); Hoverfly is HTTP-only but faster
• Nock (Node.js) — In-process HTTP mocking; Hoverfly works as external proxy for any language

FAQ

Q: Can Hoverfly handle HTTPS traffic? A: Yes. It generates a self-signed CA certificate for MITM proxy mode. Install the CA cert in your trust store for transparent HTTPS capture.

Q: How do I use Hoverfly in CI pipelines? A: Export simulations to JSON, commit them to your repo, and start Hoverfly in simulate mode before running tests. No network access to real APIs needed.

Q: Does Hoverfly support WebSocket or gRPC? A: Hoverfly is HTTP/HTTPS only. For gRPC, consider using grpc-mock or similar tools.

Q: Can I add latency to simulations? A: Yes. Configure fixed or random delays per simulation to test timeout handling and retry logic.

Sources

• https://github.com/SpectoLabs/hoverfly
• https://docs.hoverfly.io/