.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Roo::Cookbook 3pm"
.TH Test::Roo::Cookbook 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Roo::Cookbook \- Test::Roo examples
.SH "VERSION"
.IX Header "VERSION"
version 1.004
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This file offers usage ideas and examples for Test::Roo.
.SH "ORGANIZING TEST CLASSES AND ROLES"
.IX Header "ORGANIZING TEST CLASSES AND ROLES"
.SS "Self-contained test file"
.IX Subsection "Self-contained test file"
A single test file could be used for simple tests where you want to
use Moo attributes for fixtures that get used by test blocks.
.PP
Here is an example that requires a \f(CW\*(C`corpus\*(C'\fR attribute, stores
lines from that file in the \f(CW\*(C`lines\*(C'\fR attribute and makes it
available to all test blocks:
.PP
.Vb 1
\&    # examples/cookbook/single_file.t
\&
\&    use Test::Roo;
\&
\&    use MooX::Types::MooseLike::Base qw/ArrayRef/;
\&    use Path::Tiny;
\&
\&    has corpus => (
\&        is       => \*(Aqro\*(Aq,
\&        isa      => sub { \-f shift },
\&        required => 1,
\&    );
\&
\&    has lines => (
\&        is  => \*(Aqlazy\*(Aq,
\&        isa => ArrayRef,
\&    );
\&
\&    sub _build_lines {
\&        my ($self) = @_;
\&        return [ map { lc } path( $self\->corpus )\->lines ];
\&    }
\&
\&    test \*(Aqsorted\*(Aq => sub {
\&        my $self = shift;
\&        is_deeply( $self\->lines, [ sort @{$self\->lines} ], "alphabetized");
\&    };
\&
\&    test \*(Aqa to z\*(Aq => 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;
.Ve
.SS "Standalone test class"
.IX Subsection "Standalone test class"
You don't have to put the test class into the \fI.t\fR file.  It's just a class.
.PP
Here is the same corpus checking example as before, but now as a class:
.PP
.Vb 1
\&    # examples/cookbook/lib/CorpusCheck.pm
\&
\&    package CorpusCheck;
\&    use Test::Roo;
\&
\&    use MooX::Types::MooseLike::Base qw/ArrayRef/;
\&    use Path::Tiny;
\&
\&    has corpus => (
\&        is       => \*(Aqro\*(Aq,
\&        isa      => sub { \-f shift },
\&        required => 1,
\&    );
\&
\&    has lines => (
\&        is  => \*(Aqlazy\*(Aq,
\&        isa => ArrayRef,
\&    );
\&
\&    sub _build_lines {
\&        my ($self) = @_;
\&        return [ map { lc } path( $self\->corpus )\->lines ];
\&    }
\&
\&    test \*(Aqsorted\*(Aq => sub {
\&        my $self = shift;
\&        is_deeply( $self\->lines, [ sort @{$self\->lines} ], "alphabetized");
\&    };
\&
\&    test \*(Aqa to z\*(Aq => sub {
\&        my $self = shift;
\&        my %letters = map { substr($_,0,1) => 1 } @{ $self\->lines };
\&        is_deeply( [sort keys %letters], ["a" .. "z"], "all letters found" );
\&    };
\&
\&    1;
.Ve
.PP
Running it from a \fI.t\fR file doesn't even need Test::Roo:
.PP
.Vb 1
\&    # examples/cookbook/standalone.t
\&
\&    use strictures;
\&    use Test::More;
\&
\&    use lib \*(Aqlib\*(Aq;
\&    use CorpusCheck;
\&
\&    CorpusCheck\->run_tests({ corpus => "/usr/share/dict/words" });
\&
\&    done_testing;
.Ve
.SS "Standalone Test Roles"
.IX Subsection "Standalone Test Roles"
The real power of Test::Roo is decomposing test behaviors into
roles that can be reused.
.PP
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:
.PP
.Vb 1
\&    # examples/cookbook/test\-pir.pl
\&
\&    use Test::Roo;
\&
\&    use lib \*(Aqlib\*(Aq;
\&
\&    with \*(AqIteratorTest\*(Aq;
\&
\&    run_me(
\&        {
\&            iterator_class => \*(AqPath::Iterator::Rule\*(Aq,
\&            result_type    => \*(Aq\*(Aq,
\&        }
\&    );
\&
\&    done_testing;
.Ve
.PP
Then in the distribution for Path::Class::Rule, the same role
could be tested with a test file like this:
.PP
.Vb 1
\&    # examples/cookbook/test\-pcr.pl
\&
\&    use Test::Roo;
\&
\&    use lib \*(Aqlib\*(Aq;
\&
\&    with \*(AqIteratorTest\*(Aq;
\&
\&    run_me(
\&        {
\&            iterator_class => \*(AqPath::Class::Rule\*(Aq,
\&            result_type    => \*(AqPath::Class::Entity\*(Aq,
\&        },
\&    );
\&
\&    done_testing;
.Ve
.PP
What is the common role that they are consuming?  It sets up a test
directory, creates files and runs tests:
.PP
.Vb 1
\&    # 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       => \*(Aqro\*(Aq,
\&        isa      => Str,
\&        required => 1,
\&    );
\&
\&    has test_files => (
\&        is      => \*(Aqro\*(Aq,
\&        isa     => ArrayRef,
\&        default => sub {
\&            return [
\&                qw(
\&                aaaa
\&                bbbb
\&                cccc/dddd
\&                eeee/ffff/gggg
\&                )
\&            ];
\&        },
\&    );
\&
\&    has tempdir => (
\&        is  => \*(Aqlazy\*(Aq,
\&        isa => InstanceOf [\*(AqPath::Tiny\*(Aq]
\&    );
\&
\&    has rule_object => (
\&        is      => \*(Aqlazy\*(Aq,
\&        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), \*(Aq\*(Aq, "$file is string" );
\&        }
\&    }
\&
\&    test \*(Aqfind files\*(Aq => 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( \e@files, $self\->test_files, "correct list of files" )
\&        or diag explain \e@files;
\&
\&        $self\->test_result_type($_) for @files;
\&    };
\&
\&    # ... more tests ...
\&
\&    1;
.Ve
.SH "CREATING AND MANAGING FIXTURES"
.IX Header "CREATING AND MANAGING FIXTURES"
.SS "Skipping all tests"
.IX Subsection "Skipping all tests"
If you need to skip all tests in the \fI.t\fR file because some prerequisite
isn't available or some fixture couldn't be built, use a \f(CW\*(C`BUILD\*(C'\fR method and
call \f(CW\*(C`plan skip_all => $reason\*(C'\fR.
.PP
.Vb 1
\&    use Class::Load qw/try_load_class/;
\&
\&    has fixture => (
\&        is => \*(Aqlazy\*(Aq,
\&    );
\&
\&    sub _build_fixture {
\&        # ... something that might die if unavailable ...
\&    }
\&
\&    sub BUILD {
\&        my ($self) = @_;
\&
\&        try_load_class(\*(AqClass::Name\*(Aq)
\&            or plan skip_all => "Class::Name required to run these tests";
\&
\&        eval { $self\->fixture }
\&            or plan skip_all => "Couldn\*(Aqt build fixture";
\&    }
.Ve
.SS "Setting a test description"
.IX Subsection "Setting a test description"
You can override \f(CW\*(C`_build_description\*(C'\fR to create a test description based
on other attributes.  For example, the \f(CW\*(C`IteratorTest\*(C'\fR package earlier
had these lines:
.PP
.Vb 5
\&    has [qw/iterator_class result_type/] => (
\&        is       => \*(Aqro\*(Aq,
\&        isa      => Str,
\&        required => 1,
\&    );
\&
\&    sub _build_description { return shift\->iterator_class }
.Ve
.PP
The \f(CW\*(C`iterator_class\*(C'\fR attribute is required and then the description
is set to it.  Or, there could be a more verbose description:
.PP
.Vb 4
\&    sub _build_description {
\&        my $name = shift\->iterator_class;
\&        return "Testing the $name class"
\&    }
.Ve
.SS "Requiring a builder"
.IX Subsection "Requiring a builder"
A test role can specify a lazy attribute and then require the
consuming class to provide a builder for it.
.PP
In the test role:
.PP
.Vb 3
\&    has fixture => (
\&        is => \*(Aqlazy\*(Aq,
\&    );
\&
\&    requires \*(Aq_build_fixture\*(Aq;
.Ve
.PP
In the consuming class:
.PP
.Vb 1
\&    sub _build_fixture { ... }
.Ve
.SS "Clearing fixtures"
.IX Subsection "Clearing fixtures"
If a fixture has a clearer method, it can be easily reset during testing.
This works really well with lazy attributes which get regenerated on demand.
.PP
.Vb 4
\&    has fixture => (
\&        is => \*(Aqlazy\*(Aq,
\&        clearer => 1,
\&    );
\&
\&    test "some test" => sub {
\&        my $self = shift;
\&        $self\->clear_fixture;
\&        ...
\&    };
.Ve
.SH "MODIFIERS FOR SETUP AND TEARDOWN"
.IX Header "MODIFIERS FOR SETUP AND TEARDOWN"
.SS "Setting up a fixture before testing"
.IX Subsection "Setting up a fixture before testing"
When you need to do some extra work to set up a fixture, you can put a
method modifier on the \f(CW\*(C`setup\*(C'\fR method.  In some cases, this is more
intuitive than doing all the work in an attribute builder.
.PP
Here is an example that creates an SQLite table before any tests are
run and cleans up afterwards:
.PP
.Vb 1
\&    # example/cookbook/sqlite.t
\&
\&    use Test::Roo;
\&    use DBI;
\&    use Path::Tiny;
\&
\&    has tempdir => (
\&        is      => \*(Aqro\*(Aq,
\&        clearer => 1,
\&        default => sub { Path::Tiny\->tempdir },
\&    );
\&
\&    has dbfile => (
\&        is      => \*(Aqlazy\*(Aq,
\&        default => sub { shift\->tempdir\->child(\*(Aqtest.sqlite3\*(Aq) },
\&    );
\&
\&    has dbh => ( is => \*(Aqlazy\*(Aq, );
\&
\&    sub _build_dbh {
\&        my $self = shift;
\&        DBI\->connect(
\&            "dbi:SQLite:dbname=" . $self\->dbfile, { RaiseError => 1 }
\&        );
\&    }
\&
\&    before \*(Aqsetup\*(Aq => sub {
\&        my $self = shift;
\&        $self\->dbh\->do("CREATE TABLE f (f1, f2, f3)");
\&    };
\&
\&    after \*(Aqteardown\*(Aq => sub { shift\->clear_tempdir };
\&
\&    test \*(Aqfirst\*(Aq => 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;
.Ve
.SS "Running tests during setup and teardown"
.IX Subsection "Running tests during setup and teardown"
You can run any tests you like during setup or teardown.  The previous example
could have written the setup and teardown hooks like this:
.PP
.Vb 6
\&    before \*(Aqsetup\*(Aq => 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 \*(Aqteardown\*(Aq => sub {
\&        my $self = shift;
\&        my $dir = $self\->tempdir;
\&        $self\->clear_tempdir;
\&        ok( ! \-f $dir, "tempdir cleaned up");
\&    };
.Ve
.SH "MODIFIERS ON TESTS"
.IX Header "MODIFIERS ON TESTS"
.ie n .SS "Global modifiers with ""each_test"""
.el .SS "Global modifiers with \f(CWeach_test\fP"
.IX Subsection "Global modifiers with each_test"
Modifying \f(CW\*(C`each_test\*(C'\fR triggers methods before or after \fBevery\fR test block
defined with the \f(CW\*(C`test\*(C'\fR function.  Because this affects all tests, whether
from the test class or composed from roles, it needs to be used thoughtfully.
.PP
Here is an example that ensures that every test block is run in its own
separate temporary directory.
.PP
.Vb 1
\&    # examples/cookbook/with_tempd.t
\&
\&    use Test::Roo;
\&    use File::pushd qw/tempd/;
\&    use Cwd qw/getcwd/;
\&
\&    has tempdir => (
\&        is => \*(Aqlazy\*(Aq,
\&        isa => sub { shift\->isa(\*(AqFile::pushd\*(Aq) },
\&        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 \*(Aqfirst test\*(Aq => sub {
\&        my $self = shift;
\&        is( $self\->tempdir, getcwd(), "cwd is " . $self\->tempdir );
\&        # ... more tests ...
\&    };
\&
\&    # do stuff in a separate, fresh temp directory
\&    test \*(Aqsecond test\*(Aq => sub {
\&        my $self = shift;
\&        is( $self\->tempdir, getcwd(), "cwd is " . $self\->tempdir );
\&        # ... more tests ...
\&    };
\&
\&    run_me;
\&    done_testing;
.Ve
.SS "Individual test modifiers"
.IX Subsection "Individual test modifiers"
If you want to have method modifiers on an individual test, put your
Test::More tests in a method, add modifiers to that method, and use \f(CW\*(C`test\*(C'\fR
to invoke it.
.PP
.Vb 1
\&    # examples/cookbook/hookable_test.t
\&
\&    use Test::Roo;
\&
\&    has counter => ( is => \*(Aqrw\*(Aq, default => sub { 0 } );
\&
\&    sub is_positive {
\&        my $self = shift;
\&        ok( $self\->counter > 0, "counter is positive" );
\&    }
\&
\&    before is_positive => sub { shift\->counter( 1 ) };
\&
\&    test \*(Aqhookable\*(Aq => sub { shift\->is_positive };
\&
\&    run_me;
\&    done_testing;
.Ve
.SS "Wrapping tests"
.IX Subsection "Wrapping tests"
As a middle ground between global and individual modifiers, if you need to call
some code repeatedly for some, but not all all tests, you can create a custom
test function.  This might make sense for only a few tests, but could be
helpful if there are many that need similar behavior, but you can't make it
global by modifying \f(CW\*(C`each_test\*(C'\fR.
.PP
The following example clears the fixture before tests defined with the
\&\f(CW\*(C`fresh_test\*(C'\fR function.
.PP
.Vb 1
\&    # examples/cookbook/wrapped.t
\&
\&    use strict;
\&    use Test::Roo;
\&
\&    has fixture => (
\&        is => \*(Aqrw\*(Aq,
\&        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 \*(Aqfirst\*(Aq => sub {
\&        my $self = shift;
\&        is ( $self\->fixture, \*(AqHello World\*(Aq, "fixture has default" );
\&        $self\->fixture("Goodbye World");
\&    };
\&
\&    fresh_test \*(Aqsecond\*(Aq => sub {
\&        my $self = shift;
\&        is ( $self\->fixture, \*(AqHello World\*(Aq, "fixture has default" );
\&    };
\&
\&    run_me;
\&    done_testing;
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
David Golden <dagolden@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2013 by David Golden.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve