NAME

Test::Builder - Parrot extension for building test modules

SYNOPSIS

    # load this library
    load_bytecode 'library/Test/Builder.pbc'

    # create a new Test::Builder object
    .local pmc test

    test = new [ 'Test'; 'Builder' ]

    # plan to run ten tests
    test.'plan'( 10 )

    test.'ok'( 1, 'some test description' )
    test.'ok'( 0, 'some test description' )
    test.'diag'( 'the last test failed on purpose!' )

    test.'skip'( 3, 'do not run these three tests' )
    test.'todo'( 1, 'this is a todo test that passes', 'i am not sure' )
    test.'todo'( 0, 'this is a todo test that fails', ' i am still not sure' )

    test.'skip'( 4, 'cannot think of four more tests' )

    # you must call this when you have finished!
    test.'finish'()

DESCRIPTION

Test::Builder is a pure-Parrot library for building test modules. It manages test plans, formats and reports test results correctly, and has methods to manage passing, failing, skip, and TODO tests. It provides a simple, single backend for multiple test modules to use within your tests.

METHODS

This class defines the following methods:

new( args_hash )

Given an optional Hash of arguments, initializes the new object with the provided arguments. By default, you should rarely need to pass any arguments. If you do, you know why. The two allowed arguments are:

testplan

An object that does Test::Builder::TestPlan to manage the plan for this test run.

output

An object that does Test::Builder::Output to manage the output for this test run.

new() will not always return the same object, but every object will share the same state.

create( args_hash )

Creates and returns a new Test::Builder object with different backend objects. This probably doesn't work correctly yet, but you will probably never use it.

finish()

Finishes this test run. You should call this when you have finished running all of the tests. I know this is awful, but this has to be here until object finalization works reliably.This is probably not idempotent now, so try not to call it too many times, where "too many" means "more than one".

plan( number_or_no_plan )

Tells the object how many tests to run, either an integer greater than zero or the string no_plan. This will throw an exception if you have already declared a plan or if you pass an invalid argument.

diag( diagnostic_message )

Records a diagnostic message for output.

ok( passed, description )

Records a test as pass or fail depending on the truth of the integer passed, recording it with the optional test description in description.

todo( passed, description, reason )

Records a test as pass or fail based on the truth of the integer passed, but marks it as TODO so it always appears as a success. This also records the optional description of the test and the reason you have marked it as TODO.

skip( number reason )

Records number of tests as skip tests, using the optional reason to mark why you've skipped them.

skip_all()

Skips all of the tests in a test file. You cannot call this if you have a plan. This calls exit; there's little point in continuing.

BAILOUT( reason )

Ends the test immediately, giving the string reason as explanation. This also calls exit.

AUTHOR

Written and maintained by chromatic, chromatic at wgz dot org, based on the Perl 6 port he wrote, based on the original Perl 5 version he wrote with ideas from Michael G. Schwern. Please send patches, feedback, and suggestions to the Perl 6 internals mailing list.

COPYRIGHT

Copyright (C) 2005-2008, Parrot Foundation.