rspec-given 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f6b65b46cef2fc751535568e6bd4b49bab117ad
-  data.tar.gz: 87338960a579e6e2b881c4438954733703801322
+  metadata.gz: 28324282e7dae4f8e019d59cc094b90e43e2c2bb
+  data.tar.gz: 12422b6076ce08f5c257d5da088a4753c6e6bc2f
 SHA512:
-  metadata.gz: 2188ecabba52de943bfaff4ff22ead2808a41402b9d2d807c1afdc19c5955e53794891eff19c2f904dca4a7d220d6730b104021133f39c3fc95604262755a0b2
-  data.tar.gz: c2b4b93337146df65592f25002cb96ce3537dc2e804b6a2cd76f81076c3b2ec126809cb6d93b9653f6b9891e745de9ff8fd9ca7ab04b915ca333a4d0c3bd8b40
+  metadata.gz: 931a00a40a178c7a35b6231aee226139225b6f82d4198a81ded2f0e52086d355fa5cf78f1acb18f427bcc7eced5d5a57dfa03dac5107177cf438366658c022ea
+  data.tar.gz: d0021d7b45dab9bf98381f992acfb6bafe6237e71d3dc8237c1e0071a08d0b438d0874321cefb2e3a73d365a864129f08fde414efc8a86649d562fa146a4e876

data/README.md

