Assay is an foundational assertion framework.

# Assay Classes

## NilAssay

The ‘NilAssay` asserts that an object reference is `nil`. Reference to any other object will fail.

assert NilAssay.pass?(nil)

refute NilAssay.pass?(true)
refute NilAssay.pass?(false)
refute NilAssay.pass?("foo")

And conversely,

assert NilAssay.fail?(true)
assert NilAssay.fail?(false)
assert NilAssay.fail?("foo")

refute NilAssay.fail?(nil)

Making assertions,

assert NilAssay.assert!(nil)

expect ::NilAssay do
  NilAssay.assert!(true)
end

And refutations,

assert NilAssay.refute!(true)

expect ::NilAssay do
  NilAssay.refute!(nil)
end

## BooleanAssay

The ‘BooleanAssay` asserts that an object reference is `nil`. Reference to any other object will fail.

assert BooleanAssay.pass?(true)
assert BooleanAssay.pass?(false)

refute BooleanAssay.pass?(nil)
refute BooleanAssay.pass?("foo")

And conversely,

assert BooleanAssay.fail?(nil)
assert BooleanAssay.fail?("foo")

refute BooleanAssay.fail?(true)
refute BooleanAssay.fail?(false)

Making assertions,

assert BooleanAssay.assert!(true)

expect ::BooleanAssay do
  BooleanAssay.assert!(nil)
end

And refutations,

assert BooleanAssay.refute!(nil)

expect ::BooleanAssay do
  BooleanAssay.refute!(true)
end

## FalseAssay

The ‘FalseAssay` class asserts that an object is `false. Reference to any other object will fail.

assert FalseAssay.pass?(false)

refute FalseAssay.pass?(true)
refute FalseAssay.pass?(nil)
refute FalseAssay.pass?('foo')

And conversely,

assert FalseAssay.fail?(true)
assert FalseAssay.fail?(nil)
assert FalseAssay.fail?('foo')

refute FalseAssay.fail?(false)

## TrueAssay

The ‘TrueAssay` class asserts that an object is `true`. Reference to any other object will fail.

assert TrueAssay.pass?(true)

refute TrueAssay.pass?(false)
refute TrueAssay.pass?(nil)
refute TrueAssay.pass?('foo')

And conversely,

assert TrueAssay.fail?(false)
assert TrueAssay.fail?(nil)
assert TrueAssay.fail?('foo')

refute TrueAssay.fail?(true)

## LikeAssay

The ‘LikeAssay` is a very … assertion. It is a comparison that evaluates to true for any of Ruby’s many “equal” operators, ‘equal?` (same as `identical?`), `eql?`, `==`, `===` and `=~`. If any one of these evaluates to true, than two objects can be said to be alike.

assert LikeAssay.pass?(1, 1)
assert LikeAssay.pass?(1, 1.0)
assert LikeAssay.pass?("1", /\d/)

refute LikeAssay.pass?(1, "1")
refute LikeAssay.pass?("1", /\D/)

And conversely,

assert LikeAssay.fail?(1, "1")
assert LikeAssay.fail?("1", /\D/)

## EqualAssay

The ‘EqualAssay` class defines an assertion for equality based on the `==` method.

assert EqualAssay.pass?(1, 1)
assert EqualAssay.pass?(1, 1.0)

refute EqualAssay.pass?(1, 2)
refute EqualAssay.pass?(1, 'foo')

And conversely,

assert EqualAssay.fail?(1, 2)
assert EqualAssay.fail?(1, 'foo')

refute EqualAssay.fail?(1, 1)
refute EqualAssay.fail?(1, 1.0)

## UnequalAssay

The ‘UnequalAssay` class defines an assertion for equality based on the `!=` method, which in Ruby 1.8 is a redefinable method all it’s own.

assert UnequalAssay.pass?(1, 2)
assert UnequalAssay.pass?(1, 'foo')

refute UnequalAssay.pass?(1, 1)
refute UnequalAssay.pass?(1, 1.0)

And conversely,

assert UnequalAssay.fail?(1, 1)
assert UnequalAssay.fail?(1, 1.0)

refute UnequalAssay.fail?(1, 2)
refute UnequalAssay.fail?(1, 'foo')

Making assertions,

assert UnequalAssay.assert!(10, 20)

expect ::UnequalAssay do
  UnequalAssay.assert!(10, 10)
end

And refutations,

assert UnequalAssay.refute!(10, 10)

expect ::UnequalAssay do
  UnequalAssay.refute!(10, 20)
end

## EqualityAssay

The ‘EqualityAssay` class defines an assertion for strict equality via the `eql?` method.

