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

NAME

Fennec::UserManual::Overview - A summary of Fennecs core offerings

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' {
    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' {
    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 name {
    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 or 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.

use Fennec random => $bool, sort => $bool;

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. Core Fennec assertions work like Test::Builder based tools, they do not die upon failure.

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::DeveloperManual::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 objects 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.

Core workflows

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

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

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

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.

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.

Core Collectors

Fennec::Collector::Files - The default, writes results as files in a temporary directory, then reads them in the parent process.

Fennec::Collector::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.

Core File Types

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

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.