Self-contained test file

Here is an example that requires a "corpus" attribute, stores lines from that file in the "lines" attribute and makes it available to all test blocks:

    # examples/cookbook/single_file.t

    use Test::Roo;

    use MooX::Types::MooseLike::Base qw/ArrayRef/;
    use Path::Tiny;

    has corpus => (
        is       => 'ro',
        isa      => sub { -f shift },
        required => 1,
    );

    has lines => (
        is  => 'lazy',
        isa => ArrayRef,
    );

    sub _build_lines {
        my ($self) = @_;
        return [ map { lc } path( $self->corpus )->lines ];
    }

    test 'sorted' => sub {
        my $self = shift;
        is_deeply( $self->lines, [ sort @{$self->lines} ], "alphabetized");
    };

    test 'a to z' => sub {
        my $self = shift;
        my %letters = map { substr($_,0,1) => 1 } @{ $self->lines };
        is_deeply( [sort keys %letters], ["a" .. "z"], "all letters found" );
    };


    run_me( { corpus => "/usr/share/dict/words" } );
    # ... test other corpuses ...

    done_testing;

Standalone test class

Here is the same corpus checking example as before, but now as a class:

    # examples/cookbook/lib/CorpusCheck.pm

    package CorpusCheck;
    use Test::Roo;

    use MooX::Types::MooseLike::Base qw/ArrayRef/;
    use Path::Tiny;

    has corpus => (
        is       => 'ro',
        isa      => sub { -f shift },
        required => 1,
    );

    has lines => (
        is  => 'lazy',
        isa => ArrayRef,
    );

    sub _build_lines {
        my ($self) = @_;
        return [ map { lc } path( $self->corpus )->lines ];
    }

    test 'sorted' => sub {
        my $self = shift;
        is_deeply( $self->lines, [ sort @{$self->lines} ], "alphabetized");
    };

    test 'a to z' => sub {
        my $self = shift;
        my %letters = map { substr($_,0,1) => 1 } @{ $self->lines };
        is_deeply( [sort keys %letters], ["a" .. "z"], "all letters found" );
    };

    1;

Running it from a .t file doesn't even need Test::Roo:

    # examples/cookbook/standalone.t

    use strictures;
    use Test::More;

    use lib 'lib';
    use CorpusCheck;

    CorpusCheck->run_tests({ corpus => "/usr/share/dict/words" });

    done_testing;

Standalone Test Roles

Imagine we want to test a file-finder module like Path::Iterator::Rule. We could put tests for it into a role, then run the tests from a file that composes that role. For example, here would be the test file:

    # examples/cookbook/test-pir.pl

    use Test::Roo;

    use lib 'lib';

    with 'IteratorTest';

    run_me(
        {
            iterator_class => 'Path::Iterator::Rule',
            result_type    => '',
        }
    );

    done_testing;

Then in the distribution for Path::Class::Rule, the same role could be tested with a test file like this:

    # examples/cookbook/test-pcr.pl

    use Test::Roo;

    use lib 'lib';

    with 'IteratorTest';

    run_me(
        {
            iterator_class => 'Path::Class::Rule',
            result_type    => 'Path::Class::Entity',
        },
    );

    done_testing;

What is the common role that they are consuming? It sets up a test directory, creates files and runs tests:

    # examples/cookbook/lib/IteratorTest.pm

    package IteratorTest;
    use Test::Roo::Role;

    use MooX::Types::MooseLike::Base qw/:all/;
    use Class::Load qw/load_class/;
    use Path::Tiny;

    has [qw/iterator_class result_type/] => (
        is       => 'ro',
        isa      => Str,
        required => 1,
    );

    has test_files => (
        is      => 'ro',
        isa     => ArrayRef,
        default => sub {
            return [
                qw(
                aaaa
                bbbb
                cccc/dddd
                eeee/ffff/gggg
                )
            ];
        },
    );

    has tempdir => (
        is  => 'lazy',
        isa => InstanceOf ['Path::Tiny']
    );

    has rule_object => (
        is      => 'lazy',
        isa     => Object,
        clearer => 1,
    );

    sub _build_description { return shift->iterator_class }

    sub _build_tempdir {
        my ($self) = @_;
        my $dir = Path::Tiny->tempdir;
        $dir->child($_)->touchpath for @{ $self->test_files };
        return $dir;
    }

    sub _build_rule_object {
        my ($self) = @_;
        load_class( $self->iterator_class );
        return $self->iterator_class->new;
    }

    sub test_result_type {
        my ( $self, $file ) = @_;
        if ( my $type = $self->result_type ) {
            isa_ok( $file, $type, $file );
        }
        else {
            is( ref($file), '', "$file is string" );
        }
    }

    test 'find files' => sub {
        my $self = shift;
        $self->clear_rule_object; # make sure have a new one each time

        $self->tempdir;
        my $rule = $self->rule_object;
        my @files = $rule->file->all( $self->tempdir, { relative => 1 } );

        is_deeply( \@files, $self->test_files, "correct list of files" )
        or diag explain \@files;

        $self->test_result_type($_) for @files;
    };

    # ... more tests ...

    1;

