spectus 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e08a0c9d455c7e57dc73d412e7f1a1c6a470b954
-  data.tar.gz: 19554aba37f38c6227b199498bb5b99df33a9896
+  metadata.gz: 5af3530d553018e8e3edb227a935720e3d059710
+  data.tar.gz: ba087a69cc7fdb7fa34b77f9533c613dfe212b1d
 SHA512:
-  metadata.gz: 3c514e5429e220d6f8dd0954d7a6779951efb876d6cf0565ee4042f77618f2ef5127b6f2232de254f1133099393c53e4879611f41903d7ba6059ff601474dfcb
-  data.tar.gz: 013b5b2aeb1507c74ba3fb4ec942cb56fde0a3ede1c3acc4d16027292991fc99dedf92ba7290f701737488e6728f15a795936415ea1677661edef32343a5fbe5
+  metadata.gz: 1e87dc18064518c251a502e63a719e8f8ae4e5646c1e9dfd2ebb468ba1188eda8a8e2a3418d61e3d430b94a6f8cd68754b72a7b291cca4294394cf7c4f893ae6
+  data.tar.gz: 5416775288db9e161101a4759e8aaad4ae600809ca90db34b5213303aa8c247f1b59a7fef1c7c83372295c5f64d1586c9142cf8a50d4d9aaafce344b007a0428

data/README.md

@@ -30,6 +30,16 @@ To be sure the gem you install hasn't been tampered with, add my public key (if
 
 The `HighSecurity` trust profile will verify all gems.  All of __Spectus__'s dependencies are signed.
 
+Or add this line to your application's Gemfile:
+
+```ruby
+gem 'spectus'
+```
+
+And then execute:
+
+    $ bundle
+
 ## Expectation
 
 An expectation is an assertion that is either `true` or `false`.
@@ -58,7 +68,7 @@ Given the `"ルビー"` object, when it receives `valid_encoding?` method, then
 
 ```ruby
 Spectus.this { 'ルビー'.valid_encoding? }.MUST :BeTrue
-# => #<Spectus::Result::Pass:0x007fbbc12b9fd8 @subject=#<Proc:0x007fbbc12ba410@(irb):1>, @challenge=:call, @context=[], @actual=true, @expected=:BeTrue, @got=true, @error=nil, @level=:High, @negate=false, @valid=true>
+# => #<Spectus::Result::Pass:0x007f9329c45090 @message="Pass: Expected true to be true.", @subject=#<Proc:0x007f9329c45d60@(irb):1>, @challenge=:call, @context=[], @actual=true, @expected=:BeTrue, @got=true, @error=nil, @level=:High, @negate=false, @valid=true>
 ```
 
 The result of the test shows that the spec passed.
@@ -69,7 +79,7 @@ Given the `"foo"` object, when it receives `length` method, then it **MUST NOT**
 
 ```ruby
 Spectus.this { 'foo'.length }.MUST_NOT RaiseException: NoMethodError
-# => #<Spectus::Result::Pass:0x007fbbc12a8e90 @subject=#<Proc:0x007fbbc12a95e8@(irb):2>, @challenge=:call, @context=[], @actual=3, @expected={:RaiseException=>NoMethodError}, @got=true, @error=nil, @level=:High, @negate=true, @valid=true>
+# => #<Spectus::Result::Pass:0x007f9329c341f0 @message="Pass: Expected 3 not to raise exception NoMethodError.", @subject=#<Proc:0x007f9329c34da8@(irb):2>, @challenge=:call, @context=[], @actual=3, @expected={:RaiseException=>NoMethodError}, @got=true, @error=nil, @level=:High, @negate=true, @valid=true>
 ```
 
 The result of the test shows that the spec passed.
@@ -80,7 +90,7 @@ Given the `BasicObject` object, when it receives `superclass` method, then it **
 
 ```ruby
 Spectus.this { BasicObject.superclass }.SHOULD Equal: NilClass
-# => #<Spectus::Result::Pass:0x007fbbc1291ec0 @subject=#<Proc:0x007fbbc12923e8@(irb):3>, @challenge=:call, @context=[], @actual=nil, @expected={:Equal=>NilClass}, @got=false, @error=nil, @level=:Medium, @negate=false, @valid=false>
+# => #<Spectus::Result::Pass:0x007f9329c1def0 @message="Info: Expected nil to equal NilClass.", @subject=#<Proc:0x007f9329c1e990@(irb):3>, @challenge=:call, @context=[], @actual=nil, @expected={:Equal=>NilClass}, @got=false, @error=nil, @level=:Medium, @negate=false, @valid=false>
 ```
 
 Instead of the expected `NilClass` class, its sole instance (which is `nil`) was returned.
