spectus 2.0.3 → 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4e7aff59bbeafa35f8d48f0ad922c18b67b3ab67
+  data.tar.gz: 4fc80ff8c310a2f088182976c0c1a770291c375e
+SHA512:
+  metadata.gz: d7bad2346b48569a149e01e486990b64f62a999b2a98f4f5530868f6ad43f835e2b6c87d77f30dc922e53f476996926e1a7cadfde8a44d06c303ff9d2ab461a0
+  data.tar.gz: 96073c63f2c891acf9a44e46fc36b1fea47204c288699712a4205480ee80f264c449eef926cf30a76670896ec896f055b1dd0fd83affb133e56c0b076df10443

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/.ruby-version
 /.yardoc
 /Gemfile.lock
 /_yardoc/

data/.rubocop.yml

@@ -0,0 +1,12 @@
+TrivialAccessors:
+  Enabled: true
+  ExactNameMatch: true
+
+Style/MethodName:
+  Enabled: false
+
+ParameterLists:
+  Max: 11
+
+Metrics/MethodLength:
+  Max: 16

data/README.md

@@ -36,7 +36,9 @@ Or install it yourself as:
 
     $ gem install spectus
 
-## Results
+## Expectation
+
+An expectation is an assertion that is either `true` or `false`.
 
 | Requirement levels        | **MUST** | **SHOULD** | **MAY** |
 | ------------------------- | -------- | ---------- | ------- |
@@ -45,38 +47,72 @@ Or install it yourself as:
 | Implemented & Exception   | `false`  | `false`    | `false` |
 | Not implemented           | `false`  | `false`    | `true`  |
 
+## Results
+
+There are two cases:
+
+* when an expectation is `true`, an instance of `Spectus::Result::Pass` is returned;
+* when an expectation is `false`, an instance of `Spectus::Result::Fail` is raised.
+
+Both instances share the same interface.
+
 ## Usage
 
-**Absolute requirement** definition:
+### Absolute requirement
+
+Given the `"ルビー"` object, when it receives `valid_encoding?` method, then it **MUST** be `true`:
 
 ```ruby
-Spectus.this { 'foo'.upcase }.MUST eql: 'FOO' # => true
+Spectus.this { 'ルビー'.valid_encoding? }.MUST :BeTrue
+# => #<Spectus::Result::Pass:0x007fa41c371b90 @message="passing spec", @subject=#<Proc:0x007fa41c3721f8@(irb):1>, @challenge=:call, @context=[], @actual=true, @expected=:BeTrue, @got=true, @error=nil, @level=:High, @negate=false, @valid=true>
 ```
 
-**Absolute prohibition** definition:
+The result of the test shows that the spec passed.
+
+### Absolute prohibition
+
+Given the `"foo"` object, when it receives `length` method, then it **MUST NOT** raise the `NoMethodError` exception:
 
 ```ruby
-Spectus.this { 'foo'.length }.MUST_NOT equal: 42 # => true
+Spectus.this { 'foo'.length }.MUST_NOT RaiseException: NoMethodError
+# => #<Spectus::Result::Pass:0x007fa41e001d50 @message="passing spec", @subject=#<Proc:0x007fa41c34a928@(irb):2>, @challenge=:call, @context=[], @actual=3, @expected={:RaiseException=>NoMethodError}, @got=true, @error=nil, @level=:High, @negate=true, @valid=true>
 ```
 
-**Recommended** definition:
+The result of the test shows that the spec passed.
+
+### Recommended
+
+Given the `BasicObject` object, when it receives `superclass` method, then it **SHOULD** return the explicit blank class `NilClass`:
 
 ```ruby
-Spectus.this { 'foo'.valid_encoding? }.SHOULD equal: true # => true
+Spectus.this { BasicObject.superclass }.SHOULD Equal: NilClass
+# => #<Spectus::Result::Pass:0x007fa41c2f1d00 @message="passing spec", @subject=#<Proc:0x007fa41c2f2110@(irb):3>, @challenge=:call, @context=[], @actual=nil, @expected={:Equal=>NilClass}, @got=false, @error=nil, @level=:Medium, @negate=false, @valid=false>
 ```
 
