.. image:: https://travis-ci.org/herczy/quicktester.svg?branch=master
    :target: https://travis-ci.org/herczy/quicktester

quickrunner
===========

Nose plugins that will only run "relevant tests". A relevant test may be a
test associated with a git change, a previous failure, etc. The ultimate goal
is to help you, the developer to speed up the TDD's RED-GREEN-REFACTOR cycle.

In order to do this, the ``quickrunner`` module gives you a number of tools:

* the ``git-changes`` plugin lets you rerun tests possibly relevant to the
  currently changed modules.

* the ``fail-only`` plugin will only re-run tests that have failed in the
  previous run(s).

* the ``quickfix`` plugin gives nose the ability to output a file in the
  quickfix format. This can be used with ``vim`` which can parse files like
  this and jump to the relevant failure points.

Installation
------------

To install these plugins, run

::

  $ python setup.py install

or if you want to install it locally,

::

  $ python setup.py install --user

Usage
=====

The quicktester-statistics CLI tool
-----------------------------------

The ``quicktester-statistics`` tool can be used to list the states of previously
failed tests up to a given number of runs. E.g. the statistics for the last 4 runs:

::

  $ quicktester-statistics -b 4
  [..F.] package/tests/test_module.py:package.tests.test_module:TestClass.test_case

Where the test has failed before the last run.

Run tests according to the git changes
--------------------------------------

To run only tests relevant to the git changes, use:

::

  $ nosetests --git-changes

The ``git-changes`` plugin expects that the tests are in the same directory as the
modules themselves, i.e.

::

  package
  |-- subpackage
  |   |-- tests
  |   |   `-- test_something.py
  |   `-- something.py
  |-- tests
  |   `-- test_module.py
  `-- module.py

Otherwise all tests may not run.

*New in 0.2*: A further reduction of test cases is to match the names of the modules
to the (hopefully) appropriate test module name. This only works if the test module
names are under the package tests with the appropriate name (i.e. ``example.py`` will
have its tests in ``tests/test_example.py``.

To use the name matching, use the ``--match-names`` extra option, i.e.:

::

  $ nosetests --git-changes --match-names

*New in 0.2*: Now there is a way to run tests in an alternative mapping too. The
``external`` mapping expects the following structure:

::

  package
  |-- subpackage
  |   `-- something.py
  `-- module.py
  <test module>
  |-- test_module.py
  `-- subpackage
      `-- test_something.py

To turn this more on, specify the ``--separate-tests <test module>`` extra option, e.g.:

::

  $ nosetests --git-changes --separate-tests tests

Run only previously failed tests
--------------------------------

To run tests that have failed thrice in the last runs, use:

::

  $ nosetests --run-count 3

Create quickfix file
--------------------

To create a quickfix file with the exception trace positions, use:

::

  $ nosetests -Q /path/to/quickfix

This will only list exception trace positions relative to the current
working directory (i.e. it will not list positions in the ``os`` module).
To get the 'irrelevant' positions too, use the ``--qf-irrelevant`` option:

::

  $ nosetests -Q /path/to/quickfix --qf-irrelevant

*New in 0.2*: With Python versions 3+, the quickfix file will contain the
whole exception chain.

Usage in vi
...........

*New in 0.2*: Read the next section for a solution.

There are multiple ways to use this plugin, the simplest being:

::

  :cex system('nosetests -Q /tmp/quickfix')

But this will print nothing. A better ``vim`` script may be:

::

  execute ':!nosetests -Q /tmp/nose-quickfix --git-changes'
  cfile /tmp/nose-quickfix

VIM plugin
----------

*New in 0.2*: Now quicktester contains a Vim plugin using the quicktester
nosetest features. The Vim plugin can be found at
``<python prefix>/share/quicktester/quicktester.vim``. To use this plugin,
simply copy the file into your Vim plugin directory (``~/.vim/plugin`` or
``/usr/share/vim/plugin``.

The plugin defines two commands:

 * ``Nose`` will simply run nosetests without any of the quicktester plugins.

 * ``Quicktest`` will run nosetests for the git changes (if there's been no failure)
   or for the previously failed tests (if there's been a failure). If there are any
   errors, the quickfix file will be loaded and you can navigate with the usual
   commands (``:cf``, ``:cn``, ...)

By default, the plugin uses the default Python executable, but the ``g:python`` global
variable can be used to change this to a user-specified behavior.