assert EqualityAssay.pass?(1, 1)

refute EqualityAssay.pass?(1, 1.0)
refute EqualityAssay.pass?(1, 2)
refute EqualityAssay.pass?(1, 'foo')

And conversely,

assert EqualityAssay.fail?(1, 2)
assert EqualityAssay.fail?(1, 1.0)
assert EqualityAssay.fail?(1, 'foo')

refute EqualityAssay.fail?(1, 1)

## IdentityAssay

The ‘IdentityAssay` class defines an assertion for identity comparison via the `#identical?` method, which is an alias for the `#equal?` method. We have choosen not to use the term `equal` to avoid confusion with the ordinary `==` type of equality.

assert IdentityAssay.pass?(1, 1)
assert IdentityAssay.pass?(:a, :a)

refute IdentityAssay.pass?('a', 'a')
refute IdentityAssay.pass?(1, 1.0)
refute IdentityAssay.pass?(1, 2)
refute IdentityAssay.pass?(1, 'foo')

And conversely,

assert IdentityAssay.fail?(1, 2)
assert IdentityAssay.fail?(1, 1.0)
assert IdentityAssay.fail?(1, 'foo')
assert IdentityAssay.fail?('a', 'a')

refute IdentityAssay.fail?(1, 1)
refute IdentityAssay.fail?(:a, :a)

## CaseAssay

The ‘CaseAssay` class defines an assertion for case equality using the `#===` method.

assert CaseAssay.pass?(1, 1)
assert CaseAssay.pass?(1, 1.0)
assert CaseAssay.pass?(/a/, 'a')
assert CaseAssay.pass?(String, 'foo')

refute CaseAssay.pass?(1, 2)
refute CaseAssay.pass?(1, 'foo')

And conversely,

assert CaseAssay.fail?(1, 2)
assert CaseAssay.fail?(1, 'foo')

refute CaseAssay.fail?(1, 1)
refute CaseAssay.fail?(1, 1.0)
refute CaseAssay.fail?(/a/, 'a')
refute CaseAssay.fail?(String, 'foo')

## MatchAssay

The ‘MatchAssay` class defines an assertion for matching using the `#=~` method.

assert MatchAssay.pass?('a', /a/)

refute MatchAssay.pass?('a', /b/)

And conversely,

assert MatchAssay.fail?('a', /b/)

refute MatchAssay.fail?('a', /a/)

## NoMatchAssay

The ‘NoMatchAssay` class defines an assertion for matching using the `#!~` method. As of Ruby 1.9, the `#!~` method is redefinable independent of `#=~`, so a separate assertion class is needed to cover it.

assert NoMatchAssay.pass?('a', /b/)

refute NoMatchAssay.pass?('a', /a/)

And conversely,

assert NoMatchAssay.fail?('a', /a/)

refute NoMatchAssay.fail?('a', /b/)

## CompareAssay

The ‘CompareAssay` class defines an assertion of comparison around the `#<=>` method. Since `#<=>` can return either a `1`, `0` or `-1`, an extra criterion is needed when making testing the assertion.

assert CompareAssay.pass?(1, 1,  0)
assert CompareAssay.pass?(1, 2, -1)
assert CompareAssay.pass?(2, 1,  1)

refute CompareAssay.pass?(1, 1,  1)
refute CompareAssay.pass?(1, 1, -1)

refute CompareAssay.pass?(1, 'foo', 0)

And conversely,

assert CompareAssay.fail?(1, 1,  1)
assert CompareAssay.fail?(1, 1, -1)

refute CompareAssay.fail?(1, 1,  0)
refute CompareAssay.fail?(1, 2, -1)
refute CompareAssay.fail?(2, 1,  1)

## LessAssay

The ‘LessAssay` class defines an assertion of comparison around the `#<` method. This method usually depends on the `#<=>` method via Ruby’s Comparable mixin, so ‘LessAssay` is a subclass of `ComapreAssay`, though techincally the `#<` method can be defined independently.

assert LessAssay.pass?( 1, 2)
assert LessAssay.pass?(-1, 0)