-**Not recommended** definition:
+Even if the sole instance of `NilClass` (`nil`) was returned, there isn't any exception so the result of the test shows that the spec passed.
+
+### Not recommended
+
+Given the `"1"` object, when it receives `+(1)` method, then it **SHOULD NOT** return the `"11"` value:
 
 ```ruby
-Spectus.this { ''.blank? }.SHOULD_NOT raise_exception: NoMethodError # => true
+Spectus.this { '1' + 1 }.SHOULD_NOT Eql: '11'
+# => raise #<Spectus::Result::Fail: failing spec> exception
 ```
 
-**Optional** definition:
+There was a `TypeError` exception, the result of the test shows that the spec failed.
+
+### Optional
+
+Given the `"foo"` object, when it receives `bar` method, then it **MAY** match the regular expression `/^foo$/`:
 
 ```ruby
-Spectus.this { 'foo'.bar }.MAY match: /^foo$/ # => true
+Spectus.this { 'foo'.blank? }.MAY :BeFalse
+# => #<Spectus::Result::Pass:0x007fa41c2bae18 @message="passing spec", @subject=#<Proc:0x007fa41c2bb368@(irb):6>, @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.
+
 ## Versioning
 
 __Spectus__ follows [Semantic Versioning 2.0](http://semver.org/).
@@ -88,3 +124,7 @@ __Spectus__ follows [Semantic Versioning 2.0](http://semver.org/).
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## License
+
+See `LICENSE.md` file.

data/Rakefile

@@ -2,7 +2,6 @@ require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.pattern = File.join 'test', '**', 'test_*.rb'
   t.verbose = true
   t.warning = true
 end

data/VERSION.semver

@@ -1 +1 @@
-2.0.3
+2.1.0

data/lib/spectus.rb

@@ -5,16 +5,16 @@ require_relative File.join 'spectus', 'expectation_target'
 # @api public
 #
 # @example 42 MUST be equal to 42
-#   Spectus.this { 42 }.MUST equal: 42 # => true
+#   Spectus.this { 42 }.MUST Equal: 42 # => #<Spectus::Result::Pass...>
 module Spectus
   # Expectations are built with this method.
   #
   # @api public
   #
   # @example Absolute requirement definition
-  #   this { 42 }.MUST equal: 42 # => true
+  #   this { 42 }.MUST Equal: 42 # => #<Spectus::Result::Pass...>
   #
-  # @yieldparam input the code to test.
+  # @param input [Proc] the code to test.
   #
   # @return [ExpectationTarget] the expectation target.
   def self.this(&input)

data/lib/spectus/challenge.rb

@@ -0,0 +1,22 @@
+module Spectus
+  # This class evaluate the expectation with the passed block.
+  #
+  # @api private
+  #
+  class Challenge
+    # A Query to the subject.
+    #
+    # @param [#to_sym] method_id the identifier of a method.
+    # @param [Array] args the arguments of the method.
+    def initialize(method_id, *args)
+      @symbol = method_id.to_sym
+      @args   = args
+    end
+
+    # @return [Symbol] the method to call on the subject.
+    attr_reader :symbol
+
+    # @return [Array] the parameters following the method.
+    attr_reader :args
+  end
+end

data/lib/spectus/expectation_target.rb

@@ -1,50 +1,52 @@
-require_relative File.join 'requirement_level', 'high'
-require_relative File.join 'requirement_level', 'medium'
-require_relative File.join 'requirement_level', 'low'
+require_relative File.join 'level', 'high'
+require_relative File.join 'level', 'medium'
+require_relative File.join 'level', 'low'
+require_relative 'challenge'
 
 module Spectus
   # Wraps the target of an expectation.
   #
-  # @api private
-  #
   # @example
-  #   this { stuff } # => ExpectationTarget wrapping the block
+  #   this { actual value } # => ExpectationTarget wrapping the block
   class ExpectationTarget < BasicObject
     # Create a new expection target
     #
-    # @yieldparam actual the value which is compared with the expected value.
-    def initialize(&actual)
-      @actual = actual
+    # @param subject [Proc] the value which is compared with the expected value.
+    def initialize(&subject)
+      @subject    = subject
+      @challenge  = Challenge.new(:call)
     end
 
+    # @return [BasicObject] the front object to be tested.
+    attr_reader :subject
+
+    # @return [Challenge] the challenge to call on the subject.
+    attr_reader :challenge
+
     # This word, or the terms "REQUIRED" or "SHALL", mean that the
     # definition is an absolute requirement of the specification.
     #
-    # @api public
-    #
     # @example _Absolute requirement_ definition
-    #   this { 'foo'.upcase }.MUST eql: 'FOO' # => true
+    #   this { 'foo'.upcase }.MUST Eql: 'FOO'
     #
-    # @param [Hash] definition
+    # @param definition [Array, Hash, Symbol]
     #
-    # @return [Boolean] report if the expectation is true or false.
+    # @return [Result::Fail, Result::Pass] report if the spec pass or fail.
     def MUST(definition)
-      RequirementLevel::High.new(definition).pass?(&@actual)
+      RequirementLevel::High.new(definition, false, subject, challenge).result
     end
 
     # This phrase, or the phrase "SHALL NOT", mean that the
     # definition is an absolute prohibition of the specification.
     #
-    # @api public
-    #
     # @example _Absolute prohibition_ definition
-    #   this { 'foo'.length }.MUST_NOT equal: 42 # => true
+    #   this { 'foo'.size }.MUST_NOT Equal: 42
     #
-    # @param [Hash] definition
+    # @param definition [Array, Hash, Symbol]
     #
-    # @return [Boolean] report if the expectation is true or false.
+    # @return [Result::Fail, Result::Pass] report if the spec pass or fail.
     def MUST_NOT(definition)
-      RequirementLevel::High.new(definition, true).pass?(&@actual)
+      RequirementLevel::High.new(definition, true, subject, challenge).result
     end
 
     # This word, or the adjective "RECOMMENDED", mean that there
@@ -52,16 +54,14 @@ module Spectus
     # particular item, but the full implications must be understood and
     # carefully weighed before choosing a different course.
     #
-    # @api public
-    #
     # @example _Recommended_ definition
-    #   this { 'foo'.valid_encoding? }.SHOULD equal: true # => true
+    #   this { 'foo'.valid_encoding? }.SHOULD Equal: true
     #
-    # @param [Hash] definition
+    # @param definition [Array, Hash, Symbol]
     #
-    # @return [Boolean] report if the expectation is true or false.
+    # @return [Result::Fail, Result::Pass] report if the spec pass or fail.
     def SHOULD(definition)
-      RequirementLevel::Medium.new(definition).pass?(&@actual)
+      RequirementLevel::Medium.new(definition, false, subject, challenge).result
     end
 
     # This phrase, or the phrase "NOT RECOMMENDED" mean that
@@ -70,16 +70,14 @@ module Spectus
     # implications should be understood and the case carefully weighed
     # before implementing any behavior described with this label.
     #
-    # @api public
-    #
     # @example _Not recommended_ definition
-    #   this { ''.blank? }.SHOULD_NOT raise_exception: NoMethodError # => true
+    #   this { ''.blank? }.SHOULD_NOT RaiseException: NoMethodError
     #
-    # @param [Hash] definition
+    # @param definition [Array, Hash, Symbol]
     #
-    # @return [Boolean] report if the expectation is true or false.
+    # @return [Result::Fail, Result::Pass] report if the spec pass or fail.
     def SHOULD_NOT(definition)
-      RequirementLevel::Medium.new(definition, true).pass?(&@actual)
+      RequirementLevel::Medium.new(definition, true, subject, challenge).result
     end
 
     # This word, or the adjective "OPTIONAL", mean that an item is
@@ -94,16 +92,14 @@ module Spectus
     # does not include the option (except, of course, for the feature the
     # option provides.)
     #
-    # @api public
-    #
     # @example _Optional_ definition
-    #   this { 'foo'.bar }.MAY match: /^foo$/ # => true
+    #   this { 'foo'.bar }.MAY Match: /^foo$/
     #
-    # @param [Hash] definition
+    # @param definition [Array, Hash, Symbol]
     #
-    # @return [Boolean] report if the expectation is true or false.
+    # @return [Result::Fail, Result::Pass] report if the spec pass or fail.
     def MAY(definition)
-      RequirementLevel::Low.new(definition).pass?(&@actual)
+      RequirementLevel::Low.new(definition, false, subject, challenge).result
     end
   end
 end

data/lib/spectus/level/base.rb

@@ -0,0 +1,72 @@
+require_relative File.join '..', 'sandbox'
+require_relative File.join '..', 'result', 'fail'
+require_relative File.join '..', 'result', 'pass'
+
+module Spectus
+  module RequirementLevel
+    # Requirement level's base class.
+    #
+    # @api private
+    #
+    class Base
+      # Initialize the requirement level class.
+      #
+      # @param definition [Array, Hash, Symbol] The definition of the expected
+      #   value.
+      # @param negate     [Boolean] Evaluate to a negative assertion.
+      # @param subject    [#object_id] the front object to test.
+      # @param challenge  [Challenge] a challenge for the subject.
+      def initialize(definition, negate, subject, challenge)
+        @definition = definition
+        @negate     = negate
+        @subject    = subject
+        @challenge  = challenge
+      end
+
+      protected
+
+      # @param state [Sandbox] The sandbox that tested the code.
+      #
+      # @return [Result::Pass] pass the spec.
+      def pass!(state)
+        Result::Pass.new('passing spec', *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('failing spec', *result_signature(state)))
+      end
+
+      # @param state [Sandbox] The sandbox that tested the code.
+      #
+      # @return [Array] list of parameters.
+      def result_signature(state)
+        [
+          @subject,
+          @challenge.symbol,
+          @challenge.args,
+          state.actual,
+          @definition,
+          state.got,
+          state.exception,
+          level,
+          @negate,
+          state.valid?
+        ]
+      end
+
+      # @return [Symbol] the requirement level.
+      def level
+        self.class.name.split('::').last.to_sym
+      end
+
+      # @return [Sandbox] the sandbox.
+      def sandbox
+        Sandbox.new(@definition, @negate, @subject, @challenge.symbol,
+                    *@challenge.args)
+      end
+    end
+  end
+end

data/lib/spectus/level/high.rb

@@ -0,0 +1,25 @@
+require_relative 'base'
+
+module Spectus
+  module RequirementLevel
+    # High requirement level's class.
+    #
+    # @api private
+    #
+    class High < Base
+      # Evaluate the expectation.
+      #
+      # @return [Result::Fail, Result::Pass] report if the high expectation
+      #   pass or fail.
+      def result
+        state = sandbox
+
+        if state.valid?
+          pass!(state)
+        else
+          fail!(state)
+        end
+      end
+    end
+  end
+end

data/lib/spectus/level/low.rb

@@ -0,0 +1,25 @@
+require_relative 'base'
+
+module Spectus
+  module RequirementLevel
+    # Low requirement level's class.
+    #
+    # @api private
+    #
+    class Low < Base
+      # Evaluate the expectation.
+      #
+      # @return [Result::Fail, Result::Pass] report if the low expectation
+      #   pass or fail.
+      def result
+        state = sandbox
+
+        if state.valid? || state.exception.class.equal?(::NoMethodError)
+          pass!(state)
+        else
+          fail!(state)
+        end
+      end
+    end
+  end
+end