pytest-doctestplus 0.1.2

Setup and Configuration

This plugin provides two command line options: --doctest-plus for enabling the advanced features mentioned above, and --doctest-rst for including *.rst files in doctest collection.

This plugin can also be enabled by default by adding doctest_plus = enabled to the [tool:pytest] section of the package’s setup.cfg file.

The plugin is applied to all directories and files that pytest collects. This means that configuring testpaths and norecursedirs in setup.cfg also affects the files that will be discovered by pytest-doctestplus. In addition, this plugin provides a doctest_norecursedirs configuration variable that indicates directories that should be ignored by pytest-doctestplus but do not need to be ignored by other pytest features.

Doctest Directives

The pytest-doctestplus plugin defines doctest directives that are used to control the behavior of particular features. For general information on directives and how they are used, consult the documentation. The specifics of the directives that this plugin defines are described in the sections below.

Floating Point Comparison

Some doctests may produce output that contains string representations of floating point values. Floating point representations are often not exact and contain roundoffs in their least significant digits. Depending on the platform the tests are being run on (different Python versions, different OS, etc.) the exact number of digits shown can differ. Because doctests work by comparing strings this can cause such tests to fail.

To address this issue, the pytest-doctestplus plugin provides support for a FLOAT_CMP flag that can be used with doctests. For example:

>>> 1.0 / 3.0  # doctest: +FLOAT_CMP
0.333333333333333311

When this flag is used, the expected and actual outputs are both parsed to find any floating point values in the strings. Those are then converted to actual Python float objects and compared numerically. This means that small differences in representation of roundoff digits will be ignored by the doctest. The values are otherwise compared exactly, so more significant (albeit possibly small) differences will still be caught by these tests.

Skipping Tests

Doctest provides the +SKIP directive for skipping statements that should not be executed when testing documentation. However, it is often useful to be able to skip docstrings associated with particular functions, methods, classes, or even entire files.

__doctest_skip__ = ['myfunction', 'MyClass', 'MyClass.*']

__doctest_skip__  = ['.', 'myfunction', 'MyClass']

__doctest_skip__ = ['*']

__doctest_requires__ = {('func1', 'func2'): ['scipy']}

Remote Data

The pytest-doctestplus plugin can be used in conjunction with the pytest-remotedata plugin in order to control doctest code that requires access to data from the internet. In order to make use of these features, the pytest-remotedata plugin must be installed, and remote data access must be enabled using the --remote-data command line option to pytest. See the pytest-remotedata plugin documentation for more details.

The following example illustrates how a doctest that uses remote data should be marked:

.. code-block:: python

    >>> from urlib.request import urlopen
    >>> url = urlopen('http://astropy.org') # doctest: +REMOTE_DATA

The +REMOTE_DATA directive indicates that the marked statement should only be executed if the --remote-data option is given. By default, all statements marked with --remote-data will be skipped.