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

NAME

Fennec::Manual - Manual for Fennec.

DESCRIPTION

Fennec provides a solid base that is highly extendable. It allows for the writing of custom nestable workflows (like RSPEC), Custom Asserts (like Test::Exception), Custom output handlers (Alternatives to TAP), Custom file types, and custom result passing (collectors). In Fennec all test files are objects. Fennec also solves the forking problem, thats it, forking just plain works.

THE QUICK AND DIRTY FENNEC PITCH

Fennec is not just good for writing new tools, it comes with everything the common Test::Builder tools provide and more. Here is a list of things Fennec does for you that not everything else thinks of:

Test grouping

tests 'Group A' => sub {
    ok( 1, "1 is true!" );
    ok( 2, "2 is too!" );
};

Usually you group similar tests together anyway, why not isolate them? Doing this also allows you to run groups in parallel, or run only the group on which you are currently working.

Handy workflows to make testing tasks easier

RSPEC like:

describe 'Workflow' => sub {
    my $self = shift;
    before_each { $self->do_something };
    it { ok( 1, "1 is true!" ) };
    it { ok( 2, "2 is true!" ) };
    after_each { $self->do_something_else };
};

Case:

cases {
    my $var;
    case { $var = 1 };
    case { $var = 2 };
    tests { ok( $var, "var is true" ) };
    tests { ok( is_prime($var), "var is prime" )};
}

These workflows come with Fennec, they sure do make life easier! It is also fairly easy to use Fennecs framework to write custom workflows.

Running subsets of tests

These commands can be used to run a subset of tests within a specified test file:

$ FENNEC_ITEM="item name" FENNEC_FILE="Filename" prove -I lib -v t/Fennec.t
$ FENNEC_ITEM="line number" FENNEC_FILE="Filename" prove -I lib -v t/Fennec.t

Thats right, you can specify a group or workflow name, or even a line number! Only that workflow ro group will be run, no waiting around for other tests to get at what you care about. Line number can be any line number across which the workflow or group is defined.

Parallelizing test groups within test files

See 'Test grouping'. Each group can be run in parrallel.

Object oriented test files

All test groups and workflows are blessed methods. Your test file defines a package, which is initialized. All groups and workflows are run as methods on the same test object (May be in different processes).

Command line tools to make life easier

Create t/Fennec.t with a good default config:

$ cd project_dir
$ fennec_init

Create scaffold tests for every module in /lib

$ cd project_dir
$ fennec_scaffold

Run a specific test file:

$ cd project_dir
$ fennec_prove t/MyModule.pm - [prove options]

Run a specific test group by line number or name:

$ cd project_dir
$ fennec_prove t/MyModule.pm "My Group" [prove options]

Test Randomization

Test groups are run in random order by default. You can easily disable randomization if needed on a global or per test basis. Fennec prints out its random seed so you can reproduce the order if necessary.

USAGE DOCUMENTATION

This covers basic usage of Fennec if you just want to start writing tests.

Tests

Fennec::Manual::Tests - Examples of different fennec tools.

Fennec Based Test Suite

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

Standalone

Fennec::Manual::Standalone - Write fennec tests that stand on their own.

Command Line Tools

Fennec::Manual::CommandLine - Command line tools provided by Fennec.

Vim tools

Fennec::Manual::Vim - Vim tools and rc files provided with the dist.

Running Fennec

Fennec::Manual::Running - How to run individual Fennec test files, or zeroing in on specific testsets.

ASSERTIONS (TESTERS)

Assertions are the actuals testers. ok(), is(), etc. are all assertions. A testset is comprised of 0 or more such assertions. Each assertion sends a result to the handler(s).

Each testset itself generates an additional result when completed. Testset results are true if the testset lived, false if it died. This allows the use of 'traditional' assertions which do nothing if successful, but die upon failure. Most Fennec assertions work like Test::Builder based tools, they do not die upon failure.

Writing Assertion Libraries

Fennec::Manual::Assertions - Guide to writing custom assertion libraries

Using Test::Builder Based Tools

Many Test::Builder tools will work as expected within Fennec, however some may require, or can be improved by wrapping them into Fennec.

Fennec::Manual::TBAssertions - Using Test::Builder based tools with Fennec.

Core Assertion Libraries

Many of these were named to reflect which Test::XXX module they mimic. All Core assertion libraries are imported by default.

Fennec::Assert::Core::Simple - ok(), use_ok, and similar assertions.

Fennec::Assert::Core::More - Assertions for comparing data and structures.

Fennec::Assert::Core::Exception - Assertions for testing exceptions.

Fennec::Assert::Core::Warn - Assertions for testing warnings.

Fennec::Assert::Core::Anonclass - Create anonymous objects based on specifications, created objetcs will have assertions as methods ($obj->is(), $obj->can_ok(), etc...)

TBCore Assertion Libraries

If you prefer to use the well tested and commonly used Test::Builder based tools instead of the Fennec implementations then Fennec::Assert::TBCore is here to serve you.

Fennec::Assert::TBCore::Simple - Test::Simple

Fennec::Assert::TBCore::More - Test::More

Fennec::Assert::TBCore::Exception - Test::Exception

Fennec::Assert::TBCore::Warn - Test::Warn

WORKFLOWS

Workflows are ways to seperate, group, and structure tests. A good example of a test workflow would be Ruby's RSPEC. Fennec has an implementation of the SPEC workflow in addition to others.

Writing Custom Workflows

Fennec::Manual::Workflows

Core workflows

Fennec::Workflow::Module - Workflow that lets you define testsets and setup/teardown as methods on your test object.

Fennec::Workflow::Spec - Implementation of the SPEC test workflow

Fennec::Workflow::Case - A workflow that lets you run testsets under multiple cases.

RESULT HANDLERS

A Result handler is a single object in the root process to which all results are passed as they are collected. The handler is responsible for doing something useful with them. The default handler is the TAP handler which provides TAP output. Multiple handlers can be used at a time, and they can do anything they want with the results.

Writing Custom Handlers

Fennec::Manual::Handlers

Core Handlers

Fennec::Handler::TAP - Produces TAP output for result objects.

COLLECTORS

Fennec has test parallelization, this means forking into multiple processes. Collectors are responsible for funneling all results to the parent process where they are then sent to handlers. A collector needs to implement 2 things, a writer method that takes results as input, and a cull method which collects the results.

Writing Custom Collectors

Fennec::Manual::Collectors

Core Collectors

Fennec::Collectors::Files - The default, writes results as files in _results, then in the parent process these files are read.

Fennec::Collectors::Interceptor - Used by Fennec::Assert::Interceptor in order to capture results instead of sending them to the handlers, this is not a true collector, but a perfectly valid use of the framework.

FILE TYPES

When Fennec was first conceptualized there was mention of TestML http://www.testml.org, as well I decided it would be useful to be able to customise how test files are found/loaded. This led me to make loading test files a pluggable system. Using custom file loaders you can potentially use any type of test files you would like.

*There is not currently a TestML plugin, sorry.

Writing Custom File Types

Fennec::Manual::Files

Core File Loaders

Fennec::FileLoader::Module - The default, looks for .pm files in t/ and loads them as standard perl modules.

Fennec::FileLoader::Standalone - Used in standalone tests.

OTHER DOCUMENTATION

Mission

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

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.