http_stub
is a service virtualization tool.
It provides a HTTP server that is configurable on-the-fly to stub responses
to matched requests.
http_stub
has been primarily designed to aid automated and exploratory testing for API consumers:
- By providing tools to simulate a producer API and change its responses on-the-fly
- By aiming to provide tools that validate the simulation is true to the producer
http_stub
is composed of two parts:
- A HTTP server (Sinatra) that replays known responses when an incoming request matches defined criteria. The server is run in a dedicated - external - process to the system under test to better simulate the real architecture.
- A Ruby DSL used to configure the server known as a
Configurator
To simulate a response from an authentication service, let's stub the service and respond to its login endpoint by either granting or denying access:
module AuthenticationService
class Configurator
include HttpStub::Configurator
login_template = stub_server.endpoint_template { match_requests(uri: "/login", method: :post) }
login_template.add_scenario!("Grant access", status: 200)
login_template.add_scenario!("Deny access", status: 401)
end
end
Define tasks to manage the servers lifecycle:
require 'http_stub/rake/task_generators'
configurator = AuthenticationService::Configurator
configurator.stub_server.port = 8000
HttpStub::Rake::ServerDaemonTasks.new(name: :authentication_service, configurator: configurator)
Then start the server:
some_host:some_path some_user$ rake authentication_service:start
authentication_service started on localhost:8000
Congratulations, your server is now running on localhost:8000
!
Now we can activate scenarios as needed.
Within automated tests you'll often need to activate a scenario:
let(:stub_client) { HttpStub::Client.new("http://localhost:8000") }
context "when access is granted" do
before(:example) { stub_client.activate!("Grant access") }
...
end
The server has an admin UI accessible on http://localhost:8000/http_stub
:
It allows scenarios to be listed and activated on-the-fly:
http_stub
can match requests against a
variety of criteria, including JSON schemas, and can
respond with arbitrary content including files and
values interpolated from the matching request.
See the wiki for more usage details and examples.
For those using Docker, http_stub_docker provides Rake tasks that simplify creating, validating and distributing Docker containers for stubs.
In your Gemfile include:
gem 'http_stub'
- Ruby >= 2.3 (see the CHANGELOG for older versions supporting prior Rubies)
- A Rack server
Facilitates consumer driven contracts by allowing consumers to define a contract that is shared with and verified by producers.
In comparison http_stub
:
- Supports on-the-fly changes to responses to aid exploratory testing and demonstrations.
- Supports specification based contracts in addition to example based contracts. Incoming requests can be matched through the use of clauses such as regular expressions and JSON schema definitions.
- See comparison with
http-stub-server
for more highlights.
http_stub
can be used for Consumer & Producer based contract verification.
For more information, see the dedicated Slide Deck & Wiki Page.
Records requests and responses onto 'cassettes'. Replays responses in-process by mocking HTTP libraries in use.
In comparison http_stub
:
- Relies on an external HTTP server and does not effect HTTP libraries in use.
- Facilitates test-first practice by not relying on real integrations being recorded and pre-existing.
- Can make it easier to write and alter requests and responses by not having to alter or re-record cassettes / recordings.
Similar in spirit, implemented in Java and comes with Java and Ruby clients.
In comparison http_stub
:
- Has session support to facilitate parallel test execution.
- Has the concept of scenarios that allow on-the-fly changes to responses. This aids automated testing, exploratory testing and demonstrations.
- Supports a wider range of matching rules and can match requests against JSON schemas.
- Supports references to request headers and parameters in responses.
- Supports multi-part file responses.
- Allows cross-origin request support to be enabled easily.
- Allows a match to trigger the registration of other
stubs
to simulate state changes in the provider. - Has diagnostic pages to interrogate the state of the stub, trace requests to responses, and activate scenarios on-the-fly.
- Has an elegant Ruby DSL that aids in keeping requests and responses DRY.
These are similar in spirit, implemented in Ruby, but have limited functionality and have been discontinued.