refute LessAssay.pass?(1, 1)
refute LessAssay.pass?(1, 0)

And conversely,

assert LessAssay.fail?(1, 1)
assert LessAssay.fail?(1, 0)

refute LessAssay.fail?( 1, 2)
refute LessAssay.fail?(-1, 0)

This applies to any type of object that defines ‘#<=`, not just numbers.

assert LessAssay.pass?('a', 'b')
refute LessAssay.pass?('b', 'a')

assert LessAssay.fail?('b', 'a')
refute LessAssay.fail?('a', 'b')

## MoreAssay

The ‘MoreAssay` class defines an assertion of comparison around the `#>` method. This method usually depends on the `#<=>` method via Ruby’s Comparable mixin, so ‘MoreAssay` is a subclass of `ComapreAssay`, though techincally the `#>` method can be defined indenpendently.

assert MoreAssay.pass?(2,  1)
assert MoreAssay.pass?(0, -1)
assert MoreAssay.pass?(1,  0)

refute MoreAssay.pass?(1, 1)
refute MoreAssay.pass?(1, 2)

And conversely,

assert MoreAssay.fail?(1, 1)
assert MoreAssay.fail?(0, 1)

refute MoreAssay.fail?(2,  1)
refute MoreAssay.fail?(0, -1)

This applies to any type of object that defines ‘#>`, not just numbers.

assert MoreAssay.pass?('b', 'a')
refute MoreAssay.pass?('a', 'b')

assert MoreAssay.fail?('a', 'b')
refute MoreAssay.fail?('b', 'a')

## LessEqualAssay

The ‘LessEqualAssay` class defines an assertion of comparison around the `#<=` method. This method usually depends on the `#<=>` method via Ruby’s Comparable mixin, so ‘LessEqualAssay` is a subclass of `ComapreAssay`, though techincally the `#<=` method can be defined indenpendently.

assert LessEqualAssay.pass?( 1, 2)
assert LessEqualAssay.pass?(-1, 0)
assert LessEqualAssay.pass?( 1, 1)

refute LessEqualAssay.pass?(1, 0)

And conversely,

assert LessEqualAssay.fail?(1, 0)

refute LessEqualAssay.fail?( 1, 1)
refute LessEqualAssay.fail?( 1, 2)
refute LessEqualAssay.fail?(-1, 0)

This applies to any type of object that defines ‘#<=`, not just numbers.

assert LessEqualAssay.pass?('a', 'b')
refute LessEqualAssay.pass?('b', 'a')

assert LessEqualAssay.fail?('b', 'a')
refute LessEqualAssay.fail?('a', 'b')

## MoreEqualAssay

The ‘MoreEqualAssay` class defines an assertion of comparison around the `#>=` method. This method usually depends on the `#<=>` method via Ruby’s Comparable mixin, so ‘MoreEqualAssay` is a subclass of `ComapreAssay`, though techincally the `#>=` method can be defined indenpendently.

assert MoreEqualAssay.pass?(2,  1)
assert MoreEqualAssay.pass?(0, -1)
assert MoreEqualAssay.pass?(1,  1)

refute MoreEqualAssay.pass?(0, 1)

And conversely,

assert MoreEqualAssay.fail?(0, 1)

refute MoreEqualAssay.fail?( 1, 1)
refute MoreEqualAssay.fail?( 2, 1)
refute MoreEqualAssay.fail?( 0, -1)

This applies to any type of object that defines ‘#<=`, not just numbers.

assert MoreEqualAssay.pass?('b', 'a')
refute MoreEqualAssay.pass?('a', 'b')

assert MoreEqualAssay.fail?('a', 'b')
refute MoreEqualAssay.fail?('b', 'a')

## CloseAssay

The ‘CloseAssay` class defines an assertion for matching that two values are within a relative difference.

assert CloseAssay.pass?(1, 1,   0)
assert CloseAssay.pass?(1, 1.1, 0.1)

refute CloseAssay.pass?(1, 2,   0)
refute CloseAssay.pass?(1, 1.2, 0.1)

And conversely,

assert CloseAssay.fail?(1, 2,   0)
assert CloseAssay.fail?(1, 1.2, 0.1)

refute CloseAssay.fail?(1, 1,   0)
refute CloseAssay.fail?(1, 1.1, 0.1)

The object do not have to be numbers necessaity, just so long as they are comparable and subtractable.

time = Time.now

assert CloseAssay.pass?(time, time+1, 2)

Making assertions,

assert CloseAssay.assert!(10, 11, 1)

expect ::CloseAssay do
  CloseAssay.assert!(10, 15, 0.25)
end

And refutations,

assert CloseAssay.refute!(10, 11, 0.01)

expect ::CloseAssay do
  CloseAssay.refute!(10, 11, 1)
end

## WithinAssay

The ‘WithinAssay` class defines an assertion for matching that two values lie with a range.

