test::routine::common(3pm) [debian man page]

Test::Routine::Common(3pm)				User Contributed Perl Documentation				Test::Routine::Common(3pm)

NAME

       Test::Routine::Common - a role composed by all Test::Routine roles

VERSION

       version 0.015

OVERVIEW

       Test::Routine::Common provides the "run_test" method described in the docs on writing tests in Test::Routine.

AUTHOR

       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Ricardo Signes.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

perl v5.14.2							    2012-03-16						Test::Routine::Common(3pm)

Test::Routine::Manual::Demo(3pm)			User Contributed Perl Documentation			  Test::Routine::Manual::Demo(3pm)

NAME

       Test::Routine::Manual::Demo - a walkthrough, in code, of Test::Routine

VERSION

       version 0.015

The Demo
   t/demo/01-demo.t
	 #!/bin/env perl
	 use strict;
	 use warnings;

	 # This test is both a test and an example of how Test::Routine works!	Welcome
	 # to t/01-demo.t, I will be your guide, rjbs.

	 {
	   # This block defines the HashTester package.  It's a Test::Routine, meaning
	   # it's a role.  We define state that the test will need to keep and any
	   # requirements we might have.
	   #
	   # Before we can run this test, we'll need to compose the role into a class so
	   # that we can make an instance.
	   package HashTester;
	   use Test::Routine;

	   # We import stuff from Test::More because, well, who wants to re-write all
	   # those really useful test routines that exist out there?  Maybe somebody,
	   # but not me.
	   use Test::More;

	   # ...but then we use namespace::autoclean to get rid of the routines once
	   # we've bound to them.  This is just standard Moose practice, anyway, right?
	   use namespace::autoclean;

	   # Finally, some state!  Every test will get called as method on an instance,
	   # and it will have this attribute.  Here are some points of interest:
	   #
	   # - We're giving this attribute a builder, so it will try to get built with a
	   #   call to $self->build_hash_to_test -- so each class that composes this
	   #   role can provide means for these attributes (fixtures) to be generated as
	   #   needed.
	   #
	   # - We are not adding "requires 'build_hash_to_test'", because then we can
	   #   apply this role to Moose::Object and instantiate it with a given value
	   #   in the constructor.  There will be an example of this below.  This lets
	   #   us re-use these tests in many variations without having to write class
	   #   after class.
	   #
	   # - We don't use lazy_build because it would create a clearer.  If someone
	   #   then cleared our lazy_build fixture, it could not be re-built in the
	   #   event that we'd gotten it explicitly from the constructor!
	   #
	   # Using Moose attributes for our state and fixtures allows us to get all of
	   # their powerful behaviors like types, delegation, traits, and so on, and
	   # allows us to decompose shared behavior into roles.
	   #
	   has hash_to_test => (
	     is  => 'ro',
	     isa => 'HashRef',
	     builder => 'build_hash_to_test',
	   );

	   # Here, we're just declaring an actual test that we will run.  This sub will
	   # get installed as a method with a name that won't get clobbered easily.  The
	   # method will be found later by run_tests so we can find and execute all
	   # tests on an instance.
	   #
	   # There is nothing magical about this method!  Calling this method is
	   # performed in a Test::More subtest block.  A TAP plan can be issued with
	   # "plan", and we can issue TODO or SKIP directives the same way.  There is
	   # none of the return-to-skip magic that we find in Test::Class.
	   #
	   # The string after "test" is used as the method name -- which means we're
	   # getting a method name with spaces in it.  This can be slightly problematic
	   # if you try to use, say, ::, in a method name.  For the most part, it works
	   # quite well -- but look at the next test for an example of how to give an
	   # explicit description.
	   test "only one key in hash" => sub {
	     my ($self) = @_;

	     my $hash = $self->hash_to_test;

	     is(keys %$hash, 1, "we have one key in our test hash");
	     is(2+2, 4, "universe still okay");
	   };

	   # The only thing of note here is that we're passing a hashref of extra args
	   # to the test method constructor.  "desc" lets us set the test's description,
	   # which is used in the test output, so we can avoid weird method names being
	   # installed.  Also note that we order tests more or less by order of
	   # definition, not by name or description.
	   test second_test => { desc => "Test::Routine demo!" } => sub {
	     pass("We're running this test second");
	     pass("...notice that the subtest's label is the 'desc' above");
	     pass("...and not the method name!");
	   };
	 }

	 {
	   # This package is one fixture against which we can run the HashTester
	   # routine.  It has the only thing it needs:	a build_hash_to_test method.
	   # Obviously real examples would have more to them than this.
	   package ProcessHash;
	   use Moose;
	   with 'HashTester';

	   use namespace::autoclean;

	   sub build_hash_to_test { return { $$ => $^T } }
	 }

	 # Now we're into the body of the test program:  where tests actually get run.

	 # We use Test::Routine::Util to get its "run_tests" routine, which runs the
	 # tests on an instance, building it if needed.
	 use Test::Routine::Util;

	 # We use Test::More to get done_testing.  We don't assume that run_tests is the
	 # entire test, because that way we can (as we do here) run multiple test
	 # instances, and can intersperse other kinds of sanity checks amongst the
	 # Test::Routine-style tests.
	 use Test::More;

	 is(2+2, 4, "universe still makes sense") or BAIL_OUT("PANIC!");

	 # The first arg is a description for the subtest that will be run.  The second,
	 # here, is a class that will be instantiated and tested.
	 run_tests('ProcessHash class' => 'ProcessHash');

	 # Here, the second argument is an instance of a class to test.
	 run_tests('ProcessHash obj' => ProcessHash->new({ hash_to_test => { 1 => 0 }}));

	 # We could also just supply a class name and a set of args to pass to new.
	 # The below is very nearly equivalent to the above:
	 run_tests('ProcessHash new' => ProcessHash => { hash_to_test => { 1 => 0 }});

	 # ...and here, the second arg is not a class or instance at all, but the
	 # Test::Routine role (by name).  Since we know we can't instantiate a role,
	 # run_tests will try to compose it with Moose::Object.  Then the args are used
	 # as the args to ->new on the new class, as above.  This lets us write
	 # Test::Routines that can be tested with the right state to start with, or
	 # Test::Routines that need to be composed with testing fixture classes.
	 run_tests(
	   'HashTester with given state',
	   HashTester => {
	     hash_to_test => { a => 1 },
	   },
	 );

	 # There's one more interesting way to run out tests, but it's demonstrated in
	 # 02-simple.t instead of here.  Go check that out.

	 # ...and we're done!
	 done_testing;

   t/demo/02-simple.t
	 # Welcome to part two of the Test::Routine demo.  This is showing how you can
	 # write quick one-off tests without having to write a bunch of .pm files or
	 # (worse?) embed packages in bare blocks in the odious way that 01-demo.t did.
	 #
	 # First off, we use Test::Routine.  As it did before, this turns the current
	 # package (main!) into a Test::Routine role.  It also has the pleasant
	 # side-effect of turning on strict and warnings.
	 use Test::Routine;

	 # Then we bring in the utils, because we'll want to run_tests later.
	 use Test::Routine::Util;

	 # And, finally, we bring in Test::More so that we can use test assertions, and
	 # namespace::autoclean to clean up after us.
	 use Test::More;
	 use namespace::autoclean;

	 # We're going to give our tests some state.  It's nothing special.
	 has counter => (
	   is  => 'rw',
	   isa => 'Int',
	   default => 0,
	 );

	 # Then another boring but useful hunk of code: a method for our test routine.
	 sub counter_is_even {
	   my ($self) = @_;
	   return $self->counter % 2 == 0;
	 }

	 # Then we can write some tests, just like we did before.  Here, we're writing
	 # several tests, and they will be run in the order in which they were defined.
	 # You can see that they rely on the state being maintained.
	 test 'start even' => sub {
	   my ($self) = @_;
	   ok($self->counter_is_even, "we start with an even counter");

	   $self->counter( $self->counter + 1);
	 };

	 test 'terminate odd' => sub {
	   my ($self) = @_;

	   ok(! $self->counter_is_even, "the counter is odd, so state was preserved");
	   pass("for your information, the counter is " . $self->counter);
	 };

	 # Now we can run these tests just by saying "run_me" -- rather than expecting a
	 # class or role name, it uses the caller.  In this case, the calling package
	 # (main!) is a Test::Routine, so the runner composes it with Moose::Object,
	 # instantiating it, and running the tests on the instance.
	 run_me;

	 # Since each test run gets its own instance, we can run the test suite again,
	 # possibly to verify that the test suite is not destructive of some external
	 # state.
	 run_me("second run");

	 # And we can pass in args to use when constructing the object to be tested.
	 # Given the tests above, we can pick any starting value for "counter" that is
	 # even.
	 run_me({ counter => 192 });

	 # ...and we're done!
	 done_testing;

	 # More Test::Routine behavior is demonstrated in t/03-advice.t and t/04-misc.t
	 # Go have a look at those!

   t/demo/03-advice.t
	 use Test::Routine;
	 use Test::Routine::Util;
	 use Test::More;

	 use namespace::autoclean;

	 # xUnit style testing has the idea of setup and teardown that happens around
	 # each test.  With Test::Routine, we assume that you will do most of this sort
	 # of thing in your BUILD, DEMOLISH, and attribute management.	Still, you can
	 # easily do setup and teardown by applying method modifiers to the "run_test"
	 # method, which your Test::Routine uses to run each test.  Here's a simple
	 # example.

	 # We have the same boring state that we saw before.  It's just an integer that
	 # is carried over between tests.
	 has counter => (
	   is	=> 'rw',
	   isa	=> 'Int',
	   lazy => 1,
	   default => 0,
	   clearer => 'clear_counter',
	 );

	 # The first test changes the counter's value and leaves it changed.
	 test test_0 => sub {
	   my ($self) = @_;

	   is($self->counter, 0, 'start with counter = 0');
	   $self->counter( $self->counter + 1);
	   is($self->counter, 1, 'end with counter = 1');
	 };

	 # The second test assumes that the value is the default, again.  We want to
	 # make sure that before each test, the counter is reset, but we don't want to
	 # tear down and recreate the whole object, because it may have other, more
	 # expensive resources built.
	 test test_1 => sub {
	   my ($self) = @_;

	   is($self->counter, 0, 'counter is reset between tests');
	 };

	 # ...so we apply a "before" modifier to each test run, calling the clearer on
	 # the counter.  When next accessed, it will re-initialize to zero.  We could
	 # call any other code we want here, and we can compose numerous modifiers
	 # together onto run_test.
	 #
	 # If you want to clear *all* the object state between each test... you probably
	 # want to refactor.
	 before run_test => sub { $_[0]->clear_counter };

	 run_me;
	 done_testing;

   t/demo/04-misc.t
	 use Test::Routine;
	 use Test::Routine::Util;
	 use Test::More;

	 use namespace::autoclean;

	 # One thing that the previous examples didn't show was how to mark tests as
	 # "skipped" or "todo."  Test::Routine makes -no- provisions for these
	 # directives.	Instead, it assumes you will use the entirely usable mechanisms
	 # provided by Test::More.

	 # This is a normal test.  It is neither skipped nor todo.
	 test boring_ordinary_tests => sub {
	   pass("This is a plain old boring test that always passes.");
	   pass("It's here just to remind you what they look like.");
	 };

	 # To skip a test, we just add a "skip_all" plan.  Because test methods get run
	 # in subtests, this skips the whole subtest, but nothing else.
	 test sample_skip_test => sub {
	   plan skip_all => "these tests don't pass, for some reason";

	   is(6, 9, "I don't mind.");
	 };

	 # To mark a test todo, we just set our local $TODO variable.  Because the test
	 # is its own block, this works just like it would in any other Test::More test.
	 test sample_todo_test => sub {
	   local $TODO = 'demo of todo';

	   is(2 + 2, 5, "we can bend the fabric of reality");
	 };

	 run_me;
	 done_testing;

   t/demo/05-multiple.t
	 #!/bin/env perl
	 use strict;
	 use warnings;

	 use Test::Routine::Util;
	 use Test::More;

	 # One of the benefits of building our sets of tests into roles instead of
	 # classes is that we can re-use them in whatever combination we want.	We can
	 # break down sets of tests into bits that can be re-used in different cases.
	 # With classes, this would lead to multiple inheritance or other monstrosities.

	 # Here's a first Test::Routine.  We use it to make sure that one of our
	 # fixture's attributes is a numeric id.
	 {
	   package Test::ThingHasID;
	   use Test::Routine;
	   use Test::More;

	   requires 'id';

	   test thing_has_numeric_id => sub {
	     my ($self) = @_;

	     my $id = $self->id;
	     like($id, qr/A[0-9]+z/, "the thing's id is a string of ascii digits");
	   };
	 }

	 # A second one ensures that the thing has an associated directory that
	 # looks like a unix path.
	 {
	   package Test::HasDirectory;
	   use Test::Routine;
	   use Test::More;

	   requires 'dir';

	   test thing_has_unix_dir => sub {
	     my ($self) = @_;

	     my $dir = $self->dir;
	     like($dir, qr{A(?:/w+)+/?z}, "thing has a unix-like directory");
	   };
	 }

	 # We might have one class that is only expected to pass one test:
	 {
	   package JustHasID;
	   use Moose;

	   has id => (
	     is      => 'ro',
	     default => sub {
	       my ($self) = @_;
	       return Scalar::Util::refaddr($self);
	     },
	   );
	 }

	 # ...and another class that should pass both:
	 {
	   package UnixUser;
	   use Moose;

	   has id  => (is => 'ro', default => 501);
	   has dir => (is => 'ro', default => '/home/users/rjbs');
	 }

	 # So far, none of this is new, it's just a slightly different way of factoring
	 # things we've seen before.  In t/01-demo.t, we wrote distinct test roles and
	 # classes, and we made our class compose the role explicitly.	This can be
	 # a useful way to put these pieces together, but we also might want to write
	 # all these classes and roles as unconnected components and compose them only
	 # when we're ready to run our tests.  When we do that, we can tell run_tests
	 # what to put together.
	 #
	 # Here, we tell it that we can test JustHasID with Test::ThingHasID:
	 run_tests(
	   "our JustHasID objects have ids",
	   [ 'JustHasID', 'Test::ThingHasID' ],
	 );

	 # ...but we can run two test routines against our UnixUser class
	 run_tests(
	   "unix users have dirs and ids",
	   [ 'UnixUser', 'Test::ThingHasID', 'Test::HasDirectory' ],
	 );

	 # We can still use the "attributes to initialize an object," and when doing
	 # that it may be that we don't care to run all the otherwise applicable tests,
	 # because they're not interesting in the scenario we're creating.  For
	 # example...
	 run_tests(
	   "a trailing slash is okay in a directory",
	   [ 'UnixUser', 'Test::HasDirectory' ],
	   { dir => '/home/meebo/' },
	 );

	 # ...and we're done!
	 done_testing;

AUTHOR

       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Ricardo Signes.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

perl v5.14.2							    2012-03-16					  Test::Routine::Manual::Demo(3pm)