/ 
Fennec-0.024
River stage one • 9 direct dependents • 9 total dependents
/ Fennec::UserManual::Tests

NAME

Fennec::UserManual::Tests - Examples of Fennec Tests

DESCRIPTION

This document is the primer for fennec. It gives a synopsis of fennec capabilities. After this introduction you should move on to Fennec::Manual::TestSuite for more info.

SYNOPSIS

This is an example fennec test using all default workflow styles.

t/MyTest.t

Boilerplate

#!/usr/bin/perl;
package TEST::MyTest;
use strict;
use warnings;
use Fennec::Standalone;

# If the module specified is not installed all tests will be skipped
use_or_skip 'Module::Name';

# Tests and workflows (See following headings)
...

# Standalone tests need this
done_testing;

Tests in package space

Tests can be made script style, but you loose parallelization

ok( 1, "Not grouped" );
is( 'a', 'a', "" );
...

Tests in groups

It is much better to put tests into parallelizable groups. Devel::Declare is used to provide a freindly syntax. As well all test groups are run as methods against an instance of your test class, $self is automatically shifted for you.

tests "hello world group" {
    ok( $self, 'Automatically get $self' );
    ok( 1, "Hello world" );
}

RSPEC like testing

describe 'my group' {
    before_each { $self->reset }

    # 'it()' is an alias to 'tests()'
    it 'my test' {
        ok( 1, 'spec test!' )
    }

    # Nested!
    describe ...;
}

Tests under multiple cases

You can run the same TestSets under multiple cases using the Case workfow (loaded by default).

cases some_cases {
    case a => sub { ... }
    case b => sub { ... }
    tests a => sub { ... }
    tests b => sub { ... }
}

Tests as object methods

You can also define test groups, setups, and teardowns as methods on your test object.

sub setup_my_setup {
    my $self = shift;
    print "methods prefixed by setup_ will be run before tests defined as methods.";
}

sub test_method_as_test_by_prefix {
    my $self = shift;
    ok( 1, "methods prefixed by test_ will be run as method." );
}

sub teardown_my_teardown {
    my $self = shift;
    print "method prefixed by teardown_ will be run after tests defined as methods."
}

Breakdown

package TEST::MyTest;

Fennec tests must all be contained inside test packages, they will be used as objects.

use_or_skip 'Module::Name'

Works just like 'use', however if the module requested is not installed all tests will be skipped with 'Module::Name not installed' as the message. This can be used at the start of any test that should only be run when a specific other module is installed.

ok( 1, "Not grouped" )

Tests can be anywhere between 'use Fennec::Standalone' and 'done_testing()'. This means you can write Test::Builder style tests using fennec. The problem with this is that the tests are run as they are encountered. When you put tests into groups and workflows they can be parallelized, and are run later.

tests hello_world_group => sub { ... }

This declares a test group named hello_world_group. Tests groups will be run in random order (unless randomization is disabled), and are usually run in parallel, so it makes sense to seperate your tests into small groups.

describe { ... }

Define an RSPEC like workflow. This is available as long as the Fennec::Workflow::SPEC workflow is loaded. (Loaded by default)

cases { ... }

Create a case workflow using cases({...}), then define several cases and testsets within. Each testset will be run under each case; that is that case 'a' will be run, followed by each of the tests, followed by case 'b' and all the tests again, etc.

sub setup_NAME { ... }
sub test_NAME { ... }
sub teardown_NAME { ... }

Using the Fennec::Workflow::Methods workflow you can simply define methods with the tests_, setup_ and teardown_ prefixes to create a subset where the setups are run, followed by the tests, followed by the teardowns. (Note: The prefixes are case-insensitive, you can use sub tEsTs_NaMe { ... }, but please don't)

Note: setups and teardowns defined in this manner only effects testsets also defined in this manner. They will not effect testsets defined using the tests { ... } function.

SKIP AND TODO

Fennec has the concept of todo tests, tests which are expected to fail. You can also mark groups as skip if they are really bad.

If an exception is thrown within a TODO block or set, a failing TODO result will be generated alerting you. This is a todo test and will not count as a failure in the grand scheme.

#!/usr/bin/perl;
package TEST::MyStandaloneTest;
use strict;
use warnings;
use Fennec::Standalone;

# This will run, but failures will not count.
tests not_yet_implemented => (
    todo => "This will fail",
    method => sub {
        my $self = shift;
        ok( 0, "Hello world" );
    },
);

# This will be skipped completely
tests 'would die' => (
    skip => "This will die",
    method => sub {
        my $self = shift;
        die( "I eat you" );
    },
);

# You can also TODO specific asserts.
tests 'some pass' => sub {
    ok( 1, 'pass' );
    TODO {
        ok( 0, 'fail' );
    } "This will fail, I will fix it later";
}

# Do not forget this!
done_testing();

1;

USER DOCUMENTATION

User documentation is for those who wish to use Fennec to write simple tests, or manage a test suite for a project.

Fennec::UserManual

DEVELOPER DOCUMENTATION

Developer documentation is for those who wish to extend Fennec, or contribute to overall Fennec development.

Fennec::DeveloperManual

API DOCUMENTATION

API Documentation covers object internals. See the POD within each individual module.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

Fennec is free software; Standard perl licence.

Fennec is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.