assert WithinAssay.pass?(1, 1,   0)
assert WithinAssay.pass?(1, 1.1, 0.1)

refute WithinAssay.pass?(1, 2,   0)
refute WithinAssay.pass?(1, 1.2, 0.1)

And conversely,

assert WithinAssay.fail?(1, 2,   0)
assert WithinAssay.fail?(1, 1.2, 0.1)

refute WithinAssay.fail?(1, 1,   0)
refute WithinAssay.fail?(1, 1.1, 0.1)

The object do not have to be numbers necessaity, just so long as they are comparable and subtractable.

time = Time.now

assert WithinAssay.pass?(time, time+1, 2)

Making assertions,

assert WithinAssay.assert!(10, 11, 1)

expect ::WithinAssay do
  WithinAssay.assert!(10, 15, 2)
end

And refutations,

assert WithinAssay.refute!(10, 11, 0.1)

expect ::WithinAssay do
  WithinAssay.refute!(10, 11, 1)
end

## KindAssay

The ‘KindAssay` asserts that an object is a class or any ancestor of that class.

assert KindAssay.pass?(1, Fixnum)
assert KindAssay.pass?(1, Numeric)

refute KindAssay.pass?(1, String)

And conversely,

assert KindAssay.fail?(1, String)

refute KindAssay.fail?(1, Fixnum)
refute KindAssay.fail?(1, Numeric)

## InstanceAssay

The ‘InstanceAssay` asserts that an object is an instance of a specific class.

assert InstanceAssay.pass?(1, Fixnum)

refute InstanceAssay.pass?(1, Numeric)
refute InstanceAssay.pass?(1, String)

And conversely,

assert InstanceAssay.fail?(1, String)
assert InstanceAssay.fail?(1, Numeric)

refute InstanceAssay.fail?(1, Fixnum)

## IncludeAssay

The ‘IncludeAssay` asserts that a collection includes a specific member, using the `#include?` method.

assert IncludeAssay.pass?([1], 1)

refute IncludeAssay.pass?([],  1)
refute IncludeAssay.pass?([2], 1)

And conversely,

assert IncludeAssay.fail?([],  1)
assert IncludeAssay.fail?([2], 1)

refute IncludeAssay.fail?([1], 1)

## EmptyAssay

The ‘EmptyAssay` asserts that a collection includes no members, using the `#empty?` method.

assert EmptyAssay.pass?([])

refute EmptyAssay.pass?([1])

And conversely,

assert EmptyAssay.fail?([1])

refute EmptyAssay.fail?([])

## RespondAssay

The ‘RespondAssay` asserts if a an object responds to a message using then `#respond_to?` method.

assert RespondAssay.pass?('a', :to_s)

refute RespondAssay.pass?('a', :foo)

And conversely,

assert RespondAssay.fail?('a', :foo)

refute RespondAssay.fail?('a', :to_s)

## ExecutionAssay

The ‘ExecutionAssay` asserts that a procedure runs without error and returns a result other than `false` or `nil`. It is not particularly useful, because what it does is effectively what testing in itself does. So it is rather redundant. However, it serves as the base class for the more specific `ReturnAssay`.

assert ExecutionAssay.pass?{ true }
assert ExecutionAssay.pass?{ :foo }

refute ExecutionAssay.pass?{ nil }
refute ExecutionAssay.pass?{ false }
refute ExecutionAssay.pass?{ raise }

And conversely,

assert ExecutionAssay.fail?{ raise }
assert ExecutionAssay.fail?{ nil }
assert ExecutionAssay.fail?{ false }

refute ExecutionAssay.fail?{ true }
refute ExecutionAssay.fail?{ :foo }

Making assertions,

assert ExecutionAssay.assert!{ true }

expect ::ExecutionAssay do
  assert ExecutionAssay.assert!{ false }
end

And refutations,

assert ExecutionAssay.refute!{ false }

expect ::ExecutionAssay do
  assert ExecutionAssay.refute!{ true }
end

## ReturnAssay

The ‘ReturnAssay` asserts that a procedure runs without error and returns a specified result.

