Pinocchio is a set of extensions to the nose_ unit testing framework
for Python.

You can get the most recent version from pypi:

    https://pypi.python.org/pypi/pinocchio/

You can install it via easy_install or pip ::

    easy_install pinocchio
    pip install pinocchio

Pinocchio only works with nose 0.9a1 and above. Pinocchio is compatible with both Python versions 2 and 3.

.. Contents::

Extensions
==========

stopwatch -- selecting tests based on execution time
-----------------------------------------------------

Sometimes your unit tests just seem to take *forever*.  Well, now
you can get rid of the slow ones automatically!

The pinocchio.stopwatch extension module lets you time the unit tests
being run, and -- once times have been recorded -- then lets you
select only those that run faster than a given amount of time.  As a
bonus, the test names and run times are stored in a simple format -- a
pickled dictionary -- so you can target specific tests for speedup,
too.

Use cases
~~~~~~~~~

There's really only one use case here: your tests take too long to
run, so you and your developers aren't running them very frequently.
The stopwatch module lets you pick out the fast ones to be run via
the command line; you can always run the slow ones in your continuous
build system, right?

Options
~~~~~~~

``--with-stopwatch`` enables test timing.

``--stopwatch-file`` changes the filename used to save the pickled test
times from '.nose-stopwatch-times' to the specified file.

``--faster-than`` sets an upper time limit (in seconds) for which tests
should be run.

Examples
~~~~~~~~

See ``examples/test_stopwatch.py`` for some examples; use ::

   nosetests -w examples/ --with-stopwatch --faster-than 1 test_stopwatch.py
   nosetests -w examples/ --with-stopwatch --faster-than 1 test_stopwatch.py

to run a subset of the tests.  Note that you need to run it twice --
once to record the times (i.e. all tests will be run, independent of
the --faster-than parameter) and again to select only the "fast"
tests.

decorator -- adding attributes to tests
---------------------------------------

The attrib extension module for nose is a great way to select subsets
of tests based on attributes you've given the test functions, classes,
or methods.  But what if you don't want to modify the source code
to add the attributes?

The pinocchio.decorator extension module lets you provide the names of
functions, classes, and methods to which to add tags.  For example, ::

   TestModule.test_function: a
   TestModule.TestClass: b
   TestModule.TestClass.test_method: c

would set attributes on a function, a class, and a method.  Then ::

   nosetests -a a

would run only the function, ::

   nosetests -a b

would run all methods on the class, and ::

   nosetests -a c

would run only the method.

Use cases
~~~~~~~~~

There are a couple of scenarios where this can come in handy:

 * You're working on a bunch of tests that are failing, and you only
   want to execute the failing tests.  If modifying the failing test
   code itself would be more work than simply listing them in a
   file, then use the decorator extension.

 * You have a 'private' set of unit tests that bear on the code you're
   working on.  You want to iterate quickly, just running those unit
   tests.  Again, if modifying the test code itself is more work than
   simply listing the relevant tests in a file, use the decorator extension.

 * You have a few unit tests that are failing, and you *don't* want to
   execute them (that is, the reverse of the first scenario).

Options
~~~~~~~

``--decorator-file`` specifies the file containing the tags to use.

Examples
~~~~~~~~

See ``examples/test_decorator.py`` for some examples; use
``examples/test_decorator.attrib`` as the decorator file. For example,
try the following commands::

   nosetests --decorator-file examples/test_decorator.attribs examples/test_decorator.py -a one
   nosetests --decorator-file examples/test_decorator.attribs examples/test_decorator.py -a two
   nosetests --decorator-file examples/test_decorator.attribs examples/test_decorator.py -a three

figleafsections -- find out what tests are executing which parts of your code
-----------------------------------------------------------------------------

(You'll need to install `figleaf <http://darcs.idyll.org/~t/projects/figleaf/doc/>`__ to use this plugin; it will install the ``figleaf`` package and the ``annotate-sections`` script.)

This plugin lets you record code coverage per unit test, and then
annotate your Python source code with which unit tests are running
which lines of code.  It's a useful way to figure out which nose tests
are exercising what parts of your program.

See http://ivory.idyll.org/blog/feb-07/figleaf-goodness.html for some
detailed examples.

To try it out, do this::

   nosetests -w examples/ --with-figleafsections examples/test_sections.py
   annotate-sections examples/test_sections.py

The output will be placed in the file ``examples/test_sections.py``.

outputsave -- save your stdout into files
-----------------------------------------

This plugin records the stdout from each test into a separate file,
with a prefix indicating whether or not the test succeeded.

Use cases
~~~~~~~~~

The main use case is when you have MANY failing tests and you want to
take a look at the output without having to page through the nose
error output linearly.

Options
~~~~~~~

``--with-outputsave`` enables the plugin.  Output from successful tests
will be placed in ``success-<testname>``, output from failed tests will
be placed in ``fail-<testname>``, and output from errors will be placed
in ``error-<testname>``.

``--omit-success`` does not save output from successful tests, i.e. only
'fail-' and 'error-' output files will be created.

``--save-directory`` places all saved output into the given directory,
creating it if it does not exist.

Examples
~~~~~~~~

Try::

   nosetests -w examples/ --with-outputsave --save-directory=output examples/test_outputsave.py

Then look at the 'output' directory.

spec -- generate test description from test class/method names
---------------------------------------------------------------

spec lets you generate a "specification" similar to testdox_ . The
ppec plugin can generate simple documentation directly from class and
method names of test cases. For example, a test case like::

  class TestFoobar:
      def test_is_a_singleton(self):
          pass
      def test_can_be_automatically_documented(self):
          pass

during the test run will generate the following specification: ::

  Foobar
  - is a singleton
  - can be automatically documented

Test functions put directly into a module will have a context based
on the name of the containing module. For example, if you define
functions test_are_marked_as_deprecated() and
test_doesnt_work_with_sets() in a module test_containers.py,
you'll get the following specs::

  Containers
  - are marked as deprecated
  - doesn't work with sets

Use cases
~~~~~~~~~

If you follow a good naming convention for your tests you'll get free
up-to-date specification of your application - it will be as accurate
as your tests are.

Options
~~~~~~~

``--with-spec`` enables the plugin, and automatically sets the verbose
level for nose to "detailed output".  During the test run all your
test descriptions will be shown as a special kind of specification -
your test classes set up a context and test methods set up a single
specification.

``--spec-color`` enables colored output. Successful tests will be marked
as green, while failed/error cases as red. Skipped and deprecated test
cases will be shown in yellow. You need an ANSI terminal to use this.

``--spec-doctests`` enables experimental support for doctests.

``--spec-file=SPEC_FILE`` outputs specification to a separate file instead
of the default nose stream. When this option is used nose reporter is not
replaced, so error details will still go to stderr.

Examples
~~~~~~~~

Try::

   nosetests --with-spec --spec-color examples/test_spec.py

(Yes, you should see an error.)

Look at examples/test_spec.py source code and tests inside
tests/spec_test_cases/ directory to see how test cases are
mapped into specifications.

License
=======

pinocchio is available under the MIT license.

Author Information
==================

The author of the stopwatch, decorator, figleafsections, and
outputsave extensions is Titus Brown.  You can contact him at
titus@idyll.org, or check out his main site at
http://ivory.idyll.org/.

The author of the spec plugin is Michal Kwiatkowski.  His homepage is
at http://joker.linuxstuff.pl/ and his mail address is
michal@trivas.pl.

.. _nose: https://nose.readthedocs.org/en/latest/
.. _testdox: http://agiledox.sourceforge.net/