TAP Consumers

tappy Tool

The tappy command line tool is a TAP consumer. The tool accepts TAP files or directories containing TAP files and provides a standard Python unittest style summary report. Check out tappy -h for the complete list of options. You can also use the tool’s shorter alias of tap.

$ tappy *.tap
................F..................................
======================================================================
FAIL: <file=TestParser.tap>
- The parser extracts a bail out line.
----------------------------------------------------------------------

----------------------------------------------------------------------
Ran 51 tests in 0.002s

FAILED (failures=1)

TAP Stream

tappy can read a TAP stream directly STDIN. This permits any TAP producer to pipe its results to tappy without generating intermediate output files. tappy will read from STDIN when no arguments are provided or when a dash character is the only argument.

Here is an example of nosetests piping to tappy:

$ nosetests --with-tap --tap-stream 2>&1 | tappy
......................................................................
...............................................
----------------------------------------------------------------------
Ran 117 tests in 0.003s

OK

In this example, nosetests puts the TAP stream on STDERR so it must be redirected to STDOUT because the Unix pipe expects input on STDOUT.

tappy can use redirected input from a shell.

$ tappy < TestAdapter.tap
........
----------------------------------------------------------------------
Ran 8 tests in 0.000s

OK

This final example shows tappy consuming TAP from Perl’s test tool, prove. The example includes the optional dash character.

$ prove t/array.t -v | tappy -
............
----------------------------------------------------------------------
Ran 12 tests in 0.001s

OK

API

In addition to a command line interface, tappy enables programmatic access to TAP files for users to create their own TAP consumers. This access comes in two forms:

  1. A Loader class which provides a load method to load a set of TAP files into a unittest.TestSuite. The Loader can receive files or directories.

    >>> loader = Loader()
    >>> suite = loader.load(['foo.tap', 'bar.tap', 'baz.tap'])
    
  2. A Parser class to provide a lower level interface. The Parser can parse a file via parse_file and return parsed lines that categorize the file contents.

    >>> parser = Parser()
    >>> for line in parser.parse_file('foo.tap'):
    ...     # Do whatever you want with the processed line.
    ...     pass
    

The API specifics are listed below.

class tap.loader.Loader

Load TAP lines into unittest-able objects.

load(files)

Load any files found into a suite.

Any directories are walked and their files are added as TAP files.

Returns:A unittest.TestSuite instance
load_suite_from_file(filename)

Load a test suite with test lines from the provided TAP file.

Returns:A unittest.TestSuite instance
load_suite_from_stdin()

Load a test suite with test lines from the TAP stream on STDIN.

Returns:A unittest.TestSuite instance
class tap.parser.Parser

A parser for TAP files and lines.

parse_file(filename)

Parse a TAP file to an iterable of tap.line.Line objects.

This is a generator method that will yield an object for each parsed line. The file given by filename is assumed to exist.

parse_stdin()

Parse a TAP stream from standard input.

Note: this has the side effect of closing the standard input filehandle after parsing.

parse_text(text)

Parse a string containing one or more lines of TAP output.

parse(fh)

Generate tap.line.Line objects, given a file-like object fh.

fh may be any object that implements both the iterator and context management protocol (i.e. it can be used in both a “with” statement and a “for...in” statement.)

Trailing whitespace and newline characters will be automatically stripped from the input lines.

parse_line(text)

Parse a line into whatever TAP category it belongs.

Line Categories

The parser returns Line instances. Each line contains different properties depending on its category.

class tap.line.Result(ok, number=None, description='', directive=None, diagnostics=None)

Information about an individual test line.

category
Returns:test
ok

Get the ok status.

Return type:bool
number

Get the test number.

Return type:int
description

Get the description.

skip

Check if this test was skipped.

Return type:bool
todo

Check if this test was a TODO.

Return type:bool
class tap.line.Plan(expected_tests, directive=None)

A plan line to indicate how many tests to expect.

category
Returns:plan
expected_tests

Get the number of expected tests.

Return type:int
skip

Check if this plan should skip the file.

Return type:bool
class tap.line.Diagnostic(text)

A diagnostic line (i.e. anything starting with a hash).

category
Returns:diagnostic
text

Get the text.

class tap.line.Bail(reason)

A bail out line (i.e. anything starting with ‘Bail out!’).

category
Returns:bail
reason

Get the reason.

class tap.line.Version(version)

A version line (i.e. of the form ‘TAP version 13’).

category
Returns:version
version

Get the version number.

Return type:int
class tap.line.Unknown

A line that represents something that is not a known TAP line.

This exists for the purpose of a Null Object pattern.

category
Returns:unknown