@@ -4,7 +4,7 @@
 | :----: |
 | [![Master Build Status](https://secure.travis-ci.org/jimweirich/rspec-given.png?branch=master)](https://travis-ci.org/jimweirich/rspec-given) |
 
-Covering rspec-given, minitest-given, and given-core, version 3.3.0.beta21.
+Covering rspec-given, minitest-given, and given-core, version 3.4.0.
 
 rspec-given and minitest-given are extensions to your favorite testing
 framework to allow Given/When/Then notation when writing specs.
@@ -866,6 +866,11 @@ License. See the MIT-LICENSE file in the source distribution.
 
 # History
 
+* Version 3.4.0
+
+  * Bare failure objects in Then clauses will now propagate their
+    captured failure (added <code>to_bool</code> to failure object).
+
 * Version 3.3.0
 
   * Add support for <code>to_bool</code>.

data/Rakefile

@@ -42,7 +42,7 @@ task :tag do
 end
 
 desc "Publish the gems"
-task :publish => [:clobber, :gem] do
+task :publish_gems => [:clobber, :gem] do
   FileList['pkg/*.gem'].each do |gemname|
     sh "gem push #{gemname}"
   end

data/doc/article/custom_error_messages.md

@@ -0,0 +1,282 @@
+## Beautiful Failure Messages
+
+The RSpec/Given library is an extension to the RSpec testing framework
+that explicitly supports a Given/When/Then style for testing.  It has
+two goals:
+
+* Encourage specification language when writing tests
+* Allow beautiful failure messages without writing custom matchers
+
+RSpec/Given has a been very successful in both these goals. Consider
+the following spec snippet for a Page object in a Wiki Rails
+application:
+
+```ruby
+describe "content conversion to HTML" do
+  Given(:page) {
+    Page.new(
+      name: "HomePage",
+      content: "Have a _nice_ day.")
+  }
+  Then { page.html_content == "Have a <em>nice</em> day." }
+end
+```
+
+Assuming that the <code>html_content</code> method is incomplete and
+not yet marking emphasized text, the failure message from the
+specification will be:
+
+    1) Page content conversion to HTML
+       Failure/Error: Then { page.html_content == "Have a <em>nice</em> day." }
+         Then expression failed at .../spec/models/page_spec.rb:38
+         expected: "Have a _nice_ day."
+         to equal: "Have a <em>nice</em> day."
+           false   <- page.html_content == "Have a <em>nice</em> day."
+           "Have a _nice_ day."
+                    <- page.html_content
+           #<Page name: "HomePage", content: "Have a _nice_ day." ...>
+                   <- page
+       # ./spec/models/page_spec.rb:38:in `block in Then'
+
+Let's break that down:
+
+**It says what failed:**
+
+    Failure/Error: Then { page.html_content == "Have a <em>nice</em> day." }
+
+**It says where it failed:**
+
+    Then expression failed at .../spec/models/page_spec.rb:38
+
+**It says what was expected:**
+
+    expected: "Have a _nice_ day."
+    to equal: "Have a <em>nice</em> day."
+
+**It then breaks down each subexpression and displays its value:**
+
+    false   <- page.html_content == "Have a <em>nice</em> day."
+    "Have a _nice_ day."
+            <- page.html_content
+    #<Page name: "HomePage", content: "Have a _nice_ day." ...>
+            <- page
+
+All of this happens without the developer needing to write any special
+error matchers or custom output.  Everything you need to debug a spec
+failure is there in the output.
+
+## A More Complex Example
+
+Let's look at a more complex example.  Suppose we want to test
+validations in the Page object.  For example, we might want to make
+sure that:
+
+* The page has a name
+* The name conforms to the standard wiki naming convention (i.e. WikiName).
+
+Here's the beginning of that specification:
+
+```ruby
+describe Page do
+  VALID_ATTRS = { name: "SomePage", content: "CONTENT" }
+  Given(:attrs) { VALID_ATTRS }
+  Given(:page) { Page.new(attrs) }
+
+...
+end
+```
+
+<code>VALID\_ATTRS</code> is a list of attributes that will construct a
+valid page object.  Normally I would put <code>VALID\_ATTRS</code> in something like
+Factory Girl, but a simple constant is good enough this example.
+
+I then declare a given that <code>attrs</code> is the valid
+attributes, and that <code>Page</code> is constructed from these valid
+attributes.
+
+I can now describe a valid page object.
+
+```ruby
+  context "with valid attributes" do
+    Then { page.valid? }
+  end
+```
+
+To describe a validation failure where the name is missing, I create a
+context where I override the default <code>attrs</code> with a version
+that omits the name.
+
+```ruby
+context "with missing name" do
+  Given(:attrs) { VALID_ATTRS.merge(name: nil) }
+  Then { page.invalid? }
+  And  { ! page.errors[:name].empty? }
+  And  { page.errors[:name].any? { |msg| msg =~ /blank/ } }
+end
+```
+
+Why Then/And/And? Because there are three things that should be true
+if a validation fails.
+
+1. The object must not be valid
+2. The field that has the error must have error messages
+3. At least one of the error messages should mention the word 'blank'
+
+Suppose the Page object has a validation on name, but doesn't check
+for presence.  The failure message clearly tells you that the spec
+failed because no error messages on the <code>name</code> field
+mentioned 'blank'.
+
+    1) Page validations with missing name
+       Failure/Error: Then { page.invalid? }
+         And expression failed at ./spec/models/page_spec.rb:27
+         Failing expression: And  { page.errors[:name].any? { |msg| msg =~ /blank/ } }
+           false   <- page.errors[:name].any? { |msg| msg =~ /blank/ }
+           ["is not a wiki name"]
+                   <- page.errors[:name]
+           #<ActiveModel::Errors:... @messages={:name=>["is not a wiki name"]}>
+                   <- page.errors
+           #<Page name: nil, content: "CONTENT", ...>
+                   <- page
+       # ./spec/models/page_spec.rb:25:in `block in Then'
+
+We get informative error messages, which is exactly what we want.
+
+However, the spec itself is a little wordy, with repeating
+Then/And/And.  What if we wrote a simple query function that checked
+for the three conditions and reported true/false accordingly.
+
+```ruby
+def invalid?(page, field, pattern)
+  page.invalid? &&
+    ! page.errors[field].empty? &&
+    page.errors[field].any? { |msg| msg =~ pattern }
+end
+```
+
+Now we can use <code>invalid?</code> in all our validations
+specifications:
+
+```ruby
+context "with missing name" do
+  Given(:attrs) { VALID_ATTRS.merge(name: nil) }
+  Then { invalid?(page, :name, /blank/) }
+end
+```
+
+But there is a downside.  Because <code>invalid?</code> only returns
+true/false, and there are no mention of the <code>errors</code> object
+in the Then clause, the failure message is really uninformative:
+
+    1) Page validations with missing name
+       Failure/Error: Then { invalid_on(page, :name, /blank/) }
+         Then expression failed at ./spec/models/page_spec.rb:31
+           false   <- invalid_on(page, :name, /blank/)
+           #<Page name: nil, content: "CONTENT", ...>
+                   <- page
+       # ./spec/models/page_spec.rb:31:in `block in Then'
+
+All we know is that the page is invalid.  We get no indication of what
+fields were actually in error and what the error messages actually
+were.
+
+## Custom Failure Message
+
+By abstracting away the details how to check for invalid models (which
+is generally a good thing), RSpec/Given lost the ability to give us
+the details of why it failed.
+
+Fortunately, there is a simple fix.  Instead of returning a simple
+true/false value, the <code>invalid?</code> method should return an
+object, that when inspected, tells why it failed.
+
+If a _Then_ clause returns a value that supports a
+<code>to_bool</code> method, then RSpec/Given will call that method
+before checking for true/false (in rspec-given 3.3.0 or later). All we
+need to do is arrange for that object to be returned.
+
+```ruby
+  def must_be_invalid(model, field, pattern=//)
+    MustBeInvalid.new(model, field, pattern)
+  end
+```
+
+Since the method no longer returns a true/false value, I've changed
+the name from <code>invalid?</code> to <code>must\_be\_invalid</code>.
+
+The code for the <code>MustBeInvalid</code> class is a bit long, but
+there is nothing complex in it. The <code>to_bool</code> method
+carefully checks for each of our three conditions and records the
+exact reason for failure in the @why instance variable. The
+<code>inspect</code> method (called by RSpec/Given to display its
+value) just returns the @why value with additional details about the
+errors on the object.
+
+```ruby
+class MustBeInvalid
+  def initialize(model, field, pattern)
+    @model = model
+    @field = field
+    @pattern = pattern
+    @why = nil
+  end
+
+  def to_bool
+    if @model.valid?
+      @why = "#{@model.class} was valid (expected invalid)"
+      false
+    elsif @model.errors[@field].empty?
+      @why = "#{@model.class} had no errors on field #{@field}" +
+             error_descriptions
+      false
+    elsif @model.errors[@field].none? { |msg| msg =~ @pattern }
+      @why = "#{@model.class} had no errors " +
+             "matching #{@pattern} on field #{@field}" +
+             error_descriptions
+      false
+    else
+      @why = "OK (expected invalid)"
+      true
+    end
+  end
+
+  def inspect
+    to_bool if @why.nil?
+    @why
+  end
+
+  private
+
+  def error_descriptions
+    if @model.errors.empty?
+      ""
+    else
+      "\n  Errors were:\n    * " +
+        @model.errors.full_messages.
+          map { |msg| msg }.join("\n    * ")
+    end
+  end
+end
+```
+
+The failure message returned by <code>MustBeInvalid</code> is once
+again clear and to the point.  It contains all the information needed
+for debugging.
+
+    1) Page validations with missing name
+       Failure/Error: Then { must_be_invalid(page, :name, /blank/) }
+         Then expression failed at ./spec/models/page_spec.rb:31
+           Page had no errors matching (?-mix:blank) on field name
+             Errors were:
+               * Name is not a wiki name
+                        <- must_be_invalid(page, :name, /blank/)
+           #<Page name: nil, content: "CONTENT", ...>
+                        <- page
+       # ./spec/models/page_spec.rb:31:in `block in Then'
+
+## Summary
+
+I've always felt that you can tell the maturity level of a piece of
+software by the beauty of the error messages it produces.  By
+providing the ability to do custom messages where needed, RSpec/Given
+takes a step in that direction.

