port changes from #1000 (#1004)

.rubocop.yml

@@ -11,14 +11,17 @@ AllCops:
 Metrics/BlockLength:
   Exclude:
     - spec/**/*.rb
+    - examples/**/*.rb
 
 Metrics/LineLength:
   Exclude:
     - spec/**/*.rb
+    - examples/**/*.rb
 
 Style/DoubleNegation:
   Enabled: false
 
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
+    - 'examples/**/*'

docs/adapters/testing.md

@@ -19,13 +19,22 @@ response body.
 ```ruby
 conn = Faraday.new do |builder|
   builder.adapter :test do |stub|
+    # block returns an array with 3 items:
+    # - Integer response status
+    # - Hash HTTP headers
+    # - String response body
     stub.get('/ebi') do |env|
       [
         200,
         { 'Content-Type': 'text/plain', },
         'shrimp'
       ]
     end
+
+    # test exceptions too
+    stub.get('/boom') do
+      raise Faraday::ConnectionFailed, nil
+    end
   end
 end
 ```
@@ -62,3 +71,11 @@ verify the order or count of any stub.
 ```ruby
 stubs.verify_stubbed_calls
 ```
+
+## Examples
+
+Working [RSpec] and [test/unit] examples for a fictional JSON API client are
+available.
+
+[RSpec]: https://github.com/lostisland/faraday/blob/master/examples/client_spec.rb
+[test/unit]: https://github.com/lostisland/faraday/blob/master/examples/client_test.rb

examples/client_spec.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Requires Ruby with rspec and faraday gems.
+# rspec client_spec.rb
+
+require 'faraday'
+require 'json'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def sushi(jname)
+    res = @conn.get("/#{jname}")
+    data = JSON.parse(res.body)
+    data['name']
+  end
+end
+
+Rspec.describe Client do
+  let(:stubs)  { Faraday::Adapter::Test::Stubs.new }
+  let(:conn)   { Faraday.new { |b| b.adapter(:test, stubs) } }
+  let(:client) { Client.new(conn) }
+
+  it 'parses name' do
+    stubs.get('/ebi') do |env|
+      # optional: you can inspect the Faraday::Env
+      expect(env.url.path).to eq('/ebi')
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    expect(client.sushi('ebi')).to eq('shrimp')
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles 404' do
+    stubs.get('/ebi') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+    expect(client.sushi('ebi')).to be_nil
+    stubs.verify_stubbed_calls
+  end
+
+  it 'handles exception' do
+    stubs.get('/ebi') do
+      raise Faraday::ConnectionFailed, nil
+    end
+
+    expect { client.sushi('ebi') }.to raise_error(Faraday::ConnectionFailed)
+    stubs.verify_stubbed_calls
+  end
+end

examples/client_test.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Requires Ruby with test-unit and faraday gems.
+# ruby client_test.rb
+
+require 'faraday'
+require 'json'
+require 'test/unit'
+
+# Example API client
+class Client
+  def initialize(conn)
+    @conn = conn
+  end
+
+  def sushi(jname)
+    res = @conn.get("/#{jname}")
+    data = JSON.parse(res.body)
+    data['name']
+  end
+end
+
+# Example API client test
+class ClientTest < Test::Unit::TestCase
+  def test_sushi_name
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do |env|
+      # optional: you can inspect the Faraday::Env
+      assert_equal '/ebi', env.url.path
+      [
+        200,
+        { 'Content-Type': 'application/javascript' },
+        '{"name": "shrimp"}'
+      ]
+    end
+
+    # uncomment to trigger stubs.verify_stubbed_calls failure
+    # stubs.get('/unused') { [404, {}, ''] }
+
+    cli = client(stubs)
+    assert_equal 'shrimp', cli.sushi('ebi')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_sushi_404
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do
+      [
+        404,
+        { 'Content-Type': 'application/javascript' },
+        '{}'
+      ]
+    end
+
+    cli = client(stubs)
+    assert_nil cli.sushi('ebi')
+    stubs.verify_stubbed_calls
+  end
+
+  def test_sushi_exception
+    stubs = Faraday::Adapter::Test::Stubs.new
+    stubs.get('/ebi') do
+      raise Faraday::ConnectionFailed, nil
+    end
+
+    cli = client(stubs)
+    assert_raise Faraday::ConnectionFailed do
+      cli.sushi('ebi')
+    end
+    stubs.verify_stubbed_calls
+  end
+
+  def client(stubs)
+    conn = Faraday.new do |builder|
+      builder.adapter :test, stubs
+    end
+    Client.new(conn)
+  end
+end