A simple module to test your documentation examples with pytest
APACHE-2.0 License
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
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.
Additionally, a code block can be put inside the comment block to hide some initialization from the readers.
<!-- name: test_name
```python
init_some_variable = 123
```
-->
```python
assert init_some_variable == 123
```
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
```
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]
```
This block performs import:
from itertools import chain
chain
usage example:
assert list(chain(range(2), range(2))) == [0, 1, 0, 1]
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
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)
This README.md file can 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%]