Skipping all tests

    use Class::Load qw/try_load_class/;

    has fixture => (
        is => 'lazy',
    );

    sub _build_fixture {
        # ... something that might die if unavailable ...
    }

    sub BUILD {
        my ($self) = @_;

        try_load_class('Class::Name')
            or plan skip_all => "Class::Name required to run these tests";

        eval { $self->fixture }
            or plan skip_all => "Couldn't build fixture";
    }

Setting a test description

    has [qw/iterator_class result_type/] => (
        is       => 'ro',
        isa      => Str,
        required => 1,
    );

    sub _build_description { return shift->iterator_class }

The "iterator_class" attribute is required and then the description is set to it. Or, there could be a more verbose description:

    sub _build_description {
        my $name = shift->iterator_class;
        return "Testing the $name class"
    }

Requiring a builder

In the test role:

    has fixture => (
        is => 'lazy',
    );

    requires '_build_fixture';

In the consuming class:

    sub _build_fixture { ... }

Clearing fixtures

    has fixture => (
        is => 'lazy',
        clearer => 1,
    );

    test "some test" => sub {
        my $self = shift;
        $self->clear_fixture;
        ...
    };

Setting up a fixture before testing

Here is an example that creates an SQLite table before any tests are run and cleans up afterwards:

    # example/cookbook/sqlite.t

    use Test::Roo;
    use DBI;
    use Path::Tiny;

    has tempdir => (
        is      => 'ro',
        clearer => 1,
        default => sub { Path::Tiny->tempdir },
    );

    has dbfile => (
        is      => 'lazy',
        default => sub { shift->tempdir->child('test.sqlite3') },
    );

    has dbh => ( is => 'lazy', );

    sub _build_dbh {
        my $self = shift;
        DBI->connect(
            "dbi:SQLite:dbname=" . $self->dbfile, { RaiseError => 1 }
        );
    }

    before 'setup' => sub {
        my $self = shift;
        $self->dbh->do("CREATE TABLE f (f1, f2, f3)");
    };

    after 'teardown' => sub { shift->clear_tempdir };

    test 'first' => sub {
        my $self = shift;
        my $dbh  = $self->dbh;
        my $sth  = $dbh->prepare("INSERT INTO f(f1,f2,f3) VALUES (?,?,?)");
        ok( $sth->execute( "one", "two", "three" ), "inserted data" );

        my $got = $dbh->selectrow_arrayref("SELECT * FROM f");
        is_deeply( $got, [qw/one two three/], "read data" );
    };

    run_me;
    done_testing;

Running tests during setup and teardown

    before 'setup' => sub {
        my $self = shift;
        ok( ! -f $self->dbfile, "test database file not created" );
        ok( $self->dbh->do("CREATE TABLE f (f1, f2, f3)"), "created table");
        ok( -f $self->dbfile, "test database file exists" );
    };

    after 'teardown' => sub {
        my $self = shift;
        my $dir = $self->tempdir;
        $self->clear_tempdir;
        ok( ! -f $dir, "tempdir cleaned up");
    };

Global modifiers with "each_test"

Here is an example that ensures that every test block is run in its own separate temporary directory.

    # examples/cookbook/with_tempd.t

    use Test::Roo;
    use File::pushd qw/tempd/;
    use Cwd qw/getcwd/;

    has tempdir => (
        is => 'lazy',
        isa => sub { shift->isa('File::pushd') },
        clearer => 1,
    );

    # tempd changes directory until the object is destroyed
    # and the fixture caches the object until cleared
    sub _build_tempdir { return tempd() }

    # building attribute will change to temp directory
    before each_test => sub { shift->tempdir };

    # clearing attribute will change to original directory
    after each_test => sub { shift->clear_tempdir };

    # do stuff in a temp directory
    test 'first test' => sub {
        my $self = shift;
        is( $self->tempdir, getcwd(), "cwd is " . $self->tempdir );
        # ... more tests ...
    };

    # do stuff in a separate, fresh temp directory
    test 'second test' => sub {
        my $self = shift;
        is( $self->tempdir, getcwd(), "cwd is " . $self->tempdir );
        # ... more tests ...
    };

    run_me;
    done_testing;

Individual test modifiers

    # examples/cookbook/hookable_test.t

    use Test::Roo;

    has counter => ( is => 'rw', default => sub { 0 } );

    sub is_positive {
        my $self = shift;
        ok( $self->counter > 0, "counter is positive" );
    }

    before is_positive => sub { shift->counter( 1 ) };

    test 'hookable' => sub { shift->is_positive };

    run_me;
    done_testing;

Wrapping tests

The following example clears the fixture before tests defined with the "fresh_test" function.

    # examples/cookbook/wrapped.t

    use strict;
    use Test::Roo;

    has fixture => (
        is => 'rw',
        lazy => 1,
        builder => 1,
        clearer => 1,
    );

    sub _build_fixture { "Hello World" }

    sub fresh_test {
        my ($name, $code) = @_;
        test $name, sub {
            my $self = shift;
            $self->clear_fixture;
            $code->($self);
        };
    }

    fresh_test 'first' => sub {
        my $self = shift;
        is ( $self->fixture, 'Hello World', "fixture has default" );
        $self->fixture("Goodbye World");
    };

    fresh_test 'second' => sub {
        my $self = shift;
        is ( $self->fixture, 'Hello World', "fixture has default" );
    };

    run_me;
    done_testing;