assert ReturnAssay.pass?(:foo){ :foo }
assert ReturnAssay.pass?(true){ true }

refute ReturnAssay.pass?(:foo){ :bar }
refute ReturnAssay.pass?(:foo){ true }
refute ReturnAssay.pass?(:foo){ raise }

And conversely,

assert ReturnAssay.fail?(:foo){ :bar }
assert ReturnAssay.fail?(:foo){ true }
assert ReturnAssay.fail?(:foo){ raise }

refute ReturnAssay.fail?(:foo){ :foo }
refute ReturnAssay.fail?(true){ true }

Making assertions,

assert ReturnAssay.assert!(true){ true }

expect ::ReturnAssay do
  assert ReturnAssay.assert!(:foo){ :bar }
end

And refutations,

assert ReturnAssay.refute!(:foo){ :bar }

expect ::ReturnAssay do
  assert ReturnAssay.refute!(:foo){ :foo }
end

## RescueAssay

The ‘RescueAssay` asserts that a procedure will raise a specific error.

assert RescueAssay.pass?{ raise }
assert RescueAssay.pass?(RuntimeError){ raise }
assert RescueAssay.pass?(ArgumentError){ raise ArgumentError }
assert RescueAssay.pass?(Exception){ raise ArgumentError }

refute RescueAssay.pass?{ raise Exception }
refute RescueAssay.pass?(RuntimeError){ nil }
refute RescueAssay.pass?(ArgumentError){ raise }

And conversely,

assert RescueAssay.fail?{ raise Exception }
assert RescueAssay.fail?(RuntimeError){ nil }
assert RescueAssay.fail?(ArgumentError){ raise }

refute RescueAssay.fail?{ raise }
refute RescueAssay.fail?(RuntimeError){ raise }
refute RescueAssay.fail?(ArgumentError){ raise ArgumentError }
refute RescueAssay.fail?(Exception){ raise ArgumentError }

Making assertions,

assert RescueAssay.assert!(RuntimeError){ raise }

expect ::RescueAssay do
  RaiseAssay.assert!(RuntimeError){ nil }
end

And refutations,

assert RescueAssay.refute!(RuntimeError){ nil }

expect ::RescueAssay do
  RaiseAssay.refute!(RuntimeError){ raise }
end

## RaiseAssay

The ‘RaiseAssay` asserts that a procedure will raise a specific error.

assert RaiseAssay.pass?{ raise }
assert RaiseAssay.pass?(RuntimeError){ raise }
assert RaiseAssay.pass?(ArgumentError){ raise ArgumentError }

refute RaiseAssay.pass?{ raise Exception }
refute RaiseAssay.pass?(Exception){ raise ArgumentError }
refute RaiseAssay.pass?(StandardError){ nil }
refute RaiseAssay.pass?(ArgumentError){ raise }

And conversely,

assert RaiseAssay.fail?{ raise Exception }
assert RaiseAssay.fail?(RuntimeError){ nil }
assert RaiseAssay.fail?(ArgumentError){ raise }
assert RaiseAssay.fail?(Exception){ raise ArgumentError }

refute RaiseAssay.fail?{ raise }
refute RaiseAssay.fail?(RuntimeError){ raise }
refute RaiseAssay.fail?(ArgumentError){ raise ArgumentError }

Making assertions,

assert RaiseAssay.assert!(RuntimeError){ raise }

expect ::RaiseAssay do
  RaiseAssay.assert!(RuntimeError){ nil }
end

And refutations,

assert RaiseAssay.refute!(RuntimeError){ nil }

expect ::RaiseAssay do
  RaiseAssay.refute!(RuntimeError){ raise }
end

## ThrowAssay

The ‘ThrowAssay` asserts that a procedure will call `throw` and optionally of a specific type.

assert ThrowAssay.pass?(:foo){ throw :foo }
refute ThrowAssay.pass?(:foo){ throw :bar }

And conversely,

assert ThrowAssay.fail?(:foo){ throw :bar }
refute ThrowAssay.fail?(:foo){ throw :foo }

In addition ‘ThrowAssay` can assert that there is a throw, regardless of tag.

