A HTTP fake implementation for test suites.
OTHER License
:http_link: link:https://github.com/httprb/http[HTTP]
:toc: macro :toclevels: 5 :figure-caption!:
= HTTP Fake
HTTP Fake is a companion to the {http_link} gem when you want a convenient way to test HTTP requests by swapping out your real HTTP client with this fake HTTP client. Using a fake allows you to improve the performance of your test suite by answering fake responses without hitting a live API. You'll still want to test against a live API, eventually, within your integration tests but at a lower level, like your unit tests, you can use this gem instead. This gem is particularly useful when using Dependency Injection, especially when coupled with the link:https://alchemists.io/projects/infusible[Infusible] gem.
toc::[]
== Features
== Requirements
. link:https://www.ruby-lang.org[Ruby]. . {http_link}.
== Setup
To install within an existing project, run:
You'll want to ensure this gem is part of your test group since it's only meant to aid in writing specs.
== Usage
This gem works with any test framework. For demonstration purposes, we'll assume you're using link:https://rspec.info[RSpec] but you can adapt these examples to your test framework of choice. A simple spec might look like this:
RSpec.describe Endpoint do subject(:endpoint) { described_class.new http: }
let :http do HTTP::Fake::Client.new do get "/customers" do headers["Content-Type"] = "application/json" status 200
<<~JSON
{
"customers": [
{"name": "Jill Smith"}
]
}
JSON
end
end
end
As you can see, our fake http
client has been defined and injected into our endpoint
subject. When the fake is defined, the path, headers, status, and body are registered as well. This allows the fake to match against your real implementation's URL path and swap out acquiring a real HTTP response with fake response instead. When asking the endpoint for its customers, we get back the fake response with all of the normal capabilities of the real HTTP client. This works because this gem uses link:https://github.com/sinatra/mustermann[Mustermann] for pattern matching against the routes you define and also means you can define routes that are explicit -- as shown above -- or fuzzy based on your testing needs.
Here's an example where multiple endpoints are defined for the same fake in case your implementation needs to test multiple endpoints at once:
let :http do HTTP::Fake::Client.new do connect("/") { status 200 }
head("/") { status 200 }
options("/") { status 204 }
get "/customers" do
headers["Content-Type"] = "application/json"
status 200
<<~JSON
{
"customers": [
{"name": "Jill Smith"}
]
}
JSON
end
post "/customers" do
headers["Content-Type"] = "application/json"
status 201
{}
end
put "/customers/1" do
headers["Content-Type"] = "application/json"
status 200
end
patch "/customers/1" do
headers["Content-Type"] = "application/json"
status 200
end
delete("/customers/1") { status 204 }
trace("/") { status 200 }
So far you've only seen usage of JSON responses but you might want to use other MIME types. For example, XML:
HTTP::Fake::Client.new do get "/customers/1" do headers["Content-Type"] = "application/xml" status 200
<<~XML
<customer>
<id>1</id>
<name>Jill Smith</name>
</customer>
XML
Plain text would work too:
HTTP::Fake::Client.new do get "/customers" do headers["Content-Type"] = "text/plain" status 200
"1 - Jill Smith"
"2 - Tom Bombadill"
You might even want to import a fixture which is especially handy when the response is verbose or needs to be reused in different ways. Example:
HTTP::Fake::Client.new do get "/customers/1" do headers["Content-Type"] = "application/json" status 200 SPEC_ROOT.join("support/fixtures/customer.json").read end end
HTTP::Fake::Client.new do get "/customers" do headers["Content-Type"] = "application/json" status 200
<<~JSON
[#{SPEC_ROOT.join("support/fixtures/customer.json").read}]
JSON
Since you have the ability to define your own headers and status codes, you can also test failure response behavior as well. I'll leave that up to you to explore and experiment with further.
== Development
To contribute, run:
You can also use the IRB console for direct access to all objects:
== Tests
To test, run:
== link:https://alchemists.io/policies/license[License]
== link:https://alchemists.io/policies/security[Security]
== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]
== link:https://alchemists.io/policies/contributions[Contributions]
== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]
== link:https://alchemists.io/projects/http-fake/versions[Versions]
== link:https://alchemists.io/community[Community]
== Credits