# Hoverfly — Lightweight API Simulation and Service Virtualization

> A lightweight Go-based tool for simulating and testing HTTP services by capturing and replaying API traffic.

## Install

Save in your project root:

# Hoverfly — Lightweight API Simulation and Service Virtualization

## Quick Use
```bash
# Install
brew install SpectoLabs/tap/hoverfly
# Capture mode: record real API responses
hoverfly -capture
# Simulate mode: replay recorded responses
hoverfly -simulate simulation.json
# Use hoverctl for management
hoverctl start && hoverctl mode simulate
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-513ba3dc
Author: AI Open Source