Quick-start reference

pytest-codeblock collects Python code blocks from .rst and .md files and runs them as pytest tests. No configuration is required for basic use — files are discovered automatically.

Naming rules

Only blocks whose name starts with test_ are collected by default. To test all blocks regardless of name, set test_nameless_codeblocks = true in pyproject.toml.

RST syntax

.. code-block:: python
   :name: test_my_example

   result = 1 + 1
   assert result == 2

Add a pytest marker (RST)

.. pytestmark: skip
.. code-block:: python
   :name: test_skipped_block

   pass

Request a fixture (RST)

.. pytestfixture: tmp_path
.. code-block:: python
   :name: test_uses_tmp_path

   d = tmp_path / "sub"
   d.mkdir()
   assert d.is_dir()

Group blocks (RST) — shared context

.. code-block:: python
   :name: test_part_one

   x = 1

Some prose in between.

.. continue: test_part_one
.. code-block:: python
   :name: test_part_two

   y = x + 1
   assert y == 2

All blocks sharing the same group key are concatenated into one test under the first name.

Incremental grouping — each step is its own test

When every continuation block has a distinct name, each step becomes a cumulative test:

.. code-block:: python
   :name: test_step_1

   a = 1

.. continue: test_step_1
.. code-block:: python
   :name: test_step_2

   b = a + 1
   assert b == 2

This produces two tests: test_step_1 (code: a=1) and test_step_2 (code: a=1\nb=a+1\nassert b==2).

Literal block (RST)

.. codeblock-name: test_literal_block

Example code::

   result = "hello"
   assert result == "hello"

Include external file (RST)

.. literalinclude:: examples/snippet.py
   :name: test_external_snippet

Run as standalone pytest suite (RST)

.. pytestmark: pytestrun
.. code-block:: python
   :name: test_pytest_style

   import pytest

   class TestMath:
       def test_add(self):
           assert 1 + 1 == 2

Markdown syntax

```python name=test_my_example
result = 1 + 1
assert result == 2
```

Add a pytest marker (Markdown)

<!-- pytestmark: skip -->
```python name=test_skipped
pass
```

Request a fixture (Markdown)

<!-- pytestfixture: tmp_path -->
```python name=test_uses_tmp_path
d = tmp_path / "sub"
d.mkdir()
assert d.is_dir()
```

Group blocks (Markdown)

```python name=test_setup
x = 1
```

<!-- continue: test_setup -->
```python name=test_continuation
y = x + 1
assert y == 2
```

Run as standalone pytest suite (Markdown)

<!-- pytestmark: pytestrun -->
```python name=test_class_example
import pytest

class TestMath:
    @pytest.fixture
    def value(self):
        return 42

    def test_value(self, value):
        assert value == 42
```

Async support

Top-level await is automatically wrapped — no extra config needed:

.. code-block:: python
   :name: test_async_block

   import asyncio
   result = await asyncio.sleep(0.1, result=99)
   assert result == 99

pyproject.toml configuration

[tool.pytest-codeblock]
# Test all blocks regardless of test_ prefix (default: false)
test_nameless_codeblocks = false

# Add custom language identifiers (in addition to python, py, python3)
rst_user_codeblocks = []
md_user_codeblocks = []

# Add custom file extensions
rst_user_extensions = []
md_user_extensions = []

testpaths troubleshooting

If docs are not discovered, add explicitly:

[tool.pytest.ini_options]
testpaths = ["src/app/tests", "docs"]

conftest.py hook integration

Use CODEBLOCK_MARK from pytest_codeblock.constants to identify doc-block tests:

from pytest_codeblock.constants import CODEBLOCK_MARK

def pytest_collection_modifyitems(config, items):
    for item in items:
        if item.get_closest_marker(CODEBLOCK_MARK):
            item.add_marker(pytest.mark.documentation)

Custom fixtures used in doc blocks are defined in conftest.py exactly like regular fixtures. Multiple pytestfixture directives on consecutive lines are all applied to the next block. Fixture requests in the first block of a group automatically apply to all continuation blocks.

View llms.txt version