NAME

Testo - Raku Testing Done Right

SYNOPSIS

    use Testo;
    plan 10;

    # `is` uses smart match semantics:
    is 'foobar', *.contains('foo');    # test passes
    is (1, 2, (3, 4)), [1, 2, [3, 4]]; # test passes
    is (1, 2, (3, 4)), '1 2 3 4';      # test fails; unlike Test.pm6's `is`
    is 'foobar', /foo/;   # no more Test.pm6's `like`;    just use a regex
    is 'foobar', Str;     # no more Test.pm6's `isa-ok`;  just use a type object
    is 'foobar', Stringy; # no more Test.pm6's `does-ok`; just use a type object

    ok $number < 0;
    nok $io-path.e, 'path does not exist';

    # uses `eqv` semantics and works right with Seqs
    is-eqv (1, 2).Seq, (1, 2); # test fails; unlike Test.pm6's `is-deeply`

    # execute a program with some args and STDIN input and smartmatch its
    # STDERR, STDOUT, and exit status:
    is-run $*EXECUTABLE, :in<hi!>, :args['-e', 'say $*IN.uc'],
        :out(/'HI!'/), 'can say hi';

    # run a bunch of tests as a group; like Test.pm6's `subtest`
    group 'a bunch of test' => 3 => {
        is 1, 1;
        is 4, 4;
        is 'foobar', /foo/;
    }

FEATURES

• Tests routines designed for testing Raku code

• Configurable output: TAP, JSON, or even a custom type!

• Easy to extend with your own custom test routines!

BETA-WARE

Note this module is still in fleshing-out stage. JSON output type, more test functions, and docs for the classes under the hood and customization are yet to be made, but will be made soon!

DESCRIPTION

Testo is the New and Improved version of Test.pm6 that you can use instead of Test.pm6 to test all of your code and generate output in TAP, JSON, or any other custom format!

EXPORTED ROUTINES

plan

Defined as:

    sub plan (Int $number-of-tests);

Specifies the number of tests you plan to run.

    plan 5;

is

Defined as:

    sub is (Mu $expected, Mu $got, Str $desc?);

Testo's workhorse you'll use for most testing. Performs the test using smartmatch semantics; i.e. it's equivalent to doing ($expected ~~ $got).Bool, with the test passing if the result is True. An optional description of the test can be specified

    is 'foobar', *.contains('foo');    # test passes
    is (1, 2, (3, 4)), [1, 2, [3, 4]]; # test passes
    is (1, 2, (3, 4)), '1 2 3 4';      # test fails; unlike Test.pm6's `is`
    is 'foobar', /foo/;      # no more Test.pm6's `like`;    just use a regex
    is 'foobar', none /foo/; # no more Test.pm6's `unlike`;  just use a none  Junction
    is 'foobar', Str;        # no more Test.pm6's `isa-ok`;  just use a type object
    is 'foobar', Stringy;    # no more Test.pm6's `does-ok`; just use a type object

    is 1, 2, 'some description'; # you can provide optional description too

Note that Testo does not provide several of Test.pm6's tests, such as isnt, like, unlike, isa-ok or does-ok, as those are replaced by is with Regex/type objects/none Junctions as arguments.

is-eqv

Defined as:

    sub is-eqv (Mu $expected, Mu $got, Str $desc?);

Uses eqv semantics to perform the test. An optional description of the test can be specified.

    is-eqv (1, 2).Seq, (1, 2); # fails; types do not match
    is-eqv 1.0, 1; # fails; types do not match
    is-eqv 1, 1;   # succeeds; types and values match

ok and nok

    ok $number < 0;
    nok $io-path.e, 'path does not exist';

is-run

    is-run $*EXECUTABLE, :in<hi!>, :args['-e', 'say $*IN.uc'],
        :out(/'HI!'/), 'can say hi';

    is-run $*EXECUTABLE, :args['-e', '$*ERR.print: 42'],
        :err<42>, 'can err 42';

    is-run $*EXECUTABLE, :args['-e', 'die 42'],
        :err(*), :42status, 'can exit with exit code 42';

NOTE: due to a Rakudo bug RT#130781 exit code is currently always reported as 0

Runs an executable (via &run), optionally supplying extra args given as :args[...] or feeding STDIN with a Str or Blob data given via C<:in>.

Runs three is tests on STDOUT, STDERR, and exit code expected values for which are provided via :out, :err and :status arguments respectively. If omitted, :out and :err default to empty string ('') and :status defaults to 0. Use the Whatever star (*) as the value for any of the three arguments (see :err in last example above).

group

    plan 1;

    # run a bunch of tests as a group; like Test.pm6's `subtest`
    group 'a bunch of tests' => 4 => {
        is 1, 1;
        is 4, 4;
        is 'foobar', /foo/;

        group 'nested bunch of tests; with manual `plan`' => {
            plan 2;
            is 1, 1;
            is 4, 4;
        }
    }

Similar to Test.pm6's subtest. Groups a number of tests into a... group with its own plan. The entire group counts as 1 test towards the planned/ran number of tests.

Takes a Pair as the argument that is either Str:D $desc => &group-code or Str:D $desc => UInt:D $plan where .so => &group-code (see code example above), the latter form lets you specify the plan for the group, while the former would require you to manually use &plan inside of the &group-code.

Groups can be nested for any (reasonable) number of levels.

REPOSITORY

Fork this module on GitHub: https://github.com/raku-community-modules/Testo

BUGS

To report bugs or request features, please use https://github.com/raku-community-modules/Testo/issues

AUTHOR

Zoffix Znet (http://perl6.party/)

LICENSE

You can use and distribute this module under the terms of the The Artistic License 2.0. See the LICENSE file included in this distribution for complete details.

Some portions of this software may be based on or re-use code of Test.pm6 module shipped with Rakudo 2107.04.03, © 2017 by The Perl Foundation, under The Artistic License 2.0.

The META6.json file of this distribution may be distributed and modified without restrictions or attribution.