Module: Blackstart

Defined in:
lib/blackstart.rb

Overview

This module provides facilities for defining and running automated tests.

Defined Under Namespace

Classes: Context

Class Method Summary collapse

Class Method Details

.add(sink = [], &director) ⇒ Object

Allows the block to add procs to a collection, which it returns.

In detail: This method sends call with one positional argument, an adder object, to the object representing the block, director. This block can send call messages to the adder to add objects representing the respective blocks to the collection, sink. With each sending of call, the object to be added will be either a proc (if call is sent with a block) or nil (if call is sent without a block). If any non-block arguments are sent with the call message, an exception is raised. To add the object, the adder sends a << message to sink with the object as the positional argument and no other arguments. The adder returns nil in response to a call message if it returns at all. This method returns sink.

By default, sink is a new empty array.



42
43
44
45
46
47
48
 
# File 'lib/blackstart.rb', line 42

def self.add sink = [], &director
  director.call ::Kernel.lambda { |&prc|
    sink << prc
    nil
  }
  sink
end

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

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

In detail: This method expects the sequence of test objects, source, to respond to an each message by yielding successive test objects to its block. Each test is run by converting the test object to a proc and calling it in the context of a new instance of Blackstart::Context. A failure is when the test raises an error (that is, an exception whose class is StandardError or a descendent 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 describing the error, and an empty string. If a test raises any other 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 or true otherwise.

By default, ostream is $stdout.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
 
# File 'lib/blackstart.rb', line 76

def self.run source, ostream = $stdout
  success = true
  for tst in source
    # Convert to a proc and create a context outside the vet block so that
    # this method will raise any exception that results instead of
    # potentially treating it as a test failure.
    prc = ::Proc.new(&tst)
    context = Context.new
    if err_desc = vet { context.instance_exec(&prc) }
      success = false
      ostream.puts "FAILED TEST:", tst.to_s, "...ERROR:", err_desc.to_s, ""
    end
  end
  success
end

.vet(&prc) ⇒ Object

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

In detail: This method sends call with no arguments to the object representing the block. If that raises an error – that is, an exception whose class is StandardError or a descendent of StandardError – this method creates a string describing that error and returns it; the description includes the error’s class, message, and backtrace (if any). If sending the message raises any other exception, this method raises that exception. If sending the message does not raise an exception, this method returns nil.



18
19
20
21
22
23
24
 
# File 'lib/blackstart.rb', line 18

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