ae 1.8.2 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,100 @@
1
+ # Subjunctives
2
+
3
+ Okay. I can hear the BDDers rumbling, "where's the *should?*"
4
+ AE has nothing against "should", but there are different
5
+ approaches for utilizing should nomenclature in specifications,
6
+ and AE wants to be open to these techniques. One of which
7
+ is how Shoulda (http://shoulda.rubyforge.org) utilizes
8
+ `should` in a way analogous to RSpec's use of `it`.
9
+
10
+ Even so, AE provides an optional mixin called `Subjunctive` which
11
+ can be used to create assertor methods with English subjunctive
12
+ terms, such as `should`, or `must`, `shall` and `will`.
13
+ To load this library use:
14
+
15
+ require 'ae/subjunctive'
16
+
17
+ Then all that is required it to define a subjunctive method for all
18
+ objects. For example:
19
+
20
+ def will(*args, &block)
21
+ Assertor.new(self, :backtrace=>caller).be(*args,&block)
22
+ end
23
+
24
+ It's that easy. Because of their commonality AE provides two such terms,
25
+ `should` and +must+ as optional add-ons out-of-the-box.
26
+
27
+ require 'ae/should'
28
+ require 'ae/must'
29
+
30
+ We will use these two methods interchangeable for the rest of this
31
+ demonstration, but to be clear they both work exactly the same way,
32
+ and almost exactly like `assert`.
33
+
34
+ Keep in mind, AE "conical" functionality does not entail the subjunctive
35
+ forms. These are simply options you can load via your `test_helper.rb`,
36
+ or similar script, if you prefer these nomenclatures.
37
+
38
+
39
+ ## Fluent Notation and Antonyms
40
+
41
+ Like `assert`, `should` and `must` can be used as higher order functions.
42
+
43
+ 4.should == 4
44
+ 4.must == 4
45
+
46
+ Antonyms provided for +should+ as `should!` (read "should not") and `shouldnt`.
47
+ For `must`, they are `must!` and +wont+.
48
+
49
+ 4.should! == 5
50
+ 4.shouldnt == 5
51
+
52
+ 4.must! == 5
53
+ 4.wont == 5
54
+
55
+
56
+ ## To Be
57
+
58
+ On occasions where the English readability of a specification is hindered,
59
+ `be` can be used.
60
+
61
+ StandardError.must.be.raised? do
62
+ unknown_method
63
+ end
64
+
65
+ The `be` method is the same as `assert` with the single exception
66
+ that it will compare a lone argument to the receiver using `equate?`,
67
+ unlike `assert` which simply checks to see that the argument evaluates
68
+ as true.
69
+
70
+ 10.should.be 10
71
+ 10.should.be 10.0
72
+ 10.should.be Numeric
73
+
74
+ Assertion.assert.raised? do
75
+ 10.should.be "40"
76
+ end
77
+
78
+
79
+ ## Indefinite Articles
80
+
81
+ Additional English forms are `a` and `an`, equivalent to `be` except
82
+ that they use `case?` (same as `#===`) instead of `equate?` when
83
+ acting on a single argument.
84
+
85
+ "hi".must.be.a String
86
+
87
+ Assertion.assert.raised? do
88
+ /x/.must.be.a /x/
89
+ end
90
+
91
+ Otherwise they are interchangeable.
92
+
93
+ "hi".must.be.an.instance_of?(String)
94
+
95
+ The indefinite articles work well when a noun follows as an arguments.
96
+
97
+ palindrome = lambda{ |x| x == x.reverse }
98
+
99
+ "abracarba".must.be.a palindrome
100
+
data/demo/05_expect.md ADDED
@@ -0,0 +1,136 @@
1
+ # Expect Method
2
+
3
+ Expect is another assertion nomenclature available for use in your
4
+ tests or specifications. Inspired by Jay Fields' Expectations library,
5
+ it provides convenient syntax for creating exception and case equality
6
+ assertions.
7
+
8
+ require 'ae/expect'
9
+
10
+
11
+ ## Underlying Comparison
12
+
13
+ Expect uses `#===` for comparison. So providing an argument and a block
14
+ to #expect we can test for a somewhat broader range of compassion
15
+ than #assert. For example we can test for a subclass.
16
+
17
+ expect Numeric do
18
+ 3
19
+ end
20
+
21
+ Assertion.assert.raised? do
22
+ expect Numeric do
23
+ "3"
24
+ end
25
+ end
26
+
27
+ Any expected value counts, even `nil` or `false`.
28
+
29
+ expect nil do
30
+ nil
31
+ end
32
+
33
+ Assertion.assert.raised? do
34
+ "abc".expect nil do
35
+ "abc"
36
+ end
37
+ end
38
+
39
+ A block that takes an argument is given the receiver.
40
+
41
+ "abc".expect(3) { |s| s.size }
42
+
43
+
44
+ ## Exception Expectation
45
+
46
+ If the comparator is an Exception class or a instance of an Exception class,
47
+ then #expect will check to see if the block raises that kind of exception.
48
+
49
+ expect StandardError do
50
+ some_undefined_method
51
+ end
52
+
53
+ expect Assertion do
54
+ expect(nil)
55
+ end
56
+
57
+ An instance of an Exception class stands for its class.
58
+
59
+ expect ArgumentError.new do
60
+ raise ArgumentError
61
+ end
62
+
63
+ An exception of another kind fails the expectation, but an interrupt or
64
+ an exit is never caught, so it isn't mistaken for a failure, or for
65
+ a pass when negated.
66
+
67
+ expect SystemExit do
68
+ expect! ArgumentError do
69
+ exit
70
+ end
71
+ end
72
+
73
+ This is an important distinction to note because it means `#expect` can not be used
74
+ if verify instances of Exception classes.
75
+
76
+ Assertion.assert.raised? do
77
+ expect Exception do
78
+ Exception.new
79
+ end
80
+ end
81
+
82
+
83
+ ## Regex Expectations
84
+
85
+ That #expect entails `#===` also means we can check for Regexp matches.
86
+
87
+ expect /x/ do
88
+ "oooxooo"
89
+ end
90
+
91
+
92
+ ## Expected Method
93
+
94
+ We can use #expected to make the receiver the object of expectation.
95
+
96
+ x = "dummy"
97
+
98
+ /x/.expected do
99
+ "x"
100
+ end
101
+
102
+
103
+ ## Without Block
104
+
105
+ Without a block, the receiver is compared to the argument.
106
+
107
+ x.expect String
108
+
109
+
110
+ ## Negative Forms
111
+
112
+ Like #assert, `#expect` has a negated form called #expect!
113
+
114
+ expect! /x/ do
115
+ "o"
116
+ end
117
+
118
+ The pure word form for those who do not like the clever use of the
119
+ explimation mark is #forbid.
120
+
121
+ forbid /x/ do
122
+ "o"
123
+ end
124
+
125
+
126
+ ## Functor, or Higher Order Function
127
+
128
+ Like #assert, #expect can be used used as a *fluid* notation.
129
+
130
+ 10.expect == 10
131
+
132
+ In which case it works just like `#assert`, including negative forms.
133
+
134
+ 10.expect! == 11
135
+ 10.forbid == 11
136
+
data/demo/06_counts.md ADDED
@@ -0,0 +1,33 @@
1
+ # Assertion Counts
2
+
3
+ AE tracks the number of assertions made and the number that failed to pass.
4
+ We can reset the count using the +recount+ class method.
5
+
6
+ old_counts = AE::Assertor.recount
7
+
8
+ For example if we have one assertion pass and another fail.
9
+
10
+ assert(true)
11
+
12
+ expect Assertion do
13
+ assert(false)
14
+ end
15
+
16
+ We will see that AE counted three assertions and one failure.
17
+
18
+ counts = AE::Assertor.counts.dup
19
+
20
+ counts[:total].assert == 3
21
+ counts[:pass].assert == 2
22
+ counts[:fail].assert == 1
23
+
24
+ The #expect call is an assertion too, which is why the total count is 3
25
+ rather than 2.
26
+
27
+ Now that we are done checking counts we will restore them so that
28
+ any other demos being run with this will tally correctly.
29
+
30
+ AE::Assertor.recount(old_counts)
31
+ AE::Assertor.counts[:total] += 3
32
+ AE::Assertor.counts[:pass] += 3
33
+
@@ -0,0 +1,34 @@
1
+ # Matchers
2
+
3
+ Matchers are simply Procs or objects with the proper interface that can be
4
+ passed to #assert or #refute (or other Assertor) as an ecapsulated test.
5
+
6
+ ## Proc or #call
7
+
8
+ Passing a Proc object, or any object that responds to `#call`, will use it
9
+ as if it were a block of the method. This allows for a simple way to quickly
10
+ create reusable assertions.
11
+
12
+ palindrome = lambda{ |word| word == word.reverse }
13
+
14
+ "abracarba".assert palindrome
15
+
16
+ ## #matches?
17
+
18
+ Additionally if an object responds to #matches? then the receiver
19
+ will be passed to this method to determine if the assertion passes.
20
+
21
+ palindrome = Object.new
22
+
23
+ def palindrome.matches?(word)
24
+ word == word.reverse
25
+ end
26
+
27
+ "abracarba".assert palindrome
28
+
29
+ ## RSpec, Shoulda and other 3rd-Party Matchers
30
+
31
+ With tha addition of #matches?, AE supports the same interface for matchers
32
+ as RSpec. Any matcher library designed for use with RSpec should therefore
33
+ be usable with AE as well. This includes RSpecs own matchers and Shoulda's
34
+ excellent Rails matchers.
data/demo/08_check.md ADDED
@@ -0,0 +1,61 @@
1
+ ## Check Ok/No
2
+
3
+ The Check library is an optional library that can be used
4
+ to conveniently speed-up construction of reptitive assertions.
5
+
6
+ To use it, first require the library, then include the mixin
7
+ into the namespace in which you will utilize it.
8
+
9
+ require 'ae/check'
10
+
11
+ include AE::Check
12
+
13
+ Now we can define ok/no check procedures. A one-off procedure is
14
+ defined with a block only.
15
+
16
+ check do |x, y|
17
+ x == y
18
+ end
19
+
20
+ ok 1,1
21
+ no 1,2
22
+
23
+ To define reusable check procedures, give the procedure a name.
24
+
25
+ check :palindrome do |x|
26
+ x.reverse == x
27
+ end
28
+
29
+ This will also cause the current check method to be set.
30
+ Later in the code, the check procedure can be reset to this
31
+ by just passing the name.
32
+
33
+ check :palindrome
34
+
35
+ ok 'abracarba'
36
+ no 'foolishness'
37
+
38
+ The Check mixin comes preloaded with a few standard checks.
39
+ By default the `:equality` procedure is used.
40
+
41
+ check :equality
42
+
43
+ ok 1=>1.0
44
+
45
+ Notice the use of the hash argument here. This is a useful construct for
46
+ many check procedures becuase it it akin to the `#=>` pattern we often
47
+ see in code examples and it also allows for multiple assertions in one call.
48
+ For instance, in the case of `:equality`, multiple entries convey a
49
+ meaning of logical-or.
50
+
51
+ ok 1=>2, 1.0=>1
52
+
53
+ This would pass because the second assertion of equality is true.
54
+
55
+ Another built in check is `:case_equality` which uses `#===` instead of `#==`
56
+ to make the comparison.
57
+
58
+ check :case_equality
59
+
60
+ ok 1=>Integer
61
+
data/demo/09_legacy.md ADDED
@@ -0,0 +1,122 @@
1
+ # Legacy Assertions
2
+
3
+ The optional `ae/legacy` library provides Test::Unit's assertion
4
+ methods, for an easier move from Test::Unit to AE. They are defined
5
+ in the `AE::Legacy::Assertions` module, which `AE::World` includes.
6
+
7
+ require 'ae/legacy'
8
+
9
+ class LegacyTest
10
+ include AE::Legacy::Assertions
11
+ end
12
+
13
+ t = LegacyTest.new
14
+
15
+
16
+ ## Assert
17
+
18
+ With an argument, `assert` checks that it is true, with an optional
19
+ message.
20
+
21
+ t.assert(true)
22
+ t.assert(1 == 1, "one is one")
23
+
24
+ Assertion.assert.raised? do
25
+ t.assert(false, "must fail")
26
+ end
27
+
28
+ Assertion.assert.raised? do
29
+ t.assert(nil)
30
+ end
31
+
32
+ With a block instead, it works like `assert_block`.
33
+
34
+ t.assert { true }
35
+
36
+ Assertion.assert.raised? do
37
+ t.assert { false }
38
+ end
39
+
40
+
41
+ ## Assert Block
42
+
43
+ t.assert_block { true }
44
+
45
+ Assertion.assert.raised? do
46
+ t.assert_block { false }
47
+ end
48
+
49
+
50
+ ## Equality and Type
51
+
52
+ t.assert_equal 2, 1 + 1
53
+
54
+ Assertion.assert.raised? do
55
+ t.assert_equal 2, 3
56
+ end
57
+
58
+ `assert_instance_of` wants the exact class, while `assert_kind_of`
59
+ accepts a superclass too.
60
+
61
+ t.assert_instance_of Integer, 1
62
+ t.assert_kind_of Numeric, 1
63
+
64
+ Assertion.assert.raised? do
65
+ t.assert_instance_of Numeric, 1
66
+ end
67
+
68
+
69
+ ## Raises
70
+
71
+ `assert_raises` passes if the block raises one of the given exceptions,
72
+ or a subclass of one, and returns the exception.
73
+
74
+ e = t.assert_raises(ArgumentError) { raise ArgumentError, "bad" }
75
+ e.message.assert == "bad"
76
+
77
+ t.assert_raises(StandardError) { raise ArgumentError }
78
+
79
+ It fails if nothing is raised, or something else is.
80
+
81
+ Assertion.assert.raised? do
82
+ t.assert_raises(ArgumentError) { }
83
+ end
84
+
85
+ Assertion.assert.raised? do
86
+ t.assert_raises(ArgumentError) { raise TypeError }
87
+ end
88
+
89
+
90
+ ## Throws
91
+
92
+ t.assert_throws(:done) { throw :done }
93
+
94
+ Assertion.assert.raised? do
95
+ t.assert_throws(:done) { throw :other }
96
+ end
97
+
98
+ Assertion.assert.raised? do
99
+ t.assert_throws(:done) { }
100
+ end
101
+
102
+
103
+ ## Messages
104
+
105
+ Each assertion has a default message.
106
+
107
+ message = begin
108
+ t.assert_operator 1, :>, 2
109
+ rescue Assertion => e
110
+ e.message
111
+ end
112
+
113
+ message.assert.include?("Expected 1.>(2) to be true")
114
+
115
+
116
+ ## Counts
117
+
118
+ Legacy assertions are counted like any other.
119
+
120
+ before = AE::Assertor.counts[:total]
121
+ t.assert_equal 1, 1
122
+ AE::Assertor.counts[:total].assert == before + 1
@@ -0,0 +1,48 @@
1
+ # Framework Adapters
2
+
3
+ AE works within other test frameworks by way of adapters. An adapter
4
+ makes AE raise the framework's own assertion error, so a failed AE
5
+ assertion is reported as a failure rather than an error, and it adds
6
+ each AE assertion to the framework's count. Requiring `ae/adapter`
7
+ loads the adapter for whichever framework is already loaded.
8
+
9
+ To see them at work, we run a small test under each framework in a
10
+ separate Ruby process.
11
+
12
+ require 'rbconfig'
13
+
14
+ lib = File.dirname($LOADED_FEATURES.grep(%r{/ae\.rb\z}).first)
15
+
16
+ run = lambda do |code|
17
+ IO.popen([RbConfig.ruby, '-I', lib, '-e', code, err: [:child, :out]], &:read)
18
+ end
19
+
20
+
21
+ ## Minitest
22
+
23
+ output = run.call <<~'RUBY'
24
+ require 'minitest/autorun'
25
+ require 'ae/adapter'
26
+
27
+ class ExampleTest < Minitest::Test
28
+ def test_pass; 5.assert == 5; end
29
+ def test_fail; 5.assert == 6; end
30
+ end
31
+ RUBY
32
+
33
+ output.assert.include?("2 runs, 2 assertions, 1 failures, 0 errors")
34
+
35
+
36
+ ## Test::Unit
37
+
38
+ output = run.call <<~'RUBY'
39
+ require 'test/unit'
40
+ require 'ae/adapter'
41
+
42
+ class ExampleTest < Test::Unit::TestCase
43
+ def test_pass; 5.assert == 5; end
44
+ def test_fail; 5.assert == 6; end
45
+ end
46
+ RUBY
47
+
48
+ output.assert.include?("2 tests, 2 assertions, 1 failures, 0 errors")
@@ -0,0 +1 @@
1
+ require 'ae'
data/lib/ae/adapter.rb CHANGED
@@ -1,8 +1,7 @@
1
- if defined?(::MiniTest)
1
+ if defined?(::Minitest::Test)
2
2
  require 'ae/adapters/minitest'
3
- elsif defined?(::Test::Unit)
3
+ elsif defined?(::Test::Unit::TestCase)
4
4
  require 'ae/adapters/testunit'
5
- elsif defined?(::RSpec)
5
+ elsif defined?(::RSpec::Expectations)
6
6
  require 'ae/adapters/rspec'
7
7
  end
8
-
@@ -1,46 +1,45 @@
1
1
  require 'ae'
2
2
 
3
- AE.assertion_error = ::MiniTest::Assertion
3
+ AE.assertion_error = ::Minitest::Assertion
4
4
 
5
- module MiniTest #:nodoc:
6
- class Unit #:nodoc:
7
-
8
- # MiniTest tracks assertion counts internally in it's Unit class via the
9
- # +assertion_count+ attribute. To work with AE we need add in AE's assertion
10
- # total by overriding the +assertion_count+ method.
11
- #
12
- # @return [Integer] Number of assertions made.
13
- def assertion_count
14
- @assertion_count + AE::Assertor.counts[:total]
15
- end
16
-
17
- # To teach MiniTest to recognize AE's expanded concept of assertions
18
- # we add in an extra capture clause to it's #puke method.
19
- #
20
- # @return [String] Status code is `S`, `F`, or `E`.
21
- def puke k, m, e
22
- case e
23
- when MiniTest::Skip
24
- @skips += 1
25
- return "S" unless @verbose
26
- e = "Skipped:\n#{m}(#{k}) [#{location e}]:\n#{e.message}\n"
27
- when MiniTest::Assertion
28
- @failures += 1
29
- e = "Failure:\n#{m}(#{k}) [#{location e}]:\n#{e.message}\n"
30
- else
31
- if e.respond_to?(:assertion?) && e.assertion?
32
- @failures += 1
33
- e = "Failure:\n#{m}(#{c}) [#{location e}]:\n#{e.message}\n"
34
- else
35
- @errors += 1
36
- b = MiniTest::filter_backtrace(e.backtrace).join "\n "
37
- e = "Error:\n#{m}(#{k}):\n#{e.class}: #{e.message}\n #{b}\n"
5
+ module AE
6
+ # Minitest adapter. AE raises Minitest::Assertion, so failures are
7
+ # reported as failures, and each AE assertion is added to the
8
+ # running test's assertion count.
9
+ module MinitestAdapter
10
+ # Notes the running test, and reports any other exception that
11
+ # says it is an assertion as a failure rather than an error.
12
+ module Test
13
+ def capture_exceptions
14
+ previous = ::Thread.current[:ae_minitest_test]
15
+ ::Thread.current[:ae_minitest_test] = self
16
+ super do
17
+ begin
18
+ yield
19
+ rescue ::Minitest::Assertion
20
+ raise
21
+ rescue ::Exception => e
22
+ raise unless e.respond_to?(:assertion?) && e.assertion?
23
+ failure = ::Minitest::Assertion.new(e.message)
24
+ failure.set_backtrace(e.backtrace)
25
+ raise failure
26
+ end
38
27
  end
28
+ ensure
29
+ ::Thread.current[:ae_minitest_test] = previous
39
30
  end
40
- @report << e
41
- e[0, 1]
42
31
  end
43
32
 
33
+ # Adds each AE assertion to the running test's count.
34
+ module Counts
35
+ def increment_counts(pass)
36
+ test = ::Thread.current[:ae_minitest_test]
37
+ test.assertions += 1 if test
38
+ super
39
+ end
40
+ end
44
41
  end
45
42
  end
46
43
 
44
+ Minitest::Test.prepend(AE::MinitestAdapter::Test)
45
+ AE::Assertor.singleton_class.prepend(AE::MinitestAdapter::Counts)