The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Less-0.11
River stage zero No dependents
++
/ Test::Less

NAME

Test::Less - Test Categorization and Subset Execution

SYNOPSIS

    # Mark foo and bar tests with 4 tags
    > test-less -tag slow unit 3743 gui t/foo.t t/bar.t

    # Unmark t/bar.t as a gui test
    > test-less -untag gui t/bar.t
    
    # Show tags for all the tests in t/
    > test-less -show t/*.t

    # List the unit tests for ticket 3743, except the gui ones
    > test-less -list unit,3743,^gui

    # Prove (run) all gui unit tests
    > test-less -prove -v gui,unit

    # Same as above
    > prove -l `test-less -list gui,unit`

    # Without `test-less` program:
    > perl -MTest::Less -e "run" -prove -l gui,unit

DESCRIPTION

Sometimes Less is More.

Test::Less really has nothing to do with Test::More. It is also not meant to discourage you from writing lots of tests. To the contrary, it allows you to write potentially thousands of tests, but then be selective about which ones you run and when.

The fact is that sometimes Test::Harness testing can be slow. You don't always want to run every test in your t/ directory, especially if they take an hour or more to run.

Test::Less allows you to categorize your tests with keyword tags, and then select which group of tests should be run for the problem at hand.

COMMAND LINE USAGE

Test::Less installs a program called test-less in your Perl bin directory. You use this command to tag, list and run your various groups of tests.

test-less normally keeps the index file of mappings between tags and test files, in a file called t/Test-Less/index.txt. You can override this with the --file option or the TEST_LESS_INDEX environment variable.

TAGS

Tags are strings matching /^[\w\-]+$/.

The -list and -prove commands take what is called a tag specification.

A specication is a a list of tags and possibly file names.

    test-less -prove foo bar baz

Runs all the foo tests, bar tests and baz tests.

    test-less -prove foo,bar,baz

Runs all the tests that are foo and bar and baz.

    test-less -prove foo,^bar

Runs all the tests that are foo but not bar.

    test-less -prove ^foo

Runs all the tests that are in the Test-Less index file, except the foo ones.

etc...

You can pipe the output of one command to another:

    test-less -list foo | test-less -prove -
    test-less -lisr foo | test-less -untag bar

PROGRAMATIC USAGE

Test::Less is object oriented, and it is very easy to use its functionality from another program:

    use Test::Less;

    my $tl = Test::Less->new(
        index_file => 'my_index',
    );

    $tl->prove('-l', '-b', 'foo,bar,^baz boom');

THE INDEX FILE

Test::Less keeps all of its tag and file mappings in a text file called (by default) t/Test-Less/index.txt. This file is autogenerated by Test::Less but can be edited by hand. The file consists of comment lines (that begin with #) and index lines of the form:

    tag file    optional_comment

The index lines are written in sorted order by tag and then file. This rather verbose format is used so that it plays nice with revision control on projects where many people are changing the file.

ENVIRONMENT VARIABLES

Test::Less uses some special purpose environment variables.

TEST_LESS_INDEX

The path to the index file to be used by test-less.

TEST_LESS_COMMENT

A comment string to be added to new index entries. $d and $u are special variables that expanf to GMT date/time and current user.

    TEST_LESS_COMMENT='$d -- $u'

will expand to something like:

    Jun  4 23:22:12 2005 GMT -- ingy

TIPS AND TRICKS

Here are some helpful tips from my personal experience using Test::Less. If you have a helpful tip, please send it to me, and I'll include it here.

Go ahead and check in the index.txt file into your code repository and MANIFEST file. It is useful info that other people can use if they want to.

When working on a bug fix from an RT ticket, use the ticket number as a tag. Like 2143 or rt2143.

Feel free to hand edit the index.txt file.

Consider using the following shell aliases or something equivalent:

    alias tl='test-less'
    alias tlp='test-less -prove'
    alias tlt='test-less -tag'

etc...

AUTHOR

Brian Ingerson <ingy@cpan.org>

COPYRIGHT

Copyright (c) 2005. Brian Ingerson. All rights reserved.

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

See http://www.perl.com/perl/misc/Artistic.html