diff --git a/guides/links.yaml b/guides/links.yaml new file mode 100644 index 0000000..d1b7ca5 --- /dev/null +++ b/guides/links.yaml @@ -0,0 +1,2 @@ +mocking: + order: 5 diff --git a/guides/mocking/readme.md b/guides/mocking/readme.md new file mode 100644 index 0000000..124d271 --- /dev/null +++ b/guides/mocking/readme.md @@ -0,0 +1,75 @@ +# Mocking + +This guide explains how to modify `Async::HTTP::Client` for mocking responses in tests. + +## Mocking HTTP Responses + +The mocking feature of `Async::HTTP` uses a real server running in a separate task, and routes all requests to it. This allows you to intercept requests and return custom responses, but still use the real HTTP client. + +In order to enable this feature, you must create an instance of {ruby Async::HTTP::Mock::Endpoint} which will handle the requests. + +~~~ ruby +require 'async/http' +require 'async/http/mock' + +mock_endpoint = Async::HTTP::Mock::Endpoint.new + +Sync do + # Start a background server: + server_task = Async(transient: true) do + mock_endpoint.run do |request| + # Respond to the request: + ::Protocol::HTTP::Response[200, {}, ["Hello, World"]] + end + end + + endpoint = Async::HTTP::Endpoint.parse("https://www.google.com") + mocked_endpoint = mock_endpoint.wrap(endpoint) + client = Async::HTTP::Client.new(mocked_endpoint) + + response = client.get("/") + puts response.read + # => "Hello, World" +end +~~~ + +## Transparent Mocking + +Using your test framework's mocking capabilities, you can easily replace the `Async::HTTP::Client#new` with a method that returns a client with a mocked endpoint. + +### Sus Integration + +~~~ ruby +require 'async/http' +require 'async/http/mock' +require 'sus/fixtures/async/reactor_context' + +include Sus::Fixtures::Async::ReactorContext + +let(:mock_endpoint) {Async::HTTP::Mock::Endpoint.new} + +def before + super + + # Mock the HTTP client: + mock(Async::HTTP::Client) do |mock| + mock.wrap(:new) do |original, endpoint| + original.call(mock_endpoint.wrap(endpoint)) + end + end + + # Run the mock server: + Async(transient: true) do + mock_endpoint.run do |request| + ::Protocol::HTTP::Response[200, {}, ["Hello, World"]] + end + end +end + +it "should perform a web request" do + client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse("https://www.google.com")) + response = client.get("/") + # The response is mocked: + expect(response.read).to be == "Hello, World" +end +~~~ diff --git a/lib/async/http.rb b/lib/async/http.rb index 6b67b2b..3eac9b4 100644 --- a/lib/async/http.rb +++ b/lib/async/http.rb @@ -8,4 +8,6 @@ require_relative 'http/client' require_relative 'http/server' +require_relative 'http/internet' + require_relative 'http/endpoint' diff --git a/lib/async/http/mock.rb b/lib/async/http/mock.rb new file mode 100644 index 0000000..050f1c2 --- /dev/null +++ b/lib/async/http/mock.rb @@ -0,0 +1,23 @@ +# frozen_string_literal: true +# +# Copyright, 2019, by Samuel G. D. Williams. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +require_relative 'mock/endpoint' diff --git a/lib/async/http/mock/endpoint.rb b/lib/async/http/mock/endpoint.rb new file mode 100644 index 0000000..798caef --- /dev/null +++ b/lib/async/http/mock/endpoint.rb @@ -0,0 +1,70 @@ +# frozen_string_literal: true +# +# Copyright, 2019, by Samuel G. D. Williams. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +require_relative '../protocol' + +require 'async/queue' + +module Async + module HTTP + module Mock + # This is an endpoint which bridges a client with a local server. + class Endpoint + def initialize(protocol = Protocol::HTTP2, scheme = "http", authority = "localhost", queue: Queue.new) + @protocol = protocol + @scheme = scheme + @authority = authority + + @queue = queue + end + + attr :protocol + attr :scheme + attr :authority + + # Processing incoming connections + # @yield [::HTTP::Protocol::Request] the requests as they come in. + def run(parent: Task.current, &block) + while peer = @queue.dequeue + server = @protocol.server(peer) + + parent.async do + server.each(&block) + end + end + end + + def connect + local, remote = ::Socket.pair(Socket::AF_UNIX, Socket::SOCK_STREAM) + + @queue.enqueue(remote) + + return local + end + + def wrap(endpoint) + self.class.new(@protocol, endpoint.scheme, endpoint.authority, queue: @queue) + end + end + end + end +end diff --git a/test/async/http/mock.rb b/test/async/http/mock.rb new file mode 100644 index 0000000..d54840c --- /dev/null +++ b/test/async/http/mock.rb @@ -0,0 +1,74 @@ +# Copyright, 2019, by Samuel G. D. Williams. +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +require 'async/http/mock' +require 'async/http/endpoint' +require 'async/http/client' + +require 'sus/fixtures/async/reactor_context' + +describe Async::HTTP::Mock do + include Sus::Fixtures::Async::ReactorContext + + let(:endpoint) {Async::HTTP::Mock::Endpoint.new} + + it "can respond to requests" do + server = Async do + endpoint.run do |request| + ::Protocol::HTTP::Response[200, [], ["Hello World"]] + end + end + + client = Async::HTTP::Client.new(endpoint) + + response = client.get("/index") + + expect(response).to be(:success?) + expect(response.read).to be == "Hello World" + end + + with 'mocked client' do + it "can mock a client" do + server = Async do + endpoint.run do |request| + ::Protocol::HTTP::Response[200, [], ["Authority: #{request.authority}"]] + end + end + + mock(Async::HTTP::Client) do |mock| + replacement_endpoint = self.endpoint + + mock.wrap(:new) do |original, original_endpoint, **options| + original.call(replacement_endpoint.wrap(original_endpoint), **options) + end + end + + google_endpoint = Async::HTTP::Endpoint.parse("https://www.google.com") + client = Async::HTTP::Client.new(google_endpoint) + + response = client.get("/search?q=hello") + + expect(response).to be(:success?) + expect(response.read).to be == "Authority: www.google.com" + ensure + response&.close + end + end +end