2018-09-27 21:49:34 +00:00
|
|
|
require "./spectator/includes"
|
2018-08-19 07:15:32 +00:00
|
|
|
|
2018-09-27 21:41:18 +00:00
|
|
|
# Module that contains all functionality related to Spectator.
|
2018-08-18 21:33:20 +00:00
|
|
|
module Spectator
|
2018-09-27 21:41:18 +00:00
|
|
|
# Current version of the Spectator library.
|
2018-08-18 21:33:20 +00:00
|
|
|
VERSION = "0.1.0"
|
|
|
|
|
2018-09-27 21:41:18 +00:00
|
|
|
# Top-level describe method.
|
|
|
|
# All specs in a file must be wrapped in this call.
|
|
|
|
# This takes an argument and a block.
|
|
|
|
# The argument is what your spec is describing.
|
|
|
|
# It can be any Crystal expression,
|
|
|
|
# but is typically a class name or feature string.
|
|
|
|
# The block should contain all of the specs for what is being described.
|
|
|
|
# Example:
|
|
|
|
# ```
|
|
|
|
# Spectator.describe Foo do
|
|
|
|
# # Your specs for `Foo` go here.
|
|
|
|
# end
|
|
|
|
# ```
|
|
|
|
# NOTE: Inside the block, the `Spectator` prefix is no longer needed.
|
|
|
|
# Actually, prefixing methods and macros with `Spectator`
|
|
|
|
# most likely won't work and can cause compiler errors.
|
2018-09-23 01:41:56 +00:00
|
|
|
macro describe(what, &block)
|
2018-09-27 21:41:18 +00:00
|
|
|
# This macro creates the foundation for all specs.
|
|
|
|
# Every group of examples is defined a separate module - `SpectatorExamples`.
|
|
|
|
# There's multiple reasons for this.
|
|
|
|
#
|
|
|
|
# The first reason is to provide namespace isolation.
|
|
|
|
# We don't want the spec code to accidentally pickup types and values from the `Spectator` module.
|
|
|
|
# Another reason is that we need a root module to put all examples and groups in.
|
|
|
|
# And lastly, the spec DSL needs to be given to the block of code somehow.
|
|
|
|
# The DSL is included in the `SpectatorExamples` module.
|
|
|
|
#
|
|
|
|
# For more information on how the DSL works, see the `DSL` module.
|
|
|
|
|
|
|
|
# Root-level module that contains all examples and example groups.
|
2018-09-23 18:02:51 +00:00
|
|
|
module SpectatorExamples
|
2018-09-27 21:41:18 +00:00
|
|
|
# Include the DSL for creating groups, example, and more.
|
2018-09-23 18:02:51 +00:00
|
|
|
include ::Spectator::DSL::StructureDSL
|
|
|
|
|
2018-09-27 21:41:18 +00:00
|
|
|
# Pass off the "what" argument and block to `DSL::StructureDSL.describe`.
|
|
|
|
# That method will handle creating a new group for this spec.
|
2018-09-23 18:02:51 +00:00
|
|
|
describe({{what}}) {{block}}
|
|
|
|
end
|
2018-08-19 07:15:32 +00:00
|
|
|
end
|
|
|
|
|
2018-10-15 06:32:29 +00:00
|
|
|
# Flag indicating whether Spectator should automatically run tests.
|
|
|
|
# This should be left alone (set to true) in typical usage.
|
|
|
|
# There are times when Spectator shouldn't run tests.
|
|
|
|
# One of those is testing Spectator.
|
|
|
|
class_property? autorun = true
|
|
|
|
|
2018-09-27 21:41:18 +00:00
|
|
|
# All tests are ran just before the executable exits.
|
2018-10-15 06:32:29 +00:00
|
|
|
# Tests will be skipped, however, if `#autorun?` is set to false.
|
2018-09-27 21:41:18 +00:00
|
|
|
# There are a couple of reasons for this.
|
|
|
|
#
|
|
|
|
# First is that we want a clean interface for the end-user.
|
|
|
|
# They shouldn't need to call a "run" method.
|
|
|
|
# That adds the burden on the developer to ensure the tests are run after they are created.
|
|
|
|
# And that gets complicated when there are multiple files that could run in any order.
|
|
|
|
#
|
|
|
|
# Second is to allow all of the tests and framework to be constructed.
|
|
|
|
# We know that all of the instances and DSL builders have finished
|
|
|
|
# after the main part of the executable has run.
|
|
|
|
#
|
|
|
|
# By doing this, we provide a clean interface and safely run after everything is constructed.
|
|
|
|
# The downside, if something bad happens, like an exception is raised,
|
|
|
|
# Crystal doesn't display much information about what happened.
|
|
|
|
# That issue is handled by putting a begin/rescue block to show a custom error message.
|
2018-08-19 07:15:32 +00:00
|
|
|
at_exit do
|
2018-10-15 06:32:29 +00:00
|
|
|
run if autorun?
|
|
|
|
end
|
|
|
|
|
|
|
|
# Builds the tests and runs the framework.
|
|
|
|
private def self.run
|
2018-12-12 22:27:40 +00:00
|
|
|
# Build the test suite and run it.
|
|
|
|
suite = ::Spectator::DSL::Builder.build
|
2018-12-12 22:22:56 +00:00
|
|
|
Runner.new(suite).run
|
2018-10-15 06:32:29 +00:00
|
|
|
rescue ex
|
|
|
|
# Catch all unhandled exceptions here.
|
|
|
|
# Examples are already wrapped, so any exceptions they throw are caught.
|
|
|
|
# But if an exception occurs outside an example,
|
|
|
|
# it's likely the fault of the test framework (Spectator).
|
|
|
|
# So we display a helpful error that could be reported and return non-zero.
|
|
|
|
puts
|
|
|
|
puts "Encountered an unexpected error in framework"
|
|
|
|
puts ex.message
|
|
|
|
puts ex.backtrace.join("\n")
|
|
|
|
exit(1)
|
2018-08-19 07:15:32 +00:00
|
|
|
end
|
2018-08-18 21:33:20 +00:00
|
|
|
end
|