assert ThrowAssay.pass?{ throw :foo }
refute ThrowAssay.pass?{ nil }

And converselry,

assert ThrowAssay.fail?{ nil }
refute ThrowAssay.fail?{ throw :bar }

Making assertions, notice that the ‘#assert!` method requires a `nil` argument in order to test for any throw. This is not needed on the `#pass?` method because the `#pass` method can’t take aditional options for setting the message or backtrace.

assert ThrowAssay.assert!(nil){ throw :foo }

assert ThrowAssay.assert!(nil, :message=>"optional message"){
  throw :foo
}

expect ThrowAssay do
  ThrowAssay.assert!(nil){ 'nothing' }
end

And refutations,

assert ThrowAssay.refute!(:foo){ throw :bar }

expect ThrowAssay do
  ThrowAssay.refute!(:foo){ throw :foo }
end

## PathAssay

The ‘PathAssay` asserts that a file-system path exists.

file = __FILE__
dir  = File.dirname(file)
dne  = __FILE__ + '~'

assert PathAssay.pass?(file)
assert PathAssay.pass?(dir)

refute PathAssay.pass?(dne)

And conversely,

assert PathAssay.fail?(dne)

refute PathAssay.fail?(file)
refute PathAssay.fail?(dir)

## DirectoryAssay

The ‘DirectoryAssay` asserts that a file-system path exists and it is a directory.

file = __FILE__
dir  = File.dirname(file)
dne  = __FILE__ + '~'

assert DirectoryAssay.pass?(dir)

refute DirectoryAssay.pass?(file)
refute DirectoryAssay.pass?(dne)

And conversely,

assert DirectoryAssay.fail?(file)
assert DirectoryAssay.fail?(dne)

refute DirectoryAssay.fail?(dir)

## FileAssay

The ‘FileAssay` asserts that a file-system path exists and it is a file.

file = __FILE__
dir  = File.dirname(file)
dne  = __FILE__ + '~'

assert FileAssay.pass?(file)

refute FileAssay.pass?(dir)
refute FileAssay.pass?(dne)

And conversely,

assert FileAssay.fail?(dir)
assert FileAssay.fail?(dne)

refute FileAssay.fail?(file)

## OutputAssay

The ‘OutputAssay` asserts that a output is sent to either `$stdout` or `$stderr`.

Let’s do the simple stdout case first.

assert OutputAssay.pass?('foo'){ puts 'foo' }

refute OutputAssay.pass?('foo'){ nil }
refute OutputAssay.pass?('foo'){ puts 'bar' }

And conversely,

refute OutputAssay.fail?('foo'){ puts 'foo' }

assert OutputAssay.fail?('foo'){ nil }
assert OutputAssay.fail?('foo'){ puts 'bar' }

Now the same for ‘$stderr`.

assert OutputAssay.pass?('foo'){ $stderr.puts 'foo' }

refute OutputAssay.pass?('foo'){ nil }
refute OutputAssay.pass?('foo'){ $stderr.puts 'bar' }

And conversely,

refute OutputAssay.fail?('foo'){ $stderr.puts 'foo' }

assert OutputAssay.fail?('foo'){ nil }
assert OutputAssay.fail?('foo'){ $stderr.puts 'bar' }

The OutputAssay uses ‘#===` to test the match so we can also match against a regular expression.

assert OutputAssay.pass?(/f/){ puts 'foo' }

assert OutputAssay.pass?(/f/){ $stderr.puts 'foo' }

## StdoutAssay

The ‘StdoutAssay` asserts that a output is sent to `$stdout`.

assert StdoutAssay.pass?('foo'){ puts 'foo' }

refute StdoutAssay.pass?('foo'){ nil }
refute StdoutAssay.pass?('foo'){ puts 'bar' }

And conversely,

refute StdoutAssay.fail?('foo'){ puts 'foo' }

assert StdoutAssay.fail?('foo'){ nil }
assert StdoutAssay.fail?('foo'){ puts 'bar' }

The StdoutAssay uses ‘#===` to test the match so we can also match against a regular expression.

assert StdoutAssay.pass?(/f/){ puts 'foo' }

## StderrAssay

