DOCSEARCHbyAlgolia
Submit Docs

Hoverfly Documentation

repository·master·Indexed 25 days ago

https://github.com/spectolabs/hoverfly

A lightweight, high-performance API simulation tool used to replace real API dependencies with realistic, reusable simulations during development and testing. Hoverfly supports capturing and replaying HTTP(S) traffic, journal templating for dynamic responses, and extensible middleware implemented in JavaScript, Python, Ruby, or AWS Lambda. It includes a CLI, a REST API, and native Java bindings.

Tokens
36.8K
Snippets
93
Records
266
Agent score
79%

What's inside Hoverfly

  1. Overview of Hoverfly API simulations

    master

    Hoverfly is a lightweight, open source API simulation tool designed for development and testing. It allows you to create realistic simulations of API dependencies to:

    • Replace slow or flaky API dependencies with reusable simulations.
    • Simulate network latency, random failures, or rate limits to test edge cases.
    • Export, share, edit, and import API simulations.
    • Extend and customize using any programming language.

    Hoverfly provides a CLI, a REST API, and native language bindings for Java.

  2. What is Hoverfly?

    master

    Hoverfly is a lightweight, open-source API simulation tool designed to create realistic simulations of external API dependencies. It is used to replace slow or flaky dependencies with reusable simulations and to test edge cases by simulating network latency, random failures, or rate limits.

    Key features include:

    • Extensibility: Can be extended and customized with any programming language.
    • Simulation Management: Ability to export, share, edit, and import API simulations.
    • Interfaces: Provides a CLI, native language bindings (such as Java), and a REST API.
    • Performance: Lightweight and high-performance, suitable for running in various environments.
    • License: Apache 2 license.

  3. What is Hoverfly and why use it?

    master

    Hoverfly is a service virtualization tool designed to create a "dependency sandbox"—a simulated development and test environment that you control. It is intended to solve the difficulties of developing and testing applications that rely on external dependencies (such as legacy APIs or microservices under development) that are outside of your control.

    Key use cases include:

    • Avoiding intrusive mocks: Unlike mocking libraries, Hoverfly allows you to test up to the architectural boundary of your application without modifying your code.
    • Replacing complex stubs: It provides a more transparent alternative to stubbed services that often require heavy configuration.
    • Managing test data: It helps solve the bottleneck of managing fine-grained test data across large projects and multiple teams.
    • Stabilizing integration testing: It mitigates the issues of "over the wire" integration testing, such as network latency and random outages, by providing a controlled, simulated environment.

  4. Use Hoverfly Java for API simulation

    master

    Hoverfly Java provides a fluent DSL for generating simulated APIs. It allows for strict or loose HTTP request matching based on combinations of URL, method, body, and headers. Key features include:

    • Automatic JSON Marshalling: Objects are automatically marshalled into JSON when generating request/response bodies.
    • HTTPS Support: HTTPS is supported automatically without additional configuration.
    • Flexible Matching: Configure matching logic to be strict or loose based on the request components (URL, method, body, headers).

    For detailed usage and API references, consult the official Hoverfly Java documentation.

  5. What is a Post Serve Action

    master

    A PostServeAction allows you to execute custom code or invoke an endpoint with a request-response pair after a response has been served in either simulate or spy mode.

    Key characteristics:

    • It can be a custom script written in any language or a remote HTTP endpoint.
    • It can be executed on the local host operating system or a remote host.
    • It supports a configurable delay (in milliseconds) before execution.
    • Multiple actions can be registered.
    • To trigger a specific action, include its name in the postServeAction field within the response object of your simulation JSON.
    {
    "response": {
        "postServeAction": "<name of post serve action we want to invoke>"
    }
}

  6. What is hoverctl and how does it work?

    master

    Hoverctl is a command-line utility shipped with Hoverfly designed to simplify interactions with Hoverfly APIs and your local filesystem. It provides a streamlined way to start, stop, and manage Hoverfly instances.

    Key capabilities include:

    • Instance Management: Easily start and stop Hoverfly instances.
    • Multi-instance Support: Use the --target option to manage multiple Hoverfly instances simultaneously. This allows you to interact with different instances (e.g., one running locally and one running remotely) independently, as configuration is stored specifically for each target.

  7. How to use sequences to simulate stateful endpoints

    master

    Hoverfly allows you to recreate a sequence of different responses for a single request pattern by using stateful sequences. This is useful for testing endpoints that change behavior based on how many times they have been called or their current state.

    To implement a sequence:

    1. Prefix the state key: Use the prefix sequence: in your state keys (e.g., sequence:1). This tells Hoverfly the pair is part of a stateful sequence.
    2. Define requirements: In the request object, use requiresState to specify which step of the sequence the request must match.
    3. Define transitions: In the response object, use transitionsState to move the user to the next step in the sequence.
    4. End of sequence: Once Hoverfly reaches the final response in the sequence, it will continue to return that final response for all subsequent matching requests.
    {
  "data": {
    "pairs": [{
        "request": {
          "requiresState": {
            "sequence:1": "1"
          }
        },
        "response": {
          "status": 200,
          "body": "First response",
          "transitionsState": {
            "sequence:1": "2"
          }
        }
      },
      {
        "request": {
          "requiresState": {
            "sequence:1": "2"
          }
        },
        "response": {
          "status": 200,
          "body": "Second response"
        }
      }
    ]
  },
  "meta": {
    "schemaVersion": "v5.2"
  }
}

  10. Use PostServeAction to execute custom code after a response

    master

    PostServeAction allows you to execute custom code (via an external binary and script) after a response has been served in either simulate or spy mode. This is useful for triggering webhooks, initiating background processing, or logging data once a specific response is delivered.

    To use a PostServeAction, you must:

    1. Register the action with hoverctl specifying the binary (e.g., python3, bash, node) and the script path.
    2. Reference the action by its --name in the postServeAction field of a simulation JSON response.

    Note: While the example uses Python, you can use any language as long as the corresponding binary is available in your local environment.