Test Repository users manual
++++++++++++++++++++++++++++

Overview
~~~~~~~~

Test repository is a small application for tracking test results. Any test run
that can be represented as a subunit stream can be inserted into a repository.

Typical workflow is to have a repository into which test runs are inserted, and
then to query the repository to find out about issues that need addressing. For
instance, using the sample subunit stream included with Test repository::

  # Create a store to manage test results in.
  $ testr init
  # add a test result (shows failures)
  $ testr load < doc/example-failing-subunit-stream
  # see the tracked failing tests again
  $ testr failing
  # fix things
  $ testr load < doc/example-passing-subunit-stream
  # Now there are no tracked failing tests
  $ testr failing

Most commands in testr have comprehensive online help, and the commands::
  $ testr help
  $ testr commands

Will be useful to explore the system.

Test Repository can be taught how to run your tests by setting up a .testr.conf
file in your cwd. A file like::

  [DEFAULT]
  test_command=foo $IDOPTION
  test_id_option=--bar $IDFILE

will cause 'testr run' to run 'foo | testr load', and 'testr run --failing' to
run 'foo --bar failing.list | testr load'. failing.list will be a newline
separated list of the test ids that your test runner outputs. Arguments passed
to run are passed through to your test runner command line. To pass options
through to your test running, use a ``--`` before your options.
For instance, ``testr run foo -- bar --no-plugins`` would run
``foo foo bar --no-plugins | testr load`` using the above config example. The
command help for ``testr run`` describes the availableoptions for .testr.conf.

Having setup a .testr.conf, a common workflow then becomes::

  # Fix currently broken tests - repeat until there are no failures.
  $ testr run --failing
  # Do a full run to find anything thrown out during the reduction process.
  $ testr run
  # And either commit or loop around this again depending on whether errors
  # were found.
