NAME

Test::StructuredObject - Use a structured execution-graph to create a test object which runs your tests smartly.

VERSION

version 0.01000010

SYNOPSIS

    use Test::More;
    use Test::StructuredObject;

    my $testsuite = testsuite(
        test { use_ok('Foo'); },
        test { is( Foo->value, 7, 'Magic value' },
        step { note "This is a step!"; }
        testgroup( 'This is a subtest' => (
            test { ok( 1, 'some inner test' ) },
            test { ok( 1, 'another inner test' ) },
        ))
    );

    # Employs Test::More's very recent 'subtest' call internally to do subtesting.

    $testsuite->run();

    # Flattens the subtests into a linear fashion instead, decorated with 'note''s  for older Test::More's
    $testsuite->linearize->run();

    # Prints a simplistic (non-reversable) serialisation of the testsuite or diagnostic purposes.
    print $testsuite->to_s;

DESCRIPTION

This technique has various perks:

1. No need to count tests manually

2. Tests are still counted internally:

Test harness can report tests that failed to run.

3. Tests are collected in a sort of state-graph of sorts:

This is almost A.S.T. like in nature, which permits various run-time permutations of the graph for different results.

4. Every test { } closure is executed in an eval { }:

This makes subsequent tests not get skipped if one dies.

5. Internal storage of many simple sub-calls:

This allows reasonably good Deparse introspection, so if need be, the entire execution tree can easily be rewritten to be completely Test::StructuredObject free.

However, it has various downsides, which for most things appear reasonable to me:

1. Due to lots of closures:

Due to this, the only present variable transience is achieved via external lexical variables.

A good solution to this I've found is just pre-declare all your needed variables and pretend they're like CPU registers =).

2. Closures break ->import in many cases:

Due to closure techniques, code that relies on ->import to do lexical scope mangling may not work.

That is pesky for various reasons, but on average its not a problem, as it is, existing Test files need that BEGIN{ use_ok } stuff to get around this issue anyway.

But basically, all you need to do is 'use' in your file scope in these cases, or use Fully Qualified sub names instead.

If neither of these solutions appeals to you, YOU DON'T HAVE TO USE THIS MODULE!.

EXPORTS

This module exports the following symbols by default using Sub::Exporter , and as such, you can tweak and use export tunings as supported by that module.

test

    test {  test_pragma }

This method creates a Test object containing the given code. Code is run at run-time when called on the objects ->run method. The code is run in an eval container and as such will not die. Deaths called inside the eval will merely be downgraded to warnings and passed to carp. See the run documentation for details.

This object type is recognised by containing types, and presence of such types increments the relevant number of planned tests at various levels.

step

    step { code_step }

This method is virtually identical to the test method except that the returned object is instead an NonTest, and as such, containing types won't increment the test count when it is seen. It is advised you use this method for doing things that prepare data for the test, but don't actually do any testing. Additionally, it is advised to keep a 1-step-per-statement ratio, because I feel this may pay off one day when I get proper tree processing =).

testsuite

    testsuite( Test|NonTest|SubTest, ....   )

This method is just a sugar syntax to create a TestSuite instance. Its parameter list comprises of a list of either Test, NonTest or SubTest instances.

As a side perk, if you use the following notation instead:

    testsuite( name => (   Test | NonTest | SubTest, ...  ) )

It will behave the same as "testgroup" does.

testgroup

    testgroup( name => ( Test | NonTest | SubTest , ... ) )

This method creates a structural subgroup of tests (SubTest) with the given name. When the top TestSuite is executed in normal conditions, this runs each test of the subtest under Test::More's 'subtest' function creating pretty indented test TAP output.

This object, when linearised with ->linearize instead injects 'note' subs before and after all its children tests in the output linear test run, particularly useful for older Test::More instances.

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Kent Fredric <kentnl@cpan.org>.

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