Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documentation

  • Loading branch information...
commit e6e4c794f2b1910da977881f10632bd0285ce524 1 parent 7d6d0bf
John Wilger authored
53  lib/kookaburra/mental_model_matcher.rb
@@ -3,8 +3,9 @@
3 3
 class Kookaburra
4 4
   class MentalModel
5 5
     # This is a custom matcher that matches the RSpec matcher API.
6  
-    # (The test_helpers.rb file provides a match function
7  
-    # for RSpec and a custom assertion for Test::Unit.)
  6
+    #
  7
+    # @see Kookaburra::TestHelpers#match_mental_model_of
  8
+    # @see Kookaburra::TestHelpers#assert_mental_model_of
8 9
     class Matcher
9 10
       def initialize(mental_model, collection_key)
10 11
         @collection_key = collection_key
@@ -15,10 +16,16 @@ def initialize(mental_model, collection_key)
15 16
         end
16 17
       end
17 18
 
18  
-      def expecting_nothing
19  
-        only
20  
-      end
21  
-
  19
+      # Specifies that result should be limited to the given keys from the
  20
+      # mental model.
  21
+      #
  22
+      # Useful if you are looking at a filtered result. That is, your mental
  23
+      # model contains elements { A, B, C }, but you only expect to see element
  24
+      # A.
  25
+      #
  26
+      # @param [Array] collection_keys The keys used in your mental model to
  27
+      #   reference the data
  28
+      # @return [self]
22 29
       def only(*collection_keys)
23 30
         keepers = @expected.slice(*collection_keys)
24 31
         tossers = @expected.except(*collection_keys)
@@ -29,11 +36,32 @@ def only(*collection_keys)
29 36
         self
30 37
       end
31 38
 
  39
+      # Reads better than {#only} with no args
  40
+      #
  41
+      # @return [self]
  42
+      def expecting_nothing
  43
+        only
  44
+      end
  45
+
  46
+      # The result contains everything that was expected to be found and nothing
  47
+      # that was unexpected.
  48
+      #
  49
+      # (Part of the RSpec protocol for custom matchers.)
  50
+      #
  51
+      # @param [Array] actual This is the data observed that you are attempting
  52
+      #   to match against the mental model.
  53
+      # @return Boolean
32 54
       def matches?(actual)
33 55
         @actual = actual
34 56
         expected_items_not_found.empty? && unexpected_items_found.empty?
35 57
       end
36 58
 
  59
+      # Message to be printed when observed reality does not conform to
  60
+      # mental model.
  61
+      #
  62
+      # (Part of the RSpec protocol for custom matchers.)
  63
+      #
  64
+      # @return String
37 65
       def failure_message_for_should
38 66
         message = "expected #{@collection_key} to match the user's mental model, but:\n"
39 67
         if expected_items_not_found.present?
@@ -47,15 +75,26 @@ def failure_message_for_should
47 75
         message
48 76
       end
49 77
 
  78
+      # Message to be printed when observed reality does conform to mental
  79
+      # model, but you did not expect it to.  (To be honest, we can't think of
  80
+      # why you would want this, but it is included for the sake of RSpec
  81
+      # compatibility.)
  82
+      #
  83
+      # (Part of the RSpec protocol for custom matchers.)
  84
+      #
  85
+      # @return String
50 86
       def failure_message_for_should_not
51 87
         "expected #{@collection_key} not to match the user's mental model"
52 88
       end
53 89
 
  90
+      # (Part of the RSpec protocol for custom matchers.)
  91
+      #
  92
+      # @return String
54 93
       def description
55 94
         "match the user's mental model of #{@collection_key}"
56 95
       end
57 96
 
58  
-    protected
  97
+      private
59 98
 
60 99
       def expected_items;   @expected.values;   end
61 100
       def unexpected_items; @unexpected.values; end
4  lib/kookaburra/test_helpers.rb
@@ -100,12 +100,16 @@ def k
100 100
 
101 101
     # RSpec-style custom matcher that compares a given array with
102 102
     # the current state of one named collection in the mental model
  103
+    #
  104
+    # @see Kookaburra::MentalModel::Matcher
103 105
     def match_mental_model_of(collection_key)
104 106
       MentalModel::Matcher.new(k.send(:__mental_model__), collection_key)
105 107
     end
106 108
 
107 109
     # Custom assertion for Test::Unit-style tests
108 110
     # (really, anything that uses #assert(predicate, message = nil))
  111
+    #
  112
+    # @see Kookaburra::MentalModel::Matcher
109 113
     def assert_mental_model_of(collection_key, actual, message = nil)
110 114
       matcher = match_mental_model_of(collection_key)
111 115
       result = matcher.matches?(actual)

0 notes on commit e6e4c79

Please sign in to comment.
Something went wrong with that request. Please try again.