minitest-given 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f6ac78ebf0dcbd97a1c4507f2a003f6ec9003b3
-  data.tar.gz: 5e7fcbba3bc694a5ac78cce67eb5f3454d52dfee
+  metadata.gz: c3769f9d39bd6466f993687a0f3df8c169b27118
+  data.tar.gz: b041cd8182ff4ac8044e2eedc914a0196a87066f
 SHA512:
-  metadata.gz: 06b7d59ef0798b8d6283bdd0645e8fbde93b09f86bafbd21d04b6e67e540a7ff0a7b32cd4655a8e38687a14e573b629a5e3dcda7be31b1d7bfc1e6236a3095a7
-  data.tar.gz: 27f9034b05e5bdf0e7904f2a93d809cf1f189017068fa61b0b8bdf915ad2ebb2ec9285ea0cea6ceedb3e714a902726f081a48fabfdf45320b74225526b883e6b
+  metadata.gz: bcce0e56e74705ad54cbee6edef23fd17fb9241ee2cb87efd047d043c2231231fa1ffebe756a62489dd35c1ccd8ff14b1e67004967bd6b72e429ffa12a19fb07
+  data.tar.gz: 1f6a19b866f2c00fa3016bdaec94d227ee23a27e6bf88bbd5ee867e61ed5f0e371b81fc178504ca677ab412c0a6c49f05a92da92ed01c95272c64e415eb62f45

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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minitest-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: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>'
+    - - ">"
       - !ruby/object:Gem::Version
         version: '4.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>'
+    - - ">"
       - !ruby/object:Gem::Version
         version: '4.3'
 description: |
@@ -52,13 +52,8 @@ files:
 - README.md
 - Rakefile
 - TODO
-- lib/given.rb
-- lib/minitest-given.rb
-- lib/minitest/given.rb
-- rakelib/bundler_fix.rb
-- rakelib/gemspec.rake
-- rakelib/metrics.rake
-- rakelib/preview.rake
+- doc/article/custom_error_messages.md
+- doc/main.rdoc
 - examples/example_helper.rb
 - examples/failing/natural_failing_spec.rb
 - examples/failing/sample_spec.rb
@@ -80,34 +75,40 @@ files:
 - examples/stack/stack_spec.rb
 - examples/stack/stack_spec1.rb
 - examples/use_assertions.rb
-- doc/main.rdoc
+- lib/given.rb
+- lib/minitest-given.rb
+- lib/minitest/given.rb
+- rakelib/bundler_fix.rb
+- rakelib/gemspec.rake
+- rakelib/metrics.rake
+- rakelib/preview.rake
 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"
 - Minitest::Spec 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 Minitest::Spec.