Unit testing is a postdebugging testing technique that lets you try bits of your program in order to verify that they work as expected. Some programmers use unit testing habitually in addition to or even instead of interactive debugging; other programmers use it rarely or never. Entire books have been written on the techniques and methodologies of unit testing, and I will only cover its fundamentals here.

The basic idea of unit testing is that you can write a number of “assertions” stating that certain results should be obtained as the consequence of certain actions. For example, you might assert that the return value of a specific method should be 100, that it should be a Boolean, or that it should be an instance of a specific class. If, when the test is run, the assertion proves to be correct, it passes the test; if it is incorrect, the test fails.

Here’s an example, which will fail if the getVal method of the object, t, returns any value other than 100:

assert_equal(100, t.getVal)

But you can’t just pepper your code with assertions of this sort. There are precise rules to the game. First you have to require the test/unit file. Then you need to derive a test class from the TestCase class, which is found in the Unit module, which is itself in the Test module:

class MyTest < Test::Unit::TestCase

Inside this class you can write one or more methods, each of which constitutes a test containing one or more assertions. The method names must begin with test (so methods called test1 or testMyProgram are okay, but a method called myTestMethod isn’t). The following method contains a test that makes the single assertion that the return value of TestClass.new(100).getVal is 1,000:

def test2
    assert_equal(1000,TestClass.new(100).getVal)
end

And here is a complete (albeit simple) test suite in which I have defined a TestCase class called MyTest that tests the class, TestClass. Here (with a little imagination!), TestClass may be taken to represent a whole program that I want to test:

test1.rb

require 'test/unit'

class TestClass
    def initialize( aVal )
        @val = aVal * 10
    end

    def getVal
        return @val
    end
end

class MyTest < Test::Unit::TestCase
    def test1
        t = TestClass.new(10)
        assert_equal(100, t.getVal)
        assert_equal(101, t.getVal)
        assert(100 != t.getVal)
    end

    def test2
        assert_equal(1000,TestClass.new(100).getVal)
    end
end

This test suite contains two tests: test1 (which contains three assertions) and test2 (which contains one). To run the tests, you just need to run the program; you don’t have to create an instance of MyClass. You will see a report of the results that states there were two tests, three assertions, and one failure:

1) Failure:
test1(MyTest) [C:/bookofruby/ch18/test1.rb:19]:
<101> expected but was
<100>.

2 tests, 3 assertions, 1 failures, 0 errors

In fact, I made four assertions. However, assertions following a failure are not evaluated in a given test. In test1, this assertion fails:

assert_equal(101, t.getVal)

Having failed, the next assertion is skipped. If I now correct this failed assertion (asserting 100 instead of 101), this next assertion will also be tested:

assert(100 != t.getVal)

But this too fails. This time, the report states that four assertions have been evaluated with one failure:

2 tests, 4 assertions, 1 failures, 0 errors, 0 skips

Of course, in a real-life situation, you should aim to write correct assertions, and when any failures are reported, it should be the failing code that is rewritten—not the assertion!

For a slightly more complex example of testing, see the test2.rb program (which requires a file called buggy.rb). This is a small adventure game that includes the following test methods:

test2.rb

def test1
    @game.treasures.each{ |t|
        assert(t.value < 2000, "FAIL: #{t} t.value = #{t.value}" )
    }
end

def test2
    assert_kind_of( TestMod::Adventure::Map, @game.map)
    assert_kind_of( Array, @game.map)
end

Here the first method, test1, performs an assert test on an array of objects passed into a block, and it fails when a value attribute is not less than 2,000. The second method, test2, tests the class types of two objects using the assert_kind_of method. The second test in this method fails when @game.map is found to be of the type TestMod::Adventure::Map rather than Array as is asserted.

The code also contains two more methods named setup and teardown. When defined, methods with these names will be run before and after each test method. In other words, in test2.rb, the following methods will run in this order:

This gives you the opportunity of reinitializing any variables to specific values prior to running each test or, as in this case, re-creating objects to ensure that they are in a known state as in the following example:

def setup
    @game = TestMod::Adventure.new
end

def teardown
    @game.endgame
