Add docs for ExampleGroup

This commit is contained in:
Michael Miller 2018-11-19 21:52:10 -07:00
parent e79d8872ac
commit ee274dbebd

View file

@ -1,40 +1,84 @@
require "./example_component" require "./example_component"
module Spectator module Spectator
# Shared base class for groups of examples.
#
# Represents a collection of examples and other groups.
# Use the `#each` methods to iterate through each child.
# However, these methods do not recurse into sub-groups.
# If you need that functionality, see `ExampleIterator`.
# Additionally, the indexer method (`#[]`) will index into sub-groups.
#
# This class also stores hooks to be associated with all examples in the group.
# The hooks can be invoked by running one of the `#run_x_hooks` methods.
abstract class ExampleGroup < ExampleComponent abstract class ExampleGroup < ExampleComponent
include Enumerable(ExampleComponent) include Enumerable(ExampleComponent)
include Iterable(ExampleComponent) include Iterable(ExampleComponent)
# Creates the example group.
# The hooks are stored to be triggered later.
def initialize(@hooks : ExampleHooks) def initialize(@hooks : ExampleHooks)
@before_all_hooks_run = false @before_all_hooks_run = false
@after_all_hooks_run = false @after_all_hooks_run = false
end end
# Retrieves the children in the group.
# This only returns the direct descends (non-recursive).
# The children must be set (with `#children=`) prior to calling this method.
getter! children : Array(ExampleComponent) getter! children : Array(ExampleComponent)
# Sets the children of the group.
# This should be called only from a builder in the `DSL` namespace.
# The children can be set only once -
# attempting to set more than once will raise an error.
# All sub-groups' children should be set before setting this group's children.
def children=(children : Array(ExampleComponent)) def children=(children : Array(ExampleComponent))
raise "Attempted to reset example group children" if @children raise "Attempted to reset example group children" if @children
@children = children @children = children
# Recursively count the number of examples.
# This won't work if a sub-group hasn't had their children set (is still nil).
@example_count = children.sum(&.example_count) @example_count = children.sum(&.example_count)
end end
# Yields each direct descendant.
def each def each
children.each do |child| children.each do |child|
yield child yield child
end end
end end
# Returns an iterator for each direct descendant.
def each : Iterator(ExampleComponent) def each : Iterator(ExampleComponent)
children.each children.each
end end
# Number of examples in this group and all sub-groups.
getter example_count = 0 getter example_count = 0
# Retrieves an example by its index.
# This recursively searches for an example.
#
# Positive and negative indices can be used.
# Any value out of range will raise an `IndexError`.
#
# Examples are indexed as if they are in a flattened tree.
# For instance:
# ```
# examples = [0, 1, [2, 3, 4], [5, [6, 7], 8], 9, [10]].flatten
# ```
# The arrays symbolize groups,
# and the numbers are the index of the example in that slot.
def [](index : Int) : Example def [](index : Int) : Example
offset = check_bounds(index) offset = check_bounds(index)
find_nested(offset) find_nested(offset)
end end
# Checks whether an index is within acceptable bounds.
# If the index is negative,
# it will be converted to its positive equivalent.
# If the index is out of bounds, an `IndexError` is raised.
# If the index is in bounds,
# the positive index is returned.
private def check_bounds(index) private def check_bounds(index)
if index < 0 if index < 0
raise IndexError.new if index < -example_count raise IndexError.new if index < -example_count
@ -45,22 +89,43 @@ module Spectator
end end
end end
# Finds the example with the specified index in the children.
# The `index` must be positive and within bounds (use `#check_bounds`).
private def find_nested(index) private def find_nested(index)
offset = index offset = index
# Loop through each child
# until one is found to contain the index.
child = children.each do |child| child = children.each do |child|
count = child.example_count count = child.example_count
# Example groups consider their range to be [0, example_count).
# Each child is offset by the total example count of the previous children.
# The group exposes them in this way:
# 1. [0, example_count of group 1)
# 2. [example_count of group 1, example_count of group 2)
# 3. [example_count of group n, example_count of group n + 1)
# To iterate through children, the offset is tracked.
# Each iteration removes the previous child's count.
# This way the child receives the expected range.
break child if offset < count break child if offset < count
offset -= count offset -= count
end end
# The remaining offset is passed along to the child.
# If it's an `Example`, it returns itself.
# Otherwise, the indexer repeats the process for the next child.
# It should be impossible to get `nil` here, # It should be impossible to get `nil` here,
# provided the bounds check and example counts are correct. # provided the bounds check and example counts are correct.
child.not_nil![offset] child.not_nil![offset]
end end
# Checks whether all examples in the group have been run.
def finished? : Bool def finished? : Bool
children.all?(&.finished?) children.all?(&.finished?)
end end
# Runs all of the `before_all` hooks.
# This should run prior to any examples in the group.
# The hooks will be run only once.
# Subsequent calls to this method will do nothing.
def run_before_all_hooks : Nil def run_before_all_hooks : Nil
unless @before_all_hooks_run unless @before_all_hooks_run
@hooks.run_before_all @hooks.run_before_all
@ -68,10 +133,17 @@ module Spectator
end end
end end
# Runs all of the `before_each` hooks.
# This method should run prior to every example in the group.
def run_before_each_hooks : Nil def run_before_each_hooks : Nil
@hooks.run_before_each @hooks.run_before_each
end end
# Runs all of the `after_all` hooks.
# This should run following all examples in the group.
# The hooks will be run only once,
# and only after all examples in the group have finished.
# Subsequent calls after the hooks have been run will do nothing.
def run_after_all_hooks : Nil def run_after_all_hooks : Nil
unless @after_all_hooks_run unless @after_all_hooks_run
if finished? if finished?
@ -81,10 +153,16 @@ module Spectator
end end
end end
# Runs all of the `after_each` hooks.
# This method should run following every example in the group.
def run_after_each_hooks : Nil def run_after_each_hooks : Nil
@hooks.run_after_each @hooks.run_after_each
end end
# Creates a proc that runs the `around_each` hooks
# in addition to a block passed to this method.
# To call the block and all `around_each` hooks,
# just invoke `Proc#call` on the returned proc.
def wrap_around_each_hooks(&block : ->) : -> def wrap_around_each_hooks(&block : ->) : ->
@hooks.wrap_around_each(&block) @hooks.wrap_around_each(&block)
end end