Matt S Trout > Rakudo-Star-2012.08_001 > Test::More

Download:
Rakudo-Star-2012.08_001.tar.gz

Annotate this POD

Related Modules

Data::Dumper
Test::Harness
Module::Build
WWW::Mechanize
Test::Simple
Test::Exception
Scalar::Util
Devel::Cover
Class::InsideOut
Class::DBI
more...
By perlmonks.org
Source  

NAME ^

Test::More - Parrot extension for testing modules

SYNOPSIS ^

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

    # get the testing functions
    .local pmc exports, curr_namespace, test_namespace
    curr_namespace = get_namespace
    test_namespace = get_namespace [ 'Test'; 'More' ]
    exports        = split ' ', 'plan diag ok nok is is_deeply like isa_ok skip skip_all isnt todo throws_like lives_ok dies_ok'

    test_namespace.'export_to'(curr_namespace, exports)

    # set a test plan
    plan( 12 )

    # run your tests
    ok( 1 )
    ok( 0, 'failing test with diagnostic' )
    ok( 0, 'failing test with diagnostic', 'todo' => 'and a TODO comment' )

    nok( 1, 'failing test with diagnostic', 'todo' => 'and a TODO comment' )

    is( 100, 100 )
    is( 200, 100, 'failing integer compare with diagnostic' )

    is( 1.001, 1.001, 'passing float compare with diagnostic' )
    is( 8.008, 4.004 )

    is( 'foo', 'foo', 'passing string compare with diagnostic' )
    is( 'foo', 'bar', 'failing string compare with diagnostic' )

    is( some_pmc, another_pmc, 'pmc comparison uses "eq" op' )

    is_null( some_pmc, 'pmc was null' )

    diag( 'this may take a while' )
    is_deeply( some_deep_pmc, another_deep_pmc, 'deep structure comparison' )

    like( 'foo', 'f o**{2}', 'passing regex compare with diagnostic' )
    skip(1, 'reason for skipping')

    # old way
    todo(0, 'this is a failed test', 'reason for todo')

    # better way
    is(0, 'FAIL', todo => 'failure reason')

    $P0 = get_class "Squirrel"
    $P0.new()

    isa_ok($P0, "Squirrel", "new Squirrel")

DESCRIPTION ^

Test::More is a pure-Parrot library for testing modules. It provides the ok(), is(), isnt(), is_deeply(), and like() comparison functions for you. It also provides the plan() and diag() helper functions. It uses Test::Builder, a simple, single backend for multiple test modules to use within your tests.

FUNCTIONS ^

This class defines the following functions:

plan( number_or_no_plan )

Declares the number of tests you plan 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.

done_testing( number_of_tests? )

If you don't know how many tests you're going to run, you can issue the plan when you're done running tests.

number_of_tests is the same as plan(), it's the number of tests you expected to run. You can omit this, in which case the number of tests you ran doesn't matter, just the fact that your tests ran to conclusion.

This is safer than and replaces the "no_plan" plan.

ok( passed, description )

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

nok( passed, description )

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

is( left, right, description )

Compares the parameters passed as left and right, passing if they are equal and failing otherwise. This will report the results with the optional test description in description.

This is a multi-method, with separate implementations for int-int, float-float, string-string, and PMC-PMC comparisons. The latter uses the eq opcode for comparison.

If there is a mismatch, the current implementation takes the type of left as the proper type for the comparison, converting any numeric arguments to floats. Note that there is a hard-coded precision check to avoid certain rounding errors.

is( left, right, description, precision )

For Float only, an optional 4th parameter is allowed, a numeric precision. If specified, then the floats are only compared within the tolerance of the precision: e.g.:

 is(123.456, 123.457, 'close enough?', 1e-2)

will pass.

isnt( left, right, description )

Like is, but succeeds if the arguments don't match.

diag( diagnostic, ... )

Prints diagnostic to the screen, without affecting test comparisons.

is_deeply( left, right, description )

Compares the data structures passed as left and right. If data structures are passed, is_deeply does a deep comparison by walking each structure. It passes if they are equal and fails otherwise. This will report the results with the optional test description in description.

This handles comparisons of array-like and hash-like structures.

is_null( pmc, description )

Records a passing test if the PMC passed in is null, fails otherwise.

throws_type( invokable, type, description)

Passes a test if calling the invokable throws an exception of the expected type, fails a test otherwise. If the invokable parameter is an invokable object, invoke it. It it's a String, compile it as PIR code and invokes the result. Otherwise, fail the test.

dies_ok( codestring, description )

Takes PIR code in codestring and an optional message in description. Passes a test if the PIR code throws any exception, fails a test otherwise.

lives_ok( codestring, description )

Takes PIR code in codestring and an optional message in description. Passes a test if the PIR does not throw any exception, fails a test otherwise.

throws_like( codestring, pattern, description )

Takes PIR code in codestring and a PGE pattern to match in pattern, as well as an optional message in description. Passes a test if the PIR throws an exception that matches the pattern, fails the test otherwise.

throws_substring( codestring, text, description )

Takes PIR code in codestring and a string to match in text, as well as an optional message in description. Passes a test if the PIR throws an exception that matches the pattern, fails the test otherwise.

substring( target, text, description )

Similar to is, but using the index opcode to compare the string passed as text to the string passed as target. It passes if text is a substring of target and fails otherwise. This will report the results with the optional test description in description.

like( target, pattern, description )

Similar to is, but using the Parrot Grammar Engine to compare the string passed as target to the pattern passed as pattern. It passes if the pattern matches and fails otherwise. This will report the results with the optional test description in description.

skip( how_many, why )

Pass a number of tests, but with a comment that marks the test was actually skipped. Arguments are optional.

skip_all( reason )
todo( passed, description, reason )

Records a test as pass or fail (like ok, 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.

isa_ok( object, class_name, object_name )

Pass if the object isa class of the given class name. The object name passed in is not a full description, but a name to be included in the description. The description is presented as "<object_name> isa <class>".

Good input: "new MyObject", "return from bar()"

Bad input: "test that the return from Foo is correct type"

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-2009, Parrot Foundation.

syntax highlighting: