Flesh out more of the blog post.

Author: myronmarston

source/blog/2015-05-28-rspec-3-3-has-been-released.md

@@ -174,7 +174,171 @@ and want to avoid that overhead, you can configure RSpec to
 
 ### Expectations: New `aggregrate_failures` API
 
-### Expectation: Improved Failure Output
+When you've got multiple independent expectations to make about a
+particular result, you've generally got two routes you can take. One way is
+to define a separate example for each expectation:
+
+~~~ ruby
+RSpec.describe Client do
+  let(:response) { Client.make_request }
+
+  it "returns a 200 response" do
+    expect(response.status).to eq(200)
+  end
+
+  it "indicates the response body is JSON" do
+    expect(response.headers).to include("Content-Type" => "application/json")
+  end
+
+  it "returns a success message" do
+    expect(response.body).to eq('{"message":"Success"}')
+  end
+end
+~~~
+
+This follows the "one expectation per example" guideline that encourages
+you to keep each spec focused on a single facet of behavior. Alternately,
+you can put all the expectations in a single example:
+
+~~~ ruby
+RSpec.describe Client do
+  it "returns a successful JSON response" do
+    response = Client.make_request
+
+    expect(response.status).to eq(200)
+    expect(response.headers).to include("Content-Type" => "application/json")
+    expect(response.body).to eq('{"message":"Success"}')
+  end
+end
+~~~
+
+This latter approach is going to be faster, as the request is only made once
+rather than three times. However, if the status code is not a 200, the example
+will abort on the first expectation and you won't be able to see whether or not
+the latter two expectations passed or not.
+
+RSpec 3.3 has a new feature that helps when, for speed or other reasons, you
+want to put multiple expectations in a single example. Simply wrap your
+expectations in an `aggregate_failures` block:
+
+~~~ ruby
+RSpec.describe Client do
+  it "returns a successful JSON response" do
+    response = Client.make_request
+
+    aggregate_failures "testing response" do
+      expect(response.status).to eq(200)
+      expect(response.headers).to include("Content-Type" => "application/json")
+      expect(response.body).to eq('{"message":"Success"}')
+    end
+  end
+end
+~~~
+
+Within the `aggregate_failures` block, expectations do not cause the
+example to abort. Instead, a single _aggregate_ exception will be
+raised at the end containing multiple sub-failures which RSpec will
+format nicely for you:
+
+~~~
+1) Client returns a successful response
+   Got 3 failures from failure aggregation block "testing reponse".
+   # ./spec/client_spec.rb:5
+
+   1.1) Failure/Error: expect(response.status).to eq(200)
+
+          expected: 200
+               got: 404
+
+          (compared using ==)
+        # ./spec/client_spec.rb:6
+
+   1.2) Failure/Error: expect(response.headers).to include("Content-Type" => "application/json")
+          expected {"Content-Type" => "text/plain"} to include {"Content-Type" => "application/json"}
+          Diff:
+          @@ -1,2 +1,2 @@
+          -[{"Content-Type"=>"application/json"}]
+          +"Content-Type" => "text/plain",
+        # ./spec/client_spec.rb:7
+
+   1.3) Failure/Error: expect(response.body).to eq('{"message":"Success"}')
+
+          expected: "{\"message\":\"Success\"}"
+               got: "Not Found"
+
+          (compared using ==)
+        # ./spec/client_spec.rb:8
+~~~
+
+`RSpec::Core` provides improved support for this feature through the use of
+metadata. Instead of wrapping the expectations with `aggregate_failures`,
+simply tag the example or group with `:aggregate_failures`:
+
+~~~ ruby
+RSpec.describe Client, :aggregate_failures do
+  it "returns a successful JSON response" do
+    response = Client.make_request
+
+    expect(response.status).to eq(200)
+    expect(response.headers).to include("Content-Type" => "application/json")
+    expect(response.body).to eq('{"message":"Success"}')
+  end
+end
+~~~
+
+If you want to enable this feature everywhere, you can use [`define_derived_metadata`](TODO):
+
+~~~ ruby
+RSpec.configure do |c|
+  c.define_derived_metadata do |meta|
+    meta[:aggregate_failures] = true
+  end
+end
+~~~
+
+Of course, you may not want this enabled everywhere. When you've got _dependent_ expectations
+(e.g. where an expectation only makes sense if the prior expectation passed), or if you're
+using expectations to express a pre-condition, you'll probably want the example to immediately abort
+when the expectation fails.
+
+### Expectations: Improved Failure Output
+
+RSpec 3.3 includes improved failure messages across the board for all matchers.
+Test doubles now look prettier in our failure messages:
+
+~~~
+Failure/Error: expect([foo]).to include(bar)
+  expected [#<Double "Foo">] to include #<Double "Bar">
+  Diff:
+  @@ -1,2 +1,2 @@
+  -[#<Double "Bar">]
+  +[#<Double "Foo">]
+~~~
+
+In addition, RSpec's improved formatting for `Time` and other objects will
+now be used wherever those objects are inspected for every matcher. So, for
+example, where you used to get this:
+
+~~~
+Failure/Error: expect([Time.now]).to include(Time.now)
+  expected [2015-06-09 07:48:06 -0700] to include 2015-06-09 07:48:06 -0700
+~~~
+
+...you'll now get this instead:
+
+~~~
+Failure/Error: expect([Time.now]).to include(Time.now)
+  expected [2015-06-09 07:49:16.610635000 -0700] to include 2015-06-09 07:49:16.610644000 -0700
+  Diff:
+  @@ -1,2 +1,2 @@
+  -[2015-06-09 07:49:16.610644000 -0700]
+  +[2015-06-09 07:49:16.610635000 -0700]
+~~~
+
+...which makes it much clearer that the time objects differ at the level of milliseconds.
+
+Thanks to Gavin Miller, Nicholas Chmielewski and Siva Gollapalli for contributing to
+these improvements!
 
 ### Mocks: Improved Failure Output