Documentation for expectations and matchers

This commit is contained in:
Michael Miller 2018-10-07 12:42:09 -06:00
parent d98bc05b88
commit 38da6615bf
7 changed files with 48 additions and 0 deletions

View file

@ -2,6 +2,8 @@ module Spectator::Expectations
# Min-in for all expectation types.
# Classes that include this must implement
# the `#satisfied?`, `#message`, and `#negated_message` methods.
# Typically, expectation classes/structs store an `ExpectationPartial`
# and a `Matchers::Matcher` and then proxy calls to those instances.
module Expectation
# Checks whether the expectation is met.
abstract def satisfied? : Bool

View file

@ -4,6 +4,8 @@ module Spectator::Expectations
# The part of the expectation this class covers is the actual value.
# This can also cover a block's behavior.
# Sub-types of this class are returned by the `DSL::ExampleDSL.expect` call.
# Sub-types are expected to implement their own variation
# of the `#to` and `#not_to` methods.
abstract struct ExpectationPartial
# User-friendly string displayed for the actual expression being tested.
# For instance, in the expectation:

View file

@ -1,9 +1,15 @@
require "./expectation"
module Spectator::Expectations
# Expectation that operates on values.
# There are two values - the actual and expected.
# The actual value is what the SUT returned.
# The expected value is what the test wants to see.
struct ValueExpectation(ActualType, ExpectedType)
include Expectation
# Creates the expectation.
# This simply takes in the expectation partial and the matcher.
def initialize(@partial : ValueExpectationPartial(ActualType),
@matcher : Matchers::ValueMatcher(ExpectedType))
end

View file

@ -1,19 +1,27 @@
require "./expectation_partial"
module Spectator::Expectations
# Expectation partial variation that operates on a value.
struct ValueExpectationPartial(ActualType) < ExpectationPartial
# Actual value produced by the test.
# This is the value passed to the `#expect` call.
getter actual
# Creates the expectation partial.
protected def initialize(label : String, @actual : ActualType)
super(label)
end
# Asserts that the `#actual` value matches some criteria.
# The criteria is defined by the matcher passed to this method.
def to(matcher : Matchers::ValueMatcher(ExpectedType)) : Nil forall ExpectedType
expectation = ValueExpectation.new(self, matcher)
result = expectation.eval
ExpectationRegistry.current.report(result)
end
# Asserts that the `#actual` value *does not* match some criteria.
# This is effectively the opposite of `#to`.
def to_not(matcher : Matchers::ValueMatcher(ExpectedType)) : Nil forall ExpectedType
expectation = ValueExpectation.new(self, matcher)
result = expectation.eval(true)

View file

@ -1,15 +1,23 @@
require "./value_matcher"
module Spectator::Matchers
# Common matcher that tests whether two values equal each other.
# The values are compared with the `==` operator.
struct EqualityMatcher(ExpectedType) < ValueMatcher(ExpectedType)
# Determines whether the matcher is satisfied with the value given to it.
# True is returned if the match was successful, false otherwise.
def match?(partial : Expectations::ValueExpectationPartial(ActualType)) : Bool forall ActualType
partial.actual == expected
end
# Describes the condition that satisfies the matcher.
# This is informational and displayed to the end-user.
def message(partial : Expectations::ValueExpectationPartial(ActualType)) : String forall ActualType
"Expected #{partial.label} to equal #{label} (using ==)"
end
# Describes the condition that won't satsify the matcher.
# This is informational and displayed to the end-user.
def negated_message(partial : Expectations::ValueExpectationPartial(ActualType)) : String forall ActualType
"Expected #{partial.label} to not equal #{label} (using ==)"
end

View file

@ -1,7 +1,14 @@
module Spectator::Matchers
# Common base class for all expectation conditions.
# A matcher looks at something produced by the SUT
# and evaluates whether it is correct or not.
abstract struct Matcher
# Textual representation of what the matcher expects.
# This shouldn't be used in the conditional logic,
# but for verbose output to help the end-user.
private getter label : String
# Creates the base of the matcher.
private def initialize(@label)
end
end

View file

@ -1,17 +1,32 @@
require "./matcher"
module Spectator::Matchers
# Category of matcher that uses a value.
# Matchers of this type expect that a SUT applies to the value in some way.
# Sub-types must implement `#match`, `#message`, and `#negated_message`.
# Those methods accept a `ValueExpectationPartial` to work with.
abstract struct ValueMatcher(ExpectedType) < Matcher
# Expected value.
# Sub-types may use this value to test the expectation and generate message strings.
private getter expected
# Creates the value matcher.
# The label should be a string representation of the expectation.
# The expected value is stored for later use.
def initialize(label : String, @expected : ExpectedType)
super(label)
end
# Determines whether the matcher is satisfied with the value given to it.
# True is returned if the match was successful, false otherwise.
abstract def match?(partial : ValueExpectationPartial(ActualType)) : Bool forall ActualType
# Describes the condition that satisfies the matcher.
# This is informational and displayed to the end-user.
abstract def message(partial : ValueExpectationPartial(ActualType)) : String forall ActualType
# Describes the condition that won't satsify the matcher.
# This is informational and displayed to the end-user.
abstract def negated_message(partial : ValueExpectationPartial(ActualType)) : String forall ActualType
end
end