cs/Battery

copyright (c) 2004 Sean O'Dell

Purpose

cs/Battery is a unit testing framework for Ruby. It captures all standard error and output and reports the entire summary of all tests formatted as valid YAML, for easier reading and parsing. Another key feature is that all tests run in the order they are added to their batteries by default, but you can also re-arrange run order through the battery#tests method.

current version: 0.2.2
project homepage: http://rubyforge.org/projects/battery/
download url: csbattery-0.2.2.tar.gz
changes: CHANGELOG
license: GPL

Table of Contents
    Quick Lesson
    Tutorials
        A Simple Battery of Tests
        Running Multiple Batteries of Tests
        Derive the Battery Class
    Test::Battery Class
        Test::Battery.new
        battery#add_test
        battery#at_setup
        battery#at_teardown
        battery#run
        battery#tests
    Test::Report Class
        Test::Report.new
        report#output

Installation

using Ruby Gems

# gem -Ri csbattery

from source

Download csbattery-0.2.2.tar.gz to a working directory, then issue the following commands:

$ tar -xzvf csbattery-0.2.2.tar.gz

$ ruby setup.rb config
$ ruby setup.rb setup
# ruby setup.rb install

Using cs/Battery

Quick Lesson

Ruby Gems

If you installed Battery with gem, be sure to add the following code to the top of your scripts:

require "rubygems"
require_gem "csbattery"

Example

require "celsoft.com/battery"

battery = Test::Battery.new("my battery")

battery.add_test("my test") do | battery |
  next true
end

battery.run

print battery.report.output

Tutorials

A Simple Battery of Tests

To run a series of tests, just create a battery object, add some tests and print out the result.

require "celsoft.com/battery"

battery = Test::Battery.new("my battery")

battery.add_test("first test") do | battery |
  next true
end

battery.add_test("second test") do | battery |
  next true
end

battery.run

print battery.report.output

Running Multiple Batteries of Tests

To run a series of batteries and have all the output in one neat report, create a report object first, then run each battery.

require "celsoft.com/battery"

report = Test::Report.new

battery1 = Test::Battery.new("battery one", report)

battery1.add_test("test one") do | battery |
  next true
end

battery2 = Test::Battery.new("battery two", report)

battery2.add_test("test one") do | battery |
  raise "this is just a test error!"
end

battery1.run
battery2.run

print report.output

Derive the Battery Class

Create a new class derived from Battery and add methods which begin with test_.

require "celsoft.com/battery"

class MyBattery < Test::Battery
  def test_testfunc(battery)
  end
end

battery = MyBattery.new("my battery")

battery.run

print battery.report.output

Test::Battery Class

Test::Battery.new

Test::Battery.new((sBatteryTitle [, report])

Creates a new instance of Battery.

battery#add_test

battery#add_test(&block)  { | battery | }

Adds a proc as a test to be called when the battery is run.

battery#at_setup

battery#at_setup(&block) { | battery | }

Calls the block each time a new test is about to be run.

battery#at_teardown

battery#at_teardown(&block) { | battery | }

Calls the block after each test is run.

battery#run

battery#run(caseExpr = nil)

Run all tests in the battery. If the optional argument caseExpr is given, any test whose name matches the expression using === will be run.

battery#tests

battery#tests

Returns the array of blocks kept by the battery. You add and remove tests through this array, or re-arrange them and the tests will run in the order they appear in the array.

Test::Report Class

Test::Report.new

Test::Report.new()

Creates a new instance of Report.

report#output

report#output

Returns a full report of all batteries and their tests as a string in YAML format.