end

Digging Deeper

This section contains a summary of assertions for unit testing, explains why IRB may show different results for what appears to be the same code, and considers the merits of more advanced debugging tools.

Assertions Available When Unit Testing

The list of assertions shown next is provided for ease of reference. A full explanation of each assertion is beyond the scope of this book. You can find complete documentation of the testing libraries at http://ruby-doc.org/stdlib/. On this site, select the class listing for Test::Unit::Assertions in order to view the full documentation of the available assertions plus numerous code samples demonstrating their usage.

assert(boolean, message=nil)

Asserts that boolean is not false or nil.

assert_block(message="assert_block failed.") {|| ...}

The assertion upon which all other assertions are based. Passes if the block yields true.

assert_equal(expected, actual, message=nil)

Passes if expected == actual.

assert_in_delta(expected_float, actual_float, delta, message="")

Passes if expected_float and actual_float are equal within delta tolerance.

assert_instance_of(klass, object, message="")

Passes if object .instance_of? klass.

assert_kind_of(klass, object, message="")

Passes if object .kind_of? klass.

assert_match(pattern, string, message="")

Passes if string =˜ pattern.

assert_nil(object, message="")

Passes if object is nil.

assert_no_match(regexp, string, message="")

Passes if regexp !˜ string.

assert_not_equal(expected, actual, message="")

Passes if expected != actual.

assert_not_nil(object, message="")

Passes if ! object .nil?.

assert_not_same(expected, actual, message="")

Passes if ! actual .equal? expected.

assert_nothing_raised(*args) {|| ...}

Passes if block does not raise an exception.

assert_nothing_thrown(message="", &proc)

Passes if block does not throw anything.

assert_operator(object1, operator, object2, message="")

Compares the object1 with object2 using operator. Passes if object1.send(operator, object2) is true.

assert_raise(*args) {|| ...}

Passes if the block raises one of the given exceptions.

assert_raises(*args, &block)

Alias of assert_raise. (Deprecated in Ruby 1.9 and to be removed in 2.0.)

assert_respond_to(object, method, message="")

Passes if object .respond_to? method.

assert_same(expected, actual, message="")

Passes if actual .equal? expected (in other words, they are the same instance).

assert_send(send_array, message="")

Passes if the method send returns a true value.

assert_throws(expected_symbol, message="", &proc)

Passes if the block throws expected_symbol

build_message(head, template=nil, *arguments)

Builds a failure message; head is added before the template and *arguments replaces the question marks positionally in the template.

flunk(message="Flunked")

flunk always fails.

Line Breaks Are Significant

I said earlier that you need to take care when entering line breaks into the interactive Ruby console (IRB) since the position of line breaks may alter the meaning of your Ruby code. So, for example, the following:

linebreaks.rb

x = ( 10 +
( 2 * 4 ) )

assigns 18 to x, but the following:

x = (10
+ (2*4))

assigns 8 to x.

This is not merely a quirk of IRB. This is normal behavior of Ruby code even when entered into a text editor and executed by the Ruby interpreter. The second example just shown evaluates 10 on the first line, finds this to be a perfectly acceptable value, and promptly forgets about it; then it evaluates + (2*4), which it also finds to be an acceptable value (8), but it has no connection with the previous value (10), so 8 is returned and assigned to x.

If you want to tell Ruby to evaluate expressions split over multiple lines, ignoring the line breaks, you can use the line continuation character (). This is what I’ve done here:

x = (10 
+ (2*4) )

This time, x is assigned the value 18.

Graphical Debuggers

For serious debugging, I strongly recommend a graphical debugger. For example, the debugger in the Ruby In Steel IDE allows you to set breakpoints and watchpoints by clicking the margin of the editor.

It lets you monitor the values of selected “watch variables” or all local variables in separate docked windows. It maintains a “callstack” of all method calls leading to the current point of execution and allows you to navigate “backward” through the callstack to view the changing values of variables. It also has “drill-down” expansion of variables to allow you to expand arrays and hashes and look inside complex objects. These capabilities go well beyond the features of the standard Ruby debugger. For information on Ruby IDEs, see Appendix D.