doctest.rst

Overview

The `doctest.rst` file serves as a comprehensive guide and reference documentation for using doctests within the pytest testing framework. It details how to run doctests in both text files and Python docstrings, customize their behavior, and leverage pytest-specific extensions to enhance testing flexibility and integration.

This file is primarily targeted at developers and testers who want to utilize the Python standard `doctest` module capabilities within pytest's ecosystem, including how to configure, run, and extend doctests efficiently. It also highlights pytest’s additional features that improve compatibility, output formatting, and fixture usage in doctests.

Detailed Sections and Usage

Running Doctests

• Default behavior: pytest automatically collects and runs doctests located in text files matching the pattern test*.txt.

• Custom pattern: Change the pattern using --doctest-glob CLI option, e.g., pytest --doctest-glob="*.rst".

• Example test file (test_example.txt):

  >>> x = 3
  >>> x
  3
  

• Running tests:

  $ pytest
  

• Doctests in Python modules: Enable with --doctest-modules to run doctests embedded in function/class docstrings.

Encoding

• Default encoding is UTF-8.

• Can be changed globally via pytest.ini:

  [pytest]
  doctest_encoding = latin1
  

Using doctest Option Flags

• Python doctest module supports flags to control test strictness.

• Enable options in pytest.ini under doctest_optionflags, e.g.,

  [pytest]
  doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL
  

• Inline directive example:

  >>> something_that_raises()  # doctest: +IGNORE_EXCEPTION_DETAIL
  Traceback (most recent call last):
  ValueError: ...
  

• pytest-added flags:

  • ALLOW_UNICODE: strips unicode prefix u for compatibility across Python versions.

  • ALLOW_BYTES: strips bytes prefix b.

  • NUMBER: allows approximate floating-point comparison using pytest.approx with precision inferred from doctest output.

Continue on Failure

• By default, pytest stops at the first doctest failure.

• Use --doctest-continue-on-failure to run all tests regardless of failures.

Output Format

• Customize diff output for failures with --doctest-report option:

  • none, udiff, cdiff, ndiff, only_first_failure

Pytest-Specific Features

Using Fixtures in Doctests

• Fixtures can be accessed in doctests using the getfixture helper:

  >>> tmp = getfixture('tmp_path')
  

• Fixtures must be discoverable by pytest (e.g., defined in conftest.py).

doctest_namespace Fixture

• Inject variables or modules into the doctest namespace via this fixture.

• Example in conftest.py:

  import pytest
  import numpy
  
  @pytest.fixture(autouse=True)
  def add_np(doctest_namespace):
      doctest_namespace["np"] = numpy
  

• Use injected items directly in doctests:

  >>> a = np.arange(10)
  >>> len(a)
  10
  

Skipping Tests

• Skip individual doctest checks with # doctest: +SKIP directive.

• Use pytest.skip() or pytest.xfail() inside doctests for conditional skipping or marking expected failures, though usage is discouraged for readability reasons.

• Note behavioral differences when skipping in Python docstrings vs. text files.

Alternatives to Built-in Doctest Support

• For enhanced doctest capabilities and reStructuredText testing, consider external packages:

  • pytest-doctestplus: advanced doctest support with .rst file testing.

  • Sybil: parses and tests examples from documentation source files.

Implementation Details and Algorithms

This file is a reStructuredText (RST) documentation file, so it contains no executable code or algorithms. Instead, it acts as a detailed instructional manual that explains how pytest integrates and extends Python’s standard doctest module functionalities. It covers:

• How pytest collects and runs doctests from various sources.

• Configuration options and idiomatic usage patterns.

• Mechanisms to inject fixtures and namespaces into doctest execution context.

• Pytest-specific enhancements for output formatting and comparison flexibility.

The documentation leverages formatted code blocks, inline directives, and hyperlinks to Python and pytest documentation to facilitate learning and practical application.

Interactions with Other System Components

• pytest core: This documentation explains how doctests are integrated into the pytest testing lifecycle and command-line interface.

• Python doctest module: Describes how pytest wraps and extends doctest functionality.

• pytest fixtures system: Shows how fixtures interact with doctests to provide test context and dependencies.

• pytest.ini configuration: Guides users to configure doctest behavior globally.

• External doctest-related plugins: References third-party packages that build on top of this functionality.

Mermaid Diagram: File Structure and Content Flow

flowchart TD
    A[doctest.rst Documentation] --> B[Running Doctests]
    A --> C[Encoding Configuration]
    A --> D[Doctest Option Flags]
    A --> E[Continue on Failure]
    A --> F[Output Format Options]
    A --> G[Pytest-Specific Features]
    G --> G1[Using Fixtures in Doctests]
    G --> G2[doctest_namespace Fixture]
    G --> G3[Skipping Tests]
    A --> H[Alternatives and Extensions]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#ccf,stroke:#333,stroke-width:1px

Summary

The `doctest.rst` file is a user-centric guide that documents how to effectively use doctests within pytest, including running tests from text files and Python docstrings, configuring encoding and options, leveraging pytest’s unique extensions such as fixtures and namespace injection, and customizing output and failure handling. It also points users toward alternative tools for advanced doctest needs, making it an essential resource for developers aiming to maintain robust, readable, and flexible doctest suites.