/ 
Fennec-0.017
River stage one • 9 direct dependents • 9 total dependents
/ Fennec::Manual::Quickstart

NAME

Fennec::Manual::Quickstart - Quick guide to immediate fennec usage.

DESCRIPTION

This document is the primer for fennec. It gives a synopsys of fennec capabilities using a standalone test file. After this introduction you should move on to Fennec::Manual::TestSuite For more advanced usage. Writing all your tests as standalone tests is not recommended.

NOTE ON STANDALONE

This is documentation for a standalone test, that is a test that does not require anything outside each test file. This is perfectly acceptable, but not ideal. After reading this document I recommend reading Fennec::Manual::TestSuite to create a fennec config file.

A consequence of standalone tests is a loss of parallelization, and the overhead of loading fennec for each standlone test. When fennec is used to manage a suite it is loaded only once, and it can parallelize running of both test files and test groups.

SYNOPSIS

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

t/mystandalone.t

Boilerplate

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

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

#Finish must be called at the end of your workflow declarations
finish();

1;

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.

tests hello_world_group => sub {
    my $self = shift;
    ok( 1, "Hello world" );
};

RSPEC like testing

describe 'my group' => sub {
    my $self = shift;

    before_each { $self->reset };

    # 'it()' is an alias to 'tests()'
    it 'my test' => sub {
        my $self = shift;
        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 {
    my $self = shift;
    case a => sub {
        my $self = shift;
        ...
    }
    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::MyStandaloneTest;

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

use Fennec::Standalone;

Use the standalone fennec package.

ok( 1, "Not grouped" )

Tests can be anywhere between 'use Fennec::Standalone' and 'finish()'. 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.

finish()

Fennec runs your test groups and workflows after the package is loaded. In normal Fennec tests finish() is not necessary. However in Standalone tests fennec needs a trigger to tell it that the workflows are ready to be run. I appologise for this boilderplate, but it is safer than an END block.

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!
finish();

1;

NEXT STEPS - BETTER MANAGING YOUR TEST SUITE

Next you should read the TestSuite documentation.

Fennec::Manual::TestSuite

EARLY VERSION WARNING

Fennec is still under active development, many features are untested or even unimplemented. Please give it a try and report any bugs or suggestions.

DOCUMENTATION

QUICK START

Fennec::Manual::Quickstart - Drop Fennec standalone tests into an existing suite.

FENNEC BASED TEST SUITE

Fennec::Manual::TestSuite - How to create a Fennec based test suite.

MISSION

Fennec::Manual::Mission - Why does Fennec exist?

MANUAL

Fennec::Manual - Advanced usage and extending Fennec.

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.