data/spec/lib/given/failing_thens_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe "Failing Then clauses" do
+
+  # NOTE: FAIL and ERROR are special versions of the Then clause that
+  # expect failures and errors. These are used only in the framework
+  # testing and are not generally available.
+
+  context "with false" do
+    FAIL { false }
+  end
+
+  context "with exception comparison in when result" do
+    When(:result) { fail "explicitly" }
+    ERROR { result == 1 }
+  end
+
+  context "with bare exception in when result" do
+    When(:result) { fail "explicitly" }
+    ERROR { result }
+  end
+
+end

data/spec/support/failure_and_errors.rb

@@ -0,0 +1,31 @@
+require 'rspec/given'
+
+# These extensions are used for framework testing, where failing a
+# Then block is a passing condition.
+module Given
+  module InstanceExtensions
+    NotMetError = RSpec::Expectations::ExpectationNotMetError
+
+    def _gvn_fail(&block)
+      expect { _gvn_then(&block) }.to raise_error(NotMetError)
+    end
+
+    def _gvn_error(&block)
+      expect { _gvn_then(&block) }.to raise_error(StandardError)
+    end
+  end
+
+  module ClassExtensions
+
+    # Fails spec if block passes.
+    def FAIL(&block)
+      Then(on_eval: "_gvn_fail", &block)
+    end
+
+    # Fails spec if block does not raise some kind of error.
+    def ERROR(&block)
+      Then(on_eval: "_gvn_error", &block)
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-given
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Jim Weirich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-20 00:00:00.000000000 Z
+date: 2013-12-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: given_core
@@ -16,26 +16,26 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.3.0
+        version: 3.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.3.0
+        version: 3.4.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.12'
 description: |
