Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bkuhlmann/http-fake

A HTTP fake implementation for test suites.
https://github.com/bkuhlmann/http-fake

api fake http rspec testing

Last synced: 3 days ago
JSON representation

A HTTP fake implementation for test suites.

Awesome Lists containing this project

README 

        
: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



* Provides a fake HTTP client as a testing companion to the {http_link} gem.

* Supports the following HTTP verbs: CONNECT, DELETE, GET, HEAD, OPTIONS, PATCH, POST, PURGE, PUT, and TRACE.

* Uses a simple DSL for defining HTTP endpoints, headers, bodies, and statuses.

* Works well with objects that use Dependency Injection.

* Speeds up your test suite when you don't need a live API.



== Requirements



. link:https://www.ruby-lang.org[Ruby].

. {http_link}.



== Setup



To install within an existing project, run:



[source,bash]

----

bundle add http-fake

----



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:



[source,ruby]

----

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



  describe "#customers" do

    it "answers customers array when successful" do

      response = endpoint.customers

      expect(response.parse).to eq(customers: [{name: "Jill Smith"}])

    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:



[source,ruby]

----

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 }

  end

end

----



So far you've only seen usage of JSON responses but you might want to use other MIME types. For example, XML:



[source,ruby]

----

HTTP::Fake::Client.new do

  get "/customers/1" do

    headers["Content-Type"] = "application/xml"

    status 200



    <<~XML

      

        1

        Jill Smith

      

    XML

  end

end

----



Plain text would work too:



[source,ruby]

----

HTTP::Fake::Client.new do

  get "/customers" do

    headers["Content-Type"] = "text/plain"

    status 200



    "1 - Jill Smith"

    "2 - Tom Bombadill"

  end

end

----



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:



[source,ruby]

----

# Single

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



# Multiple

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

  end

end

----



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:



[source,bash]

----

git clone https://github.com/bkuhlmann/http-fake

cd http-fake

bin/setup

----



You can also use the IRB console for direct access to all objects:



[source,bash]

----

bin/console

----



== Tests



To test, run:



[source,bash]

----

bin/rake

----



== 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



* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].