Introduction
AE is an assertions framework for Ruby. It’s designed around the concept of an Assertor. The Assertor is an Assertion Functor, or Higher-Order Function, which reroutes method calls while monitoring them for failing conditions.
What’s Provided
Requiring the AE library.
require 'ae'
Loads two classes, Assertion and Assertor, the Kernel method assert and it’s ancillaries assert! and refute and a set of core extensions that make writing certain types of assertions easier.
Assertion and Assertor Classes
The Assertion class is at the heart of AE. All other AE methods depend on it. The Assertion class is a subclass of Exception. When an assertion is made and fails, it is an instance of Assertion that is raised.
Assertion.assert.raised? do
msg = "my failure message"
assert false, msg
end
Like any raised exception, the last Assertion message is available via $!.
(FYI, in Test::Unit the equivalent class was called AssertionFailedError.)
Assertions themsevles are not generally used in creating tests or behavior specifications. Rather they are used to create additonal types of assertion methods.
As mentioned above the Assertor class is a type of Higher-Order function, or Functor, which intercedes with a normal message invocation to monitor for failed conditions, upon which is raises Assertion exceptions.
Assertion Methods
The three methods, assert, assert! and refute all return an Assertor instance when used fluidly, i.e. magic-dot notation, higher-order notation, functor notation, whatever you prefer to call it.
assert(Assertor === assert)
Through the use of method_missing, the Assertor allows us to write statements like:
1.assert == 1
If the operation evaluates to false or nil, then an Assertion error is raised.
Assertion.assert.raised? do
1.assert == 2
end
The methods assert! and refute are just like assert expect they purport the negative condition. Patterned after Ruby’s own use of "!" as meaning not, assert! should be read "assert not". While refute exists for the sake of those who find the use of a bang method for this purpose unsuited to them.
How It Works
An Assertor essentially sits in wait for a method call (via method_missing). When that happens it applies the method to the original receiver, but wrapped in a clause that raises an Assertion should the statement fail. If we wanted to be pedantic, we could write our assertions like:
raise Assertion.new("1 != 1") unless 1 == 1
Instead of
1.assert == 1
Obviously using Assertor methods are whole lot more concise.
Assert Method
Compatible with Test::Unit
The assert method is designed to be backward compatible with the same method in Test::Unit.
Using an argument, assert will check that an argument evaluates to true. Optionally one can send along a meaningful message should the assertion fail.
assert(true, "Not true!")
Assertion.assert.raised? do
assert(false, "Not true!")
end
Assert with a Block
In addition assert has been extended to accept a block. Like the case of the argument, the block is expected to return something that evaluates as true.
assert do
true
end
Assertion.assert.raised? do
assert do
false
end
end
We should also mention that, while probably not very useful, since the arity of a block can be checked, one can also pass the receiver into the block as a block argument.
"hi".assert do |s|
/h/ =~ s
end
Antonyms for Assert
We can state the opposite assertion using assert!.
10.assert! == 9
Or, because some people do not like the use of a bang method, refute.
10.refute == 9
These terms can be used just as assert is used in all examples, but with the opposite inference.
Another way to get the opposite inference, is to use not.
10.assert.not == 9
Identity Assertions
Rather then the general form:
x = 10 x.assert.object_id == x.object_id
We can use Ruby’s own equal? method.
x.assert.equal?(x)
AE provides identical? method as an alternative to make it a bit more clear.
x.assert.identical?(x)
Equality Assertions
The most common assertion is that of value equality (==), as we have seen throughout this document. But other forms of equality can be verified as easily. We have already mentioned identity. In addition there is type equality.
17.assert.eql? 17
Assertion.assert.raised? do
17.assert.eql? 17.0
end
And there is case equality.
Numeric.assert === 3
Checking Equality with a Block
Because operators can not take blocks, and at times blocks can be convenient means of supplying a value to an assertion, AE has defined alternate renditions of the equality methods. For equal? and eql?, the method names are the same, they simply can take a block in place of an argument if need be.
For value equality (==), the method is called eq?.
10.assert.eq? do
10.0
end
And should it fail…
Assertion.assert.raised? do
10.assert.eq? do
20
end
end
For case equality (===), it is case?.
Numeric.assert.case? do
"3".to_i
end
Assertion.assert.raised? do
Numeric.assert.case? do
"3"
end
end
Exception Assertions
Validating errors is easy too, as has already been shown in the document to verify assertion failures.
StandardError.assert.raised? do
unknown_method
end
Assertions on Object State
While testing or specifying the internal state of an object is generally considered poor form, there are times when it is necessay. Assert combined with instance_eval makes it easy too.
class X
attr :a
def initialize(a); @a = a; end
end
x = X.new(1)
x.assert.instance_eval do
@a == 1
end
Catch/Try Assertions
Catch/Try throws can be tested via Symbol#thrown?.
:hookme.assert.thrown? do
throw :hookme
end
Alternatively, a lambda containing the potential throw can be the receiver using throws?.
hook = lambda{ throw :hookme }
hook.assert.throws?(:hookme)
Assertions on Proc Changes
I have to admit I’m not sure how this is useful, but I found it in the Bacon API and ported it over just for sake of thoroughness.
a = 0
l = lambda{ a }
l.assert.change?{ a +=1 }
Assertion on literal True, False and Nil
Ruby already provides the #nil? method.
nil.assert.nil?
AE adds true? and false? which acts accordingly.
true.assert.true? false.assert.false?
Send Assertions
Assert that a method can be successfully called.
"STRING".assert.send?(:upcase)
Numeric Delta and Epsilon
You may wish to assert that a numeric value is with some range.
3.in_delta?(1,5)
Or minimum range.
3.in_epsilon?(3,5)
Custom Lambda Assertions
Passing a lambda to the subjunctive method, will use it as if it were a block of the method. This allows for a simple way to quickly create reusable assertions.
palindrome = lambda{ |x| x == x.reverse }
"abracarba".assert palindrome
Verifying Object State
NOTE: This functionality is not currently supported, but is being considered for a future version.
If no block parameter is designated and the receiver differs from self in scope of the given block, then the block is evaluated in the scope of the receiver via instance_eval. This can be also be used to verify the state of an object.
class X
attr :a
def initialize(a); @a = a; end
end
x = X.new(4)
x.must do
4 == @a
end
And should it fail…
Assertion.assert.raised? do
x.must do
5 == @a
end
end
For some this might be considered poor form, i.e. to test underlying implementation. You will get no argument here. It should be used thoughtfully, but I would not bet against there being occasions when such validations might be handy.
Subjunctives
Okay. I can hear the BDDers rumbling, "where’s the should?" AE has nothing against "should", but there are different approaches for utilizing should nomenclature in specifications, and AE wants to be open to these techniques. One of which is how Shoulda (http://shoulda.rubyforge.org) utilizes should in a way analogous to RSpec’s use of it.
Even so, AE provides a an optional mixin called Subjunctive which can be used to create assertor methods with English subjunctive terms, such as should, or must, shall and will. To load this library use:
require 'ae/subjunctive'
Then all that is required it to define your subjunctive method for all objects. For example:
def will(*args, &block)
Assertor.new(self, :backtrace=>caller).be(*args,&block)
end
It’s that easy. Because of their popularity AE provides two such terms, should and must as optional add-ons.
require 'ae/subjunctive/should' require 'ae/subjunctive/must'
We will use these two methods interchangeable for the rest of this demonstration, but to be clear they both work exactly the same way, and almost exactly like assert.
Keep in mind, AE "conical" functionality does not entail subjunctive forms. These are simply options you can load via your test_helper.rb, or similar script, if you prefer these nomenclatures.
Fluent Notation and Antonyms
Like assert, should and must can be used as higher order functions.
4.should == 4 4.must == 4
With the antonym of should! (read "should not") or shouldnt, and for must, must! and wont.
4.should! == 5 4.shouldnt == 5 4.must! == 5 4.wont == 5
To Be
On occasions where the English readability of a specification is hindered, be can be used.
StandardError.must.be.raised? do
unknown_method
end
The be method is the same as assert with the single exception that it will compare a lone argument to the receiver using +equate?+, unlike assert which simply checks to see that the argument evalutates as true.
10.should.be 10
10.should.be 10.0
10.should.be Numeric
Assertion.assert.raised? do
10.should.be "40"
end
Indefinite Articles
Addtional English forms are a and an, equivalent to be except that they use case? instead of equate? when acting on a single argument.
"hi".must.be.a String
Assertion.assert.raised? do
/x/.must.be.a /x/
end
Otherwise they are interchangeble.
"hi".must.be.an.instance_of?(String)
The indefinite articles work well when a noun follows as an arguments.
palindrome = lambda{ |x| x == x.reverse }
"abracarba".must.be.a palindrome
QED.