From d9ec3a5f48f2feba947d6a0d2077b190084ac2f8 Mon Sep 17 00:00:00 2001 From: rick olson Date: Wed, 10 Apr 2019 11:36:59 -0600 Subject: [PATCH 1/3] add new pages for testing, the env, and middleware usage --- docs/adapters/testing.md | 26 ++++++++++++++++++++++++++ docs/env.md | 3 +++ docs/middleware/README.md | 24 ++++++++++++++++++++++++ 3 files changed, 53 insertions(+) create mode 100644 docs/adapters/testing.md create mode 100644 docs/env.md create mode 100644 docs/middleware/README.md diff --git a/docs/adapters/testing.md b/docs/adapters/testing.md new file mode 100644 index 00000000..c3d13a18 --- /dev/null +++ b/docs/adapters/testing.md @@ -0,0 +1,26 @@ +# Testing + +The built-in Faraday Test adapter lets define stubbed HTTP requests. This can +be used to mock out network services in an application's unit tests. + +The easiest way to do this is to create the stubbed requests when initializing +a `Faraday::Connection`. Stubbing a request by path yields a block with a +`Faraday::Env` object. The stub block expects an Array return value with three +values: an Integer HTTP status code, a Hash of key/value headers, and a +response body. + +```ruby +conn = Faraday.new do |builder| + builder.adapter :test do |stub| + stub.get('/ebi') do |env| + [ + 200, # status code + { + 'Content-Type': 'text/plain', + }, # headers + 'shrimp' # response body + ] + end + end +end +``` diff --git a/docs/env.md b/docs/env.md new file mode 100644 index 00000000..28748365 --- /dev/null +++ b/docs/env.md @@ -0,0 +1,3 @@ +# Faraday Env + +Faraday loves the environment. diff --git a/docs/middleware/README.md b/docs/middleware/README.md new file mode 100644 index 00000000..495fadb7 --- /dev/null +++ b/docs/middleware/README.md @@ -0,0 +1,24 @@ +# Middleware Usage + +A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a +Rack-inspired middleware stack for making HTTP requests. Each middleware runs +and passes an Env object around to the next one. After the final middleware has +run, Faraday will return a `Faraday::Response` to the end user. + +## Middleware Types + +**Request middleware** can modify Request details before the Adapter runs. Most +middleware set Header values or transform the request body based on the +content type. + +* `BasicAuthentication` sets the `Authorization` header to the `user:password` +base64 representation. +* `Multipart` converts a `Faraday::Request#body` hash of key/value pairs into a +multipart form request. +* `UrlEncoded` converts a `Faraday::Request#body` hash of key/value pairs into a url- +encoded request body. + +**Adapters** make requests. TBD + +* `Retry` automatically retries requests that fail due to intermittent client +or server errors (such as network hiccups). From 07788ab977c7d4b5cf2ef69b01a873dc3ca9a604 Mon Sep 17 00:00:00 2001 From: rick olson Date: Wed, 10 Apr 2019 12:05:53 -0600 Subject: [PATCH 2/3] finish testing, and start listing docs in readme --- README.md | 42 +++++------------------------------- docs/adapters/testing.md | 33 ++++++++++++++++++++++++++++ docs/{ => middleware}/env.md | 0 3 files changed, 38 insertions(+), 37 deletions(-) rename docs/{ => middleware}/env.md (100%) diff --git a/README.md b/README.md index 2dd38d13..6699a326 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,12 @@ Here is the list of known external adapters: It also includes a Rack adapter for hitting loaded Rack applications through Rack::Test, and a Test adapter for stubbing requests by hand. -## API documentation +## Documentation -Available at [rubydoc.info](http://www.rubydoc.info/gems/faraday). +* [Faraday API RubyDoc](http://www.rubydoc.info/gems/faraday) +* [Middleware](./docs/middleware) + * [Middleware Environment](./docs/middleware/env.md) +* [Testing](./docs/adapters/testing.md) ## Usage @@ -290,41 +293,6 @@ Faraday is intended to be a generic interface between your code and the adapter. When that happens, you can pass a block when specifying the adapter to customize it. The block parameter will change based on the adapter you're using. See below for some examples. -## Using Faraday for testing - -```ruby -# It's possible to define stubbed request outside a test adapter block. -stubs = Faraday::Adapter::Test::Stubs.new do |stub| - stub.get('/tamago') { |env| [200, {}, 'egg'] } -end - -# You can pass stubbed request to the test adapter or define them in a block -# or a combination of the two. -test = Faraday.new do |builder| - builder.adapter :test, stubs do |stub| - stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]} - end -end - -# It's also possible to stub additional requests after the connection has -# been initialized. This is useful for testing. -stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]} - -resp = test.get '/tamago' -resp.body # => 'egg' -resp = test.get '/ebi' -resp.body # => 'shrimp' -resp = test.get '/uni' -resp.body # => 'urchin' -resp = test.get '/else' #=> raises "no such stub" error - -# If you like, you can treat your stubs as mocks by verifying that all of -# the stubbed calls were made. NOTE that this feature is still fairly -# experimental: It will not verify the order or count of any stub, only that -# it was called once during the course of the test. -stubs.verify_stubbed_calls -``` - ## Supported Ruby versions This library aims to support and is [tested against][travis] the following Ruby diff --git a/docs/adapters/testing.md b/docs/adapters/testing.md index c3d13a18..44867ac6 100644 --- a/docs/adapters/testing.md +++ b/docs/adapters/testing.md @@ -24,3 +24,36 @@ conn = Faraday.new do |builder| end end ``` + +You can define the stubbed requests outside of the test adapter block: + +```ruby +stubs = Faraday::Adapter::Test::Stubs.new do |stub| + stub.get('/tamago') { |env| [200, {}, 'egg'] } +end +``` + +This Stubs instance can be passed to a new Connection: + +```ruby +conn = Faraday.new do |builder| + builder.adapter :test, stubs do |stub| + stub.get('/ebi') { |env| [ 200, {}, 'shrimp' ]} + end +end +``` + +It's also possible to stub additional requests after the connection has been +initialized. This is useful for testing. + +```ruby +stubs.get('/uni') { |env| [ 200, {}, 'urchin' ]} +``` + +Finally, you can treat your stubs as mocks by verifying that all of the stubbed +calls were made. NOTE: this feature is still fairly experimental. It will not +verify the order or count of any stub. + +```ruby +stubs.verify_stubbed_calls +``` diff --git a/docs/env.md b/docs/middleware/env.md similarity index 100% rename from docs/env.md rename to docs/middleware/env.md From 980a9514e0e73c4517bf71f9c62f14c9942ca5eb Mon Sep 17 00:00:00 2001 From: Olle Jonsson Date: Fri, 12 Apr 2019 21:33:51 +0200 Subject: [PATCH 3/3] [ci skip] Add missing "you" --- docs/adapters/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adapters/testing.md b/docs/adapters/testing.md index 44867ac6..ecaa4597 100644 --- a/docs/adapters/testing.md +++ b/docs/adapters/testing.md @@ -1,6 +1,6 @@ # Testing -The built-in Faraday Test adapter lets define stubbed HTTP requests. This can +The built-in Faraday Test adapter lets you define stubbed HTTP requests. This can be used to mock out network services in an application's unit tests. The easiest way to do this is to create the stubbed requests when initializing