Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mosquito/markdown-pytest
A simple module to test your documentation examples with pytest
https://github.com/mosquito/markdown-pytest
Last synced: 16 days ago
JSON representation
A simple module to test your documentation examples with pytest
- Host: GitHub
- URL: https://github.com/mosquito/markdown-pytest
- Owner: mosquito
- License: apache-2.0
- Created: 2022-12-26T14:34:35.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-07-03T09:38:52.000Z (4 months ago)
- Last Synced: 2024-10-13T09:14:34.336Z (30 days ago)
- Language: Python
- Size: 49.8 KB
- Stars: 10
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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:
````markdown
```python
assert True
```
````
Will be shown as
```python
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:
```markdown
```
Multiline example:
```markdown
```
This comment should be placed right before the block of code, exactly upper
the backticks, for example:
````
```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.
````markdown
```python
assert init_some_variable == 123
```
````
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 `` comment will not be executed.
* Allowed two or three dashes in the comment symbols
For example following line will be parsed identically:
````markdown
````
* 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:
````markdown
```python
assert True
```
````
Is the same of:
````markdown
```python
assert True
```
````
Code split
----------
You can split a test into multiple blocks with the same test name:
Markdown:
````markdown
This block performs import:
```python
from itertools import chain
```
`chain` usage example:
```python
assert list(chain(range(2), range(2))) == [0, 1, 0, 1]
```
````
Will be shown as
This block performs import:
```python
from itertools import chain
```
`chain` usage example:
```python
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.
````markdown
```python
from collections import Counter
```
```python
counter = Counter()
```
```python
counter["foo"] += 1
assert counter["foo"] == 1
```
````
Will be shown as
```python
from collections import Counter
```
```python
counter = Counter()
```
```python
counter["foo"] += 1
assert counter["foo"] == 1
```
Fictional Code Examples
-----------------------
Code without `` comment will not be executed.
````markdown
```python
from universe import antigravity, WrongPlanet
try:
antigravity()
except WrongPlanet:
print("You are on the wrong planet.")
exit(1)
```
````
Will be shown as
```python
from universe import antigravity, WrongPlanet
try:
antigravity()
except WrongPlanet:
print("You are on the wrong planet.")
exit(1)
```
Usage example
-------------
This README.md file can be tested like this:
```bash
$ pytest -v README.md
```
```bash
======================= 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%]
```