@@ -52,6 +52,29 @@ files:
 - README.md
 - Rakefile
 - TODO
+- doc/article/custom_error_messages.md
+- doc/main.rdoc
+- examples/example_helper.rb
+- examples/failing/natural_failing_spec.rb
+- examples/failing/sample_spec.rb
+- examples/integration/and_spec.rb
+- examples/integration/failing/eval_subexpression_spec.rb
+- examples/integration/failing/module_nesting_spec.rb
+- examples/integration/failing/to_bool_returns_false.rb
+- examples/integration/failing/undefined_method_spec.rb
+- examples/integration/failing_messages_spec.rb
+- examples/integration/focused_line_spec.rb
+- examples/integration/given_spec.rb
+- examples/integration/invariant_spec.rb
+- examples/integration/then_spec.rb
+- examples/loader.rb
+- examples/minitest/assert_raises_spec.rb
+- examples/minitest_helper.rb
+- examples/other/line_example.rb
+- examples/stack/stack.rb
+- examples/stack/stack_spec.rb
+- examples/stack/stack_spec1.rb
+- examples/use_assertions.rb
 - lib/given.rb
 - lib/rspec-given.rb
 - lib/rspec/given.rb
@@ -65,6 +88,7 @@ files:
 - spec/lib/given/ext/numeric_spec.rb
 - spec/lib/given/ext/numeric_specifications.rb
 - spec/lib/given/extensions_spec.rb
+- spec/lib/given/failing_thens_spec.rb
 - spec/lib/given/failure_matcher_spec.rb
 - spec/lib/given/failure_spec.rb
 - spec/lib/given/file_cache_spec.rb
@@ -77,57 +101,36 @@ files:
 - spec/lib/given/options_spec.rb
 - spec/spec_helper.rb
 - spec/support/be_booleany.rb
+- spec/support/failure_and_errors.rb
 - spec/support/faux_then.rb
 - spec/support/natural_assertion_control.rb
-- examples/example_helper.rb
-- examples/failing/natural_failing_spec.rb
-- examples/failing/sample_spec.rb
-- examples/integration/and_spec.rb
-- examples/integration/failing/eval_subexpression_spec.rb
-- examples/integration/failing/module_nesting_spec.rb
-- examples/integration/failing/to_bool_returns_false.rb
-- examples/integration/failing/undefined_method_spec.rb
-- examples/integration/failing_messages_spec.rb
-- examples/integration/focused_line_spec.rb
-- examples/integration/given_spec.rb
-- examples/integration/invariant_spec.rb
-- examples/integration/then_spec.rb
-- examples/loader.rb
-- examples/minitest/assert_raises_spec.rb
-- examples/minitest_helper.rb
-- examples/other/line_example.rb
-- examples/stack/stack.rb
-- examples/stack/stack_spec.rb
-- examples/stack/stack_spec1.rb
-- examples/use_assertions.rb
-- doc/main.rdoc
 homepage: http://github.com/jimweirich/rspec-given
 licenses:
 - MIT
 metadata: {}
 post_install_message: 
 rdoc_options:
-- --line-numbers
-- --inline-source
-- --main
+- "--line-numbers"
+- "--inline-source"
+- "--main"
 - doc/main.rdoc
-- --title
+- "--title"
 - RSpec Given Extensions
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: given
-rubygems_version: 2.1.11
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Given/When/Then Specification Extensions for RSpec.