🧪 shtest

shtest tests shell commands in your Sphinx documentation.

The shtest directive supports the usual doctest syntax. The following example renders as shown below during a normal documentation build and runs the test when executed using the shtest builder (see Installation and Usage for details).

.. shtest::

    # Obligatory hello world example.
    $ echo hello world
    hello world

# Obligatory hello world example. $ echo hello world hello world

The directive offers the following options:

• :returncode: [integer] specifies the expected return code (defaults to 0).
• adding the :stderr: flag compares results with the stderr rather than stdout stream.
• :cwd: [relative path] specifies the working directory relative to the source of the document (defaults to the directory containing the source document).
• :tempdir: executes the test in a temporary directory.

Installation and Usage

1. Run pip install sphinxcontrib-shtest to install the package.
2. Add "sphinxcontrib.shtest" to your extensions list in conf.py to enable the extension (see here for details).
3. Execute sphinx-build -b shtest /path/to/source/directory /path/to/output/directory. The -b shtest flag executes the shell tests; run without the -b shtest flag to build your documentation as usual.

Examples

.. shtest::
    :stderr:

    # Read from stderr instead of stdout.
    $ echo message on stderr >&2
    message on stderr

# Read from stderr instead of stdout. $ echo message on stderr >&2 message on stderr

.. shtest::
    :returncode: 1

    # Use a non-zero expected return code.
    $ false

# Use a non-zero expected return code. $ false

.. shtest::

    # Run multiple tests in one directive.
    $ echo hello
    hello
    $ echo world
    world

# Run multiple tests in one directive. $ echo hello hello $ echo world world

.. shtest::
    :cwd: tests

    # Run a test in a particular working directory relative to the document.
    $ cat hello.txt
    world

# Run a test in a particular working directory relative to the document. $ cat hello.txt world

.. shtest::
    :tempdir:

    # Run a test in a temporary directory.
    $ echo hello > world.txt

# Run a test in a temporary directory. $ echo hello > world.txt

.. sh:: ls -l

ls -l