@@ -92,7 +102,9 @@ Given the `"1"` object, when it receives `+(1)` method, then it **SHOULD NOT** r
 
 ```ruby
 Spectus.this { '1' + 1 }.SHOULD_NOT Eql: '11'
-# => raise #<Spectus::Result::Fail: failing spec> exception
+# Spectus::Result::Fail: Error: no implicit conversion of Fixnum into String (TypeError).
+# 	from (irb):4
+# 	from ./bin/console:7:in `<main>'
 ```
 
 There was a `TypeError` exception, the result of the test shows that the spec failed.
@@ -103,7 +115,7 @@ Given the `"foo"` object, when it receives `blank?` method, then it **MAY** be `
 
 ```ruby
 Spectus.this { 'foo'.blank? }.MAY :BeFalse
-# => #<Spectus::Result::Pass:0x007fbbc1b7c238 @subject=#<Proc:0x007fbbc1b7c698@(irb):5>, @challenge=:call, @context=[], @actual=nil, @expected=:BeFalse, @got=nil, @error=#<NoMethodError: undefined method `blank?' for "foo":String>, @level=:Low, @negate=false, @valid=false>
+# => #<Spectus::Result::Pass:0x007f932b91feb8 @message="Info: undefined method `blank?' for \"foo\":String (NoMethodError).", @subject=#<Proc:0x007f9329bfc5e8@(irb):5>, @challenge=:call, @context=[], @actual=nil, @expected=:BeFalse, @got=nil, @error=#<NoMethodError: undefined method `blank?' for "foo":String>, @level=:Low, @negate=false, @valid=false>
 ```
 
 The optional `blank?` method is not implemented (unlike in [Ruby on Rails](http://api.rubyonrails.org/classes/Object.html#method-i-blank-3F), for instance), so the result of the test shows that the spec passed.
@@ -118,8 +130,8 @@ built Gem they can be used for basic integrity verification purposes.
 The checksum of a file can be checked using the `sha512sum` command.  For
 example:
 
-    $ sha512sum pkg/spectus-2.0.0.gem
-    e00ef19cbae209816410c1b0e4b032a59ba70ab2e43367c934ad723d3e23a9c50c457c0963fab7d46743d82ab21f9482dbd8ceb7cab23617e37be26823d846cd  pkg/spectus-2.0.0.gem
+    $ sha512sum pkg/spectus-2.3.0.gem
+    d12d7d9c2a4fdfe075cbb7a141fa5f2195175891e4098c7e1a28c8bca655ab44fb9d67b6a2e3991d0f852026c5e4537fdf7e314575c68d1c80b3a4b1eb1c041f  pkg/spectus-2.3.0.gem
 
 ## Versioning
 

data/VERSION.semver

@@ -1 +1 @@
-2.2.0
+2.3.0

data/checksum/spectus-2.3.0.gem.sha512

@@ -0,0 +1 @@
+0bf8cbdb18e983b524e5857af066f4d948ea6e2d70b2cb97d56cb37f5ccf8a33931f3e9786097f1aea6183be01106d6e3d40a97f1fbf58dfaf89eb9f01cab260

data/lib/spectus/challenge.rb

@@ -1,10 +1,10 @@
 module Spectus
-  # This class evaluate the expectation with the passed block.
+  # This class contains a challenge to apply against an object.
   #
-  # @api private
+  # @api public
   #
   class Challenge
-    # A Query to the subject.
+    # Initialize the challenge class.
     #
     # @param [#to_sym] method_id the identifier of a method.
     # @param [Array] args the arguments of the method.
@@ -13,10 +13,14 @@ module Spectus
       @args   = args
     end
 
-    # @return [Symbol] the method to call on the subject.
+    # @!attribute [r] symbol
+    #
+    # @return [Symbol] The method to call on the subject.
     attr_reader :symbol
 
-    # @return [Array] the parameters following the method.
+    # @!attribute [r] args
+    #
+    # @return [Array] The parameters following the method.
     attr_reader :args
   end
 end

data/lib/spectus/expectation_target.rb

@@ -17,10 +17,14 @@ module Spectus
       @challenge  = Challenge.new(:call)
     end
 
-    # @return [BasicObject] the front object to be tested.
+    # @!attribute [r] subject
+    #
+    # @return [BasicObject] The front object to be tested.
     attr_reader :subject
 
-    # @return [Challenge] the challenge to call on the subject.
+    # @!attribute [r] challenge
+    #
+    # @return [Challenge] The challenge to call on the subject.
     attr_reader :challenge
 
     # This word, or the terms "REQUIRED" or "SHALL", mean that the

data/lib/spectus/level/base.rb

@@ -3,11 +3,13 @@ require_relative File.join '..', 'result', 'fail'
 require_relative File.join '..', 'result', 'pass'
 
 module Spectus
+  # Namespace for the requirement levels.
+  #
+  # @api private
+  #
   module RequirementLevel
     # Requirement level's base class.
     #
-    # @api private
-    #
     class Base
       # Initialize the requirement level class.
       #
@@ -29,14 +31,15 @@ module Spectus
       #
       # @return [Result::Pass] pass the spec.
       def pass!(state)
-        Result::Pass.new(*result_signature(state))
+        Result::Pass.new(message(state, true), *result_signature(state))
       end
 
       # @param state [Sandbox] The sandbox that tested the code.
       #
       # @raise [Result::Fail] fail the spec.
       def fail!(state)
-        fail Result::Fail.new(*result_signature(state)), 'failing spec'
+        fail Result::Fail.new(message(state, false), *result_signature(state)),
+             message(state, false), caller[2..-1]
       end
 
       # @param state [Sandbox] The sandbox that tested the code.
@@ -67,6 +70,70 @@ module Spectus
         Sandbox.new(@definition, @negate, @subject, @challenge.symbol,
                     *@challenge.args)
       end
+
+      # @param state  [Sandbox] The sandbox that tested the code.
+      # @param result [Boolean] The result of the test.
+      #
+      # @return [String] the message that describe the state.
+      def message(state, result)
+        "#{title(state, result)}: #{summary(state)}."
+      end
+
+      # The title of the state.
+      #
+      # @param state [Sandbox] The sandbox that tested the code.
+      # @param result [Boolean] The result of the test.
+      #
+      # @return [String] the title of the state.
+      def title(state, result)
+        if result
+          if state.got
+            'Pass'
+          else
+            'Info'
+          end
+        else
+          if state.exception.nil?
+            'Failure'
+          else
+            'Error'
+          end
+        end
+      end
+
+      # The summary of the state.
+      #
+      # @param state [Sandbox] The sandbox that tested the code.
+      #
+      # @return [String] the summary of the state.
+      def summary(state)
+        if state.valid? || state.exception.nil?
+          'Expected ' + state.actual.inspect + (@negate ? ' not ' : ' ') +
+            'to ' + if @definition.is_a?(Hash)
+                      readable(@definition.keys.first.to_s) +
+                        " #{@definition.values.first.inspect}"
+                    else
+                      readable(@definition.to_s)
+                    end
+        else
+          state.exception.message
+        end + if state.exception.nil?
+                ''
+              else
+                " (#{state.exception.class})"
+              end
+      end
+
+      # @param string [String] A UpperCamelCase string.
+      #
+      # @return [String] the snake_case string.
+      def readable(string)
+        string.gsub(/::/, '/')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-_', ' ')
+          .downcase
+      end
     end
   end
 end

data/lib/spectus/result/base.rb

@@ -1,12 +1,15 @@
 module Spectus
+  # Namespace for the results.
+  #
+  # @api private
+  #
   module Result
     # Result base's module.
     #
-    # @api public
-    #
     module Base
       # Initialize the result class.
       #
+      # @param message    [String] It is describing the actual/error value.
       # @param subject    [#object_id] The untrusted object to be tested.
       # @param challenge  [Symbol] The method to call on the subject.
       # @param context    [Array] Parameters of the challenge.
@@ -20,9 +23,10 @@ module Spectus
       # @param level      [:High, :Medium, :Low] The level of the expectation.
       # @param negate     [Boolean] Evaluate to a negative assertion.
       # @param valid      [Boolean] Report if the test was true or false.
-      def initialize(subject, challenge, context, actual, expected, got, error,
-        level, negate, valid)
+      def initialize(message, subject, challenge, context, actual, expected,
+        got, error, level, negate, valid)
 
+        @message    = message
         @subject    = subject
         @challenge  = challenge
         @context    = context
@@ -35,8 +39,47 @@ module Spectus
         @valid      = valid
       end
 
-      attr_reader :subject, :challenge, :context, :actual, :expected, :got,
-                  :error, :level
+      # @!attribute [r] subject
+      #
+      # @return [#object_id] The untrusted object to be tested.
+      attr_reader :subject
+
+      # @!attribute [r] challenge
+      #
+      # @return [Symbol] The method to call on the subject.
+      attr_reader :challenge
+
+      # @!attribute [r] context
+      #
+      # @return [Array] Parameters of the challenge.
+      attr_reader :context
+
+      # @!attribute [r] actual
+      #
+      # @return [#object_id] The value that the subject return through its
+      #   challenge.
+      attr_reader :actual
+
+      # @!attribute [r] expected
+      #
+      # @return [Array, Hash, Symbol] The definition of the expected value.
+      attr_reader :expected
+
+      # @!attribute [r] got
+      #
+      # @return [#object_id] The result of the boolean comparison between the
+      #   actual value and the expected value.
+      attr_reader :got
+
+      # @!attribute [r] error
+      #
+      # @return [#exception, nil] Any possible raised exception.
+      attr_reader :error
+
+      # @!attribute [r] level
+      #
+      # @return [:High, :Medium, :Low] The level of the expectation.
+      attr_reader :level
 
       # The value of the negate instance variable.
       #
@@ -53,9 +96,9 @@ module Spectus
         @valid
       end
 
-      # Report the result.
+      # Properties of the result.
       #
-      # @return [Symbol] the properties of the result.
+      # @return [Hash] the properties of the result.
       def to_h
         {
           subject:    subject,

data/lib/spectus/result/pass.rb

@@ -6,6 +6,11 @@ module Spectus
     class Pass
       include Base
 
+      # @!attribute [r] message
+      #
+      # @return [String] The message that describe the state.
+      attr_reader :message
+
       # The value of the expectation of the spec.
       #
       # @return [Boolean] the spec was true.

data/lib/spectus/sandbox.rb

@@ -6,8 +6,6 @@ module Spectus
   # @api private
   #
   class Sandbox
-    attr_reader :actual, :exception, :got
-
     # Execute the untested code from the passed block against the definition.
     #
     # @param [Array, Hash, Symbol] definition
@@ -23,6 +21,23 @@ module Spectus
       @exception = e
     end
 
+    # @!attribute [r] actual
+    #
+    # @return [#object_id] The value that the subject return through its
+    #   challenge.
+    attr_reader :actual
+
+    # @!attribute [r] exception
+    #
+    # @return [#exception, nil] Any possible raised exception.
+    attr_reader :exception
+
+    # @!attribute [r] got
+    #
+    # @return [#object_id] The result of the boolean comparison between the
+    #   actual value and the expected value.
+    attr_reader :got
+
     # Report to the spec's requirement level if the test is true or false.
     #
     # @return [Boolean] Report if the test was true or false.

data/lib/spectus.rb

@@ -9,8 +9,6 @@ require_relative File.join 'spectus', 'expectation_target'
 module Spectus
   # Expectations are built with this method.
   #
-  # @api public
-  #
   # @example Absolute requirement definition
   #   this { 42 }.MUST Equal: 42 # => #<Spectus::Result::Pass...>
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Cyril Wack
@@ -30,7 +30,7 @@ cert_chain:
   dzJvWzQ1+dJU6WQv75E9ddSkaQrK3nhdgQVu+/wgvGSrsMvOGNz+LXaSDxQqZuwX
   0KNQFuIukfrdk8URwRnHoAnvx4U93iUw
   -----END CERTIFICATE-----
-date: 2015-08-22 00:00:00.000000000 Z
+date: 2015-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: matchi
@@ -146,6 +146,7 @@ files:
 - checksum/spectus-2.1.2.gem.sha512
 - checksum/spectus-2.1.3.gem.sha512
 - checksum/spectus-2.2.0.gem.sha512
+- checksum/spectus-2.3.0.gem.sha512
 - lib/spectus.rb
 - lib/spectus/challenge.rb
 - lib/spectus/expectation_target.rb

metadata.gz.sig

@@ -1,2 +1 @@
-�+�:A��鏡(�K9ҝ�d��䉨�Q��������%��O�o�UoZ$��S��ߋٹܪA�)�W1��rɴ�uh���+C���>�N�ޘ�_�fS�bf��HA
Z��B�J��=�؍�m�a���N��㤯W��
-	�({]���V��'�<Lt���Օ�0� ��he���|�q	��{��_��Hxr����o�R�=�S`_���	�N�
+�q����eңM�O����x���Hл��z�өs����CW�G���ZAs�d����:�����Fk��8��8#�FZ��	��X��("�Q��oΟ�I��Y\�9�*A`�MCV��M�F_���B��q3��w
��!���kF|�h�|�7�3����`��b齄�me���S�)�	kO�2��k:�S�������J�h`¬�i"㟪��5���=n��5��gЇ��e�E�,<���Q���Af��