given_core 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a23d03f3e0141c051c84b2b405c84ab47c15605d
-  data.tar.gz: d8ddf0ac6cf6289b042f1efbdac1c797c8a2a358
+  metadata.gz: 21590386d93b228b7693a69b72ac1a9490153176
+  data.tar.gz: 888675be1bcf66f89099f35a227e1450569e61e5
 SHA512:
-  metadata.gz: a48e5c92dcef171c12628ddc18e7daac2024e385da10a18f158caca2dbe68f45fa9b75c190732d9cbab7d8bdb2823ae22098e33c58d5e6292929b6c258fe5e8d
-  data.tar.gz: f9ed5640e35416aa45dc9f64cb60c1bf52a4c6f02334a5f0a28b781d46855f3c2ea810de6011bce1fb2efd53e5abeb2b30403bf5c468f01433442120c64ae36e
+  metadata.gz: f715fadc107ddab08ae1ed179ab2e5a8baf289fb61ee1a8fda0a7cdb59734e3b8604b08795f8d660e048624e8eb005e87668ac79d0c1f297e93ad588a311f68a
+  data.tar.gz: 3b4552e9a81535deb11e291a349dc71131189e6e6cecdb9e8b3e2407b1deda4023a2c172e8e4a298ad4d6cd404bda7d390ac8a3739a296bcc0ebc3df3eb5d1e0

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/lib/given/extensions.rb

@@ -104,7 +104,7 @@ module Given
     end
 
     # Determine of the natural assertion pass/fail status of the block
-    def _gvn_block_passed?(block)
+    def _gvn_block_passed?(block) # :nodoc:
       passed = instance_eval(&block)
       passed = passed.to_bool if passed.respond_to?(:to_bool)
       passed
@@ -247,11 +247,12 @@ module Given
     # :call-seq:
     #   Then { ... assertion ... }
     #
-    def Then(&block)
+    def Then(opts={}, &block)
+      on_eval = opts.fetch(:on_eval, "_gvn_then")
       file, line = Given.location_of(block)
       description = _Gvn_lines.line(file, line) unless Given.source_caching_disabled
       cmd = description ? "it(description)" : "specify"
-      eval %{#{cmd} do _gvn_then(&block) end}, binding, file, line
+      eval %{#{cmd} do #{on_eval}(&block) end}, binding, file, line
       _Gvn_context_info[:then_defined] = true
     end
 

data/lib/given/failure.rb

@@ -60,7 +60,8 @@ module Given
       method_symbol == :call ||
         method_symbol == :== ||
         method_symbol == :!= ||
-        method_symbol == :is_a?
+        method_symbol == :is_a? ||
+        method_symbol == :to_bool
     end
 
     private

data/lib/given/version.rb

@@ -2,7 +2,7 @@
 module Given
   VERSION_NUMBERS = [
     VERSION_MAJOR = 3,
-    VERSION_MINOR = 3,
+    VERSION_MINOR = 4,
     VERSION_BUILD = 0,
   ]
   VERSION = VERSION_NUMBERS.join(".")

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: given_core
 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: sorcerer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.3.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.3.7
 description: |
@@ -39,6 +39,8 @@ files:
 - README.md
 - Rakefile
 - TODO
+- doc/article/custom_error_messages.md
+- doc/main.rdoc
 - lib/given.rb
 - lib/given/assertions.rb
 - lib/given/binary_operation.rb
@@ -75,34 +77,33 @@ files:
 - rakelib/gemspec.rake
 - rakelib/metrics.rake
 - rakelib/preview.rake
-- 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: Core engine for RSpec::Given and Minitest::Given.