markdown-pytest

The markdown-pytest plugin is a pytest plugin that allows you to run tests directly from Markdown files.

With this plugin, you can write your tests inside Markdown files, making it easy to read, understand and maintain your documentation samples. The tests are executed just like any other Pytest tests.

Sample of markdown file content:

<!-- name: test_assert_true -->
```python
assert True
```

assert True

Restrictions

Since there is no way to add attributes to a block of code in markdown, this module only runs those tests that are marked with a special comment.

The general format of this comment is as follows: parts separated by semicolons are a colon separated key-value pairs, the last semicolon is optional, and parts not containing a colon bill be ignored.

Example:

<!-- key1: value1; key2: value2 -->

Multiline example:

<!-- 
    key1: value1; 
    key2: value2;
-->

This comment should be placed right before the block of code, exactly upper the backticks, for example:

<!-- name: test_name -->
```python
```

The name key is required, and blocks that do not contain it will be ignored.

Some Markdown parsers support two or three dashes around comments, this module supports both variants. The case parameter is optional and might be used for subtests, see "Code split" section.

Common parsing rules

This module uses its own, very simple Markdown parser, which only supports code block parsing. In general, the parsing behavior of a file follows the following rules:

• Code without <!-- name: test_name --> comment will not be executed.

• Allowed two or three dashes in the comment symbols

  For example following line will be parsed identically:

  <!--  name: test_name -->
  <!--- name: test_name --->
  <!--  name: test_name --->
  <!--- name: test_name -->
  

• Code blocks with same names will be merged in one code and executed once

• The optional comment parameter case will execute the block as a subtest.

• Indented code blocks will be shifted left.

  For example:

      <!-- name: test_name -->
      ```python
      assert True
      ```
  

  Is the same of:

  <!-- name: test_name -->
  ```python
  assert True
  ```
  

Code split

You can split a test into multiple blocks with the same test name:

Markdown:

This block performs import:

<!-- name: test_example -->
```python
from itertools import chain
```

`chain` usage example:

<!-- name: test_example -->
```python
assert list(chain(range(2), range(2))) == [0, 1, 0, 1]
```

from itertools import chain

assert list(chain(range(2), range(2))) == [0, 1, 0, 1]

subtests support

Of course, you can break tests into subtests by simply adding case: case_name to the markdown comment.

<!-- name: test_counter -->
```python
from collections import Counter
```

<!-- 
    name: test_counter;
    case: initialize_counter
-->
```python
counter = Counter()
```

<!-- 
    name: test_counter;
    case: assign_counter_value
-->
```python
counter["foo"] += 1

assert counter["foo"] == 1
```

from collections import Counter

counter = Counter()

counter["foo"] += 1

assert counter["foo"] == 1

Fictional Code Examples

Code without <!-- name: test_name --> comment will not be executed.

```python
from universe import antigravity, WrongPlanet

try:
    antigravity()
except WrongPlanet:
    print("You are on the wrong planet.")
    exit(1)
```

from universe import antigravity, WrongPlanet

try:
    antigravity()
except WrongPlanet:
    print("You are on the wrong planet.")
    exit(1)

Usage example

This README.md file might be tested like this:

$ pytest -v README.md
======================= test session starts =======================
plugins: subtests, markdown-pytest
collected 3 items

README.md::test_assert_true PASSED                           [ 33%]
README.md::test_example PASSED                               [ 66%]
README.md::test_counter SUBPASS                              [100%]
README.md::test_counter SUBPASS                              [100%]
README.md::test_counter PASSED                               [100%]