Module: Blackstart

Defined in:
lib/blackstart.rb

Overview

This module provides facilities for running automated tests.

Defined Under Namespace

Classes: Scratchpad

Class Method Summary collapse

Class Method Details

.run(source, ostream = $stdout) ⇒ Object

Runs tests, writes any failure information to the output stream, and returns a boolean indicating whether there were no failures.

In detail: This method sends an each message with a block to the sequence of test objects, source, expecting it to yield to the block once for each test object in the sequence with that test object as the first argument. Each test involves creating a new scratchpad – an instance of Blackstart::Scratchpad – and sending an instance_exec message to it with the test object as a block argument, which converts the test object to a proc via to_proc if it’s not already a proc. The resulting proc is called with no arguments; the self object is set to the scratchpad. A failure is when the test (which includes any initial conversion to a proc) raises an error: an exception whose class is StandardError or a descendant of StandardError. After a failure, this method sends a puts message to the output stream, ostream, with these arguments (positional, in order): a string “FAILED TEST:”; the test object converted to a string via to_s; a string “…ERROR:”; a string combining the class, message, and backtrace of the error; and an empty string. If a test raises a non-error exception, this method immediately raises that exception. After it has run all the tests and handled any failures, this method returns false if there were failures, true otherwise. This method immediately raises any exception raised outside of a test.

By default, ostream is $stdout.



60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/blackstart.rb', line 60

def self.run source, ostream = $stdout
  success = true
  source.each do |tst|
    # Create the scratchpad outside the vet block so that this method will
    # raise any exception that results instead of potentially treating it as
    # a test failure.
    scratchpad = Scratchpad.new
    if err_desc = vet { scratchpad.instance_exec(&tst) }
      success = false
      ostream.puts "FAILED TEST:", tst.to_s, "...ERROR:", err_desc.to_s, ""
    end
  end
  success
end

.vet ⇒ Object

Yields to the block and returns a string describing the error raised, if any.

In detail: This method yields to the block with no arguments. If that raises an error – meaning an exception whose class is StandardError or a descendant of StandardError – this method attempts to make and return a string describing that error; the description consists of the error’s class, message, and backtrace (if any). If an exception is raised while making an error description, this method raises that exception. If yielding to the block raises a non-error exception, this method raises that exception. If yielding to the block does not raise an exception, this method returns nil.



20
21
22
23
24
25
26
 
# File 'lib/blackstart.rb', line 20

def self.vet
  yield
  nil
rescue ::StandardError
  # Like IO#puts, separate lines with a line feed character rather than $\.
  ["#{$!.class}: #{$!.message}"].concat($!.backtrace || []).join "\n"
end