shard-spectator/src/spectator/harness.cr

require "./error_result"
require "./expectation"
require "./mocks"
require "./pass_result"
require "./result"

module Spectator
  # Helper class that acts as a gateway between test code and the framework.
  #
  # Test code should be wrapped with a call to `.run`.
  # This class will catch all errors raised by the test code.
  # Errors caused by failed assertions (`AssertionFailed`) are translated to failed results (`FailResult`).
  # Errors not caused by assertions are translated to error results (`ErrorResult`).
  #
  # Every runnable example should invoke the test code by calling `.run`.
  # This sets up the harness so that the test code can use it.
  # The framework does the following:
  # ```
  # result = Harness.run { run_example_code }
  # # Do something with the result.
  # ```
  #
  # Then from the test code, the harness can be accessed via `.current` like so:
  # ```
  # harness = ::Spectator::Harness.current
  # # Do something with the harness.
  # ```
  #
  # Of course, the end-user shouldn't see this or work directly with the harness.
  # Instead, methods the test calls can access it.
  # For instance, an expectation reporting a result.
  class Harness
    Log = ::Spectator::Log.for(self)

    # Retrieves the harness for the current running example.
    class_getter! current : self

    getter mocks = Mocks::Registry.new

    # Wraps an example with a harness and runs test code.
    # A block provided to this method is considered to be the test code.
    # The value of `.current` is set to the harness for the duration of the test.
    # It will be reset after the test regardless of the outcome.
    # The result of running the test code will be returned.
    def self.run : Result
      with_harness do |harness|
        harness.run { yield }
      end
    end

    # Instanciates a new harness and yields it.
    # The `.current` harness is set to the new harness for the duration of the block.
    # `.current` is reset to the previous value (probably nil) afterwards, even if the block raises.
    # The result of the block is returned.
    private def self.with_harness
      previous = @@current
      begin
        harness = new
        yield harness
      ensure
        @@current = previous
      end
    end

    @deferred = Deque(->).new
    @expectations = [] of Expectation

    # Runs test code and produces a result based on the outcome.
    # The test code should be called from within the block given to this method.
    def run : Result
      elapsed, error = capture { yield }
      elapsed2, error2 = capture { run_deferred }
      translate(elapsed + elapsed2, error || error2)
    end

    def report(expectation : Expectation) : Nil
      Log.debug { "Reporting expectation #{expectation}" }
      @expectations << expectation

      # TODO: Move this out of harness, maybe to `Example`.
      Example.current.name = expectation.description unless Example.current.name?

      raise ExpectationFailed.new(expectation) if expectation.failed?
    end

    # Stores a block of code to be executed later.
    # All deferred blocks run just before the `#run` method completes.
    def defer(&block) : Nil
      @deferred << block
    end

    # Yields to run the test code and returns information about the outcome.
    # Returns a tuple with the elapsed time and an error if one occurred (otherwise nil).
    private def capture : Tuple(Time, Exception?)
      error   = nil
      elapsed = Time.measure do
        error = catch_error { yield }
      end
      {elapsed, error}
    end

    # Yields to run a block of code and captures exceptions.
    # If the block of code raises an error, the error is caught and returned.
    # If the block doesn't raise an error, then nil is returned.
    private def catch : Exception?
      yield
    rescue e
      e
    else
      nil
    end

    # Translates the outcome of running a test to a result.
    # Takes the *elapsed* time and a possible *error* from the test.
    # Returns a type of `Result`.
    private def translate(elapsed, error) : Result
      case error
      when nil
        PassResult.new(elapsed, @expectations)
      when ExpectationFailed
        FailResult.new(elapsed, error, @expectations)
      else
        ErrorResult.new(elapsed, error, @expectations)
      end
    end

    # Runs all deferred blocks.
    # This method executes code from tests and may raise an error.
    # It should be wrapped in a call to `#capture`.
    private def run_deferred
      Log.debug { "Running deferred operations" }
      @deferred.each(&.call)
    end
  end
end