The ‘StderrAssay` asserts that a output is sent to `$stderr`.

assert StderrAssay.pass?('foo'){ $stderr.puts 'foo' }

refute StderrAssay.pass?('foo'){ nil }
refute StderrAssay.pass?('foo'){ $stderr.puts 'bar' }

And conversely,

refute StderrAssay.fail?('foo'){ $stderr.puts 'foo' }

assert StderrAssay.fail?('foo'){ nil }
assert StderrAssay.fail?('foo'){ $stderr.puts 'bar' }

The StderrAssay uses ‘#===` to test the match so we can also match against a regular expression.

assert StderrAssay.pass?(/f/){ $stderr.puts 'foo' }

# Asay Lookup

Assay classes are indexed by both name and associated operation, so they can be looked-up by either. The indexes are stored as class attributes of the Assertion base class.

Let’s lookup the class for ‘==` equality.

Assertion.by_operator(:==)      #=> ::EqualAssay

Let’s lookup the assertion class for ‘#empty?`.

Assertion.by_operator(:empty?)  #=> ::EmptyAssay

If we wish to lookup by assertive name instead of operator, we can use the ‘by_name` method instead.

Assertion.by_name(:empty)       #=> ::EmptyAssay

We can also use the ‘Assay.lookup` module method, which will lookup an assay class by either assertion name or associated operator.

Assay.lookup(:==)               #=> ::EqualAssay
Assay.lookup(:empty?)           #=> ::EmptyAssay

# Assay as Assertor

Assay classes can be converted to assertors, otherwise known as matchers in RSpec circles. The idea behind Assertors is that they can be initialized with pre-set criteria and then applied to target subjects.

## Standard Target Matching

assertor = EqualAssay[1]

assertor.assert!(1)

expect EqualAssay do
  assertor.assert!(2)
end

## Partial Arguments

assertor = LessAssay[1,__]

We can apply the assertor using the ‘#pass!` method.

assertor.assert!(2)

Likewise we can assert the negated expression using ‘#fail!`.

assertor.refute!(0)

Assay partial a very versile because they allow any argument to become the target of a assertor.

assertor = CompareAssay[2,1,__]

assertor.assert!(1)
assertor.refute!(0)

## Match Operator

The ‘#=~` method is an alias for `#assert!`.

assertor = EqualAssay[1]
assertor =~ 1

Conversely, ‘#!~` method is an alias for `#refute!`.

assertor !~ 2

## Case Operator

The ‘#===` method is also an alias for `#assert!`.

assertor === 1

This allows the ‘case` statement to be used in an intersting way.

case 10
when KindAssay[Numeric]
when EqualAssay[10.0]
end

## Negated Assertors

Assertors can also be negated so that pass and fail methods swap behaviors.

assertor = EqualityAssay[1]

assertor.not =~ 2
assertor.not !~ 1

For conveience we can also negate the assertor using the ‘~` unary operator.

!assertor === 2

## Just Cheking

Assertors can also be used just to test the assertion without actually raising the associated exception.

assertor = EqualityAssay[__,1]

assertor.pass?(1)
assertor.fail?(2)

## RSpec Compatability

RSpec compatibality is provided via neccessary method alias, in particular ‘#matches?` and `#does_not_match?`.

assertor = EqualityAssay[__,1]

assert assertor.matches?(1)
assert assertor.does_not_match?(2)

Error messages are handle by RSpec by ‘#failure_message_for_should` and `#failure_message_for_should_not`.

assertor.failure_message_for_should(1)
assertor.failure_message_for_should_not(2)

# Assay Class Methods

## Metadata

Assay support full project metadata access thanks to the ‘.ruby` standard.

Assay.metadata['name']  #=> 'assay'

The metadata also dynamically translates into constants, so we can work with this information in the traditional fashion.

Assay::NAME  #=> 'assay'

## Color Messages

We can have some Assay error messages use ANSI color output by setting the ‘Assay.color` setting to `true`.

Assay.color = true

Keep in mind that this requires the ‘ansi` library.

In particular it is the equality related assertions that utilize color output when the objects compared are large. This helps the developer pinpint the differences quickly.

expect EqualAssay do
  EqualAssay['really long string'] === 'other string'
end

## Lookup Assay Classes

Assay tracks all created Assay classes by both associated operation and assertive name.

Assay.lookup_by_operator(:==)  #=> EqualAssay

Assay.lookup_by_name(:equal)   #=> EqualAssay

We can look for either with just ‘lookup`.

Assay.lookup(:==)      #=> EqualAssay
Assay.lookup(:equal)   #=> EqualAssay