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
<!-- name: test_assert_true -->
```python
assert True
```
````
<details>
<summary>Will be shown as</summary>
<!-- name: test_assert_true -->
```python
assert True
```
</details>
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
<!-- key1: value1; key2: value2 -->
```
Multiline example:
```markdown
<!--
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:
````markdown
<!-- 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:
````markdown
<!-- name: test_name -->
```python
assert True
```
````
Is the same of:
````markdown
<!-- name: test_name -->
```python
assert True
```
````
Code split
----------
You can split a test into multiple blocks with the same test name:
Markdown:
````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]
```
````
<details>
<summary>Will be shown as</summary>
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]
```
</details>
subtests support
----------------
Of course, you can break tests into subtests by simply adding `case: case_name`
to the markdown comment.
````markdown
<!-- 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
```
````
<details>
<summary>Will be shown as</summary>
<!-- 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
```
</details>
Fictional Code Examples
-----------------------
Code without `<!-- name: test_name -->` 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)
```
````
<details>
<summary>Will be shown as</summary>
```python
from universe import antigravity, WrongPlanet
try:
antigravity()
except WrongPlanet:
print("You are on the wrong planet.")
exit(1)
```
</details>
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%]
```
Raw data
{
"_id": null,
"home_page": "https://github.com/mosquito/markdown-pytest",
"name": "markdown-pytest",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "pytest, markdown, documentation",
"author": "Dmitry Orlov",
"author_email": "me@mosquito.su",
"download_url": "https://files.pythonhosted.org/packages/6a/d0/50654de126cd72648580dc1a1ef57a95d34b38eb7d2cbd49000caad7e2a8/markdown_pytest-0.3.1.tar.gz",
"platform": null,
"description": "markdown-pytest\n===============\n\nThe `markdown-pytest` plugin is a `pytest` plugin that allows you to run tests\ndirectly from Markdown files.\n\nWith this plugin, you can write your tests inside Markdown files, making it\neasy to read, understand and maintain your documentation samples.\nThe tests are executed just like any other Pytest tests.\n\nSample of markdown file content:\n\n````markdown\n<!-- name: test_assert_true -->\n```python\nassert True\n```\n````\n\n<details>\n<summary>Will be shown as</summary>\n\n<!-- name: test_assert_true -->\n```python\nassert True\n```\n\n</details>\n\nRestrictions\n------------\n\nSince there is no way to add attributes to a block of code in markdown, this \nmodule only runs those tests that are marked with a special comment.\n\nThe general format of this comment is as follows: parts separated by semicolons\nare a colon separated key-value pairs, the last semicolon is optional,\nand parts not containing a colon bill be ignored.\n\nExample:\n\n```markdown\n<!-- key1: value1; key2: value2 -->\n```\n\nMultiline example:\n\n```markdown\n<!-- \n key1: value1; \n key2: value2;\n-->\n```\n\nThis comment should be placed right before the block of code, exactly upper \nthe backticks, for example: \n\n````\n<!-- name: test_name -->\n```python\n```\n````\n\nThe `name` key is required, and blocks that do not contain it will be ignored.\n\nSome Markdown parsers support two or three dashes around comments, this module \nsupports both variants. The `case` parameter is optional and might be used for\nsubtests, see \"Code split\" section.\n\nCommon parsing rules\n--------------------\n\nThis module uses its own, very simple Markdown parser, which only supports code \nblock parsing. In general, the parsing behavior of a file follows the following \nrules:\n\n* Code without `<!-- name: test_name -->` comment will not be executed.\n* Allowed two or three dashes in the comment symbols\n\n For example following line will be parsed identically:\n\n ````markdown\n <!-- name: test_name -->\n <!--- name: test_name --->\n <!-- name: test_name --->\n <!--- name: test_name -->\n ````\n\n* Code blocks with same names will be merged in one code and executed once\n* The optional comment parameter `case` will execute the block as a subtest.\n* Indented code blocks will be shifted left.\n \n For example:\n\n ````markdown\n <!-- name: test_name -->\n ```python\n assert True\n ```\n ````\n\n Is the same of:\n\n ````markdown\n <!-- name: test_name -->\n ```python\n assert True\n ```\n ````\n\nCode split\n----------\n\nYou can split a test into multiple blocks with the same test name:\n\nMarkdown:\n\n````markdown\nThis block performs import:\n\n<!-- name: test_example -->\n```python\nfrom itertools import chain\n```\n\n`chain` usage example:\n\n<!-- name: test_example -->\n```python\nassert list(chain(range(2), range(2))) == [0, 1, 0, 1]\n```\n````\n\n<details>\n<summary>Will be shown as</summary>\n\nThis block performs import:\n\n<!-- name: test_example -->\n```python\nfrom itertools import chain\n```\n\n`chain` usage example:\n\n<!-- name: test_example -->\n```python\nassert list(chain(range(2), range(2))) == [0, 1, 0, 1]\n```\n\n</details>\n\nsubtests support\n----------------\n\nOf course, you can break tests into subtests by simply adding `case: case_name` \nto the markdown comment.\n\n````markdown\n<!-- name: test_counter -->\n```python\nfrom collections import Counter\n```\n\n<!-- \n name: test_counter;\n case: initialize_counter\n-->\n```python\ncounter = Counter()\n```\n\n<!-- \n name: test_counter;\n case: assign_counter_value\n-->\n```python\ncounter[\"foo\"] += 1\n\nassert counter[\"foo\"] == 1\n```\n````\n\n<details>\n<summary>Will be shown as</summary>\n\n<!-- name: test_counter -->\n```python\nfrom collections import Counter\n```\n\n<!-- \n name: test_counter;\n case: initialize_counter\n-->\n```python\ncounter = Counter()\n```\n\n<!-- \n name: test_counter;\n case: assign_counter_value\n-->\n```python\ncounter[\"foo\"] += 1\n\nassert counter[\"foo\"] == 1\n```\n\n</details>\n\nFictional Code Examples\n-----------------------\n\nCode without `<!-- name: test_name -->` comment will not be executed.\n\n````markdown\n```python\nfrom universe import antigravity, WrongPlanet\n\ntry:\n antigravity()\nexcept WrongPlanet:\n print(\"You are on the wrong planet.\")\n exit(1)\n```\n````\n\n<details>\n<summary>Will be shown as</summary>\n\n```python\nfrom universe import antigravity, WrongPlanet\n\ntry:\n antigravity()\nexcept WrongPlanet:\n print(\"You are on the wrong planet.\")\n exit(1)\n```\n</details>\n\nUsage example\n-------------\n\nThis README.md file can be tested like this:\n\n```bash\n$ pytest -v README.md\n```\n```bash\n======================= test session starts =======================\nplugins: subtests, markdown-pytest\ncollected 3 items\n\nREADME.md::test_assert_true PASSED [ 33%]\nREADME.md::test_example PASSED [ 66%]\nREADME.md::test_counter SUBPASS [100%]\nREADME.md::test_counter SUBPASS [100%]\nREADME.md::test_counter PASSED [100%]\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Pytest plugin for runs tests directly from Markdown files",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://github.com/mosquito/markdown-pytest/blob/master/README.rst",
"Homepage": "https://github.com/mosquito/markdown-pytest",
"Source": "https://github.com/mosquito/markdown-pytest",
"Tracker": "https://github.com/mosquito/markdown-pytest/issues"
},
"split_keywords": [
"pytest",
" markdown",
" documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dfba3ba329759752e2453cc7c8b0bf01205f4d3bf5debfba8dbfab422d959b77",
"md5": "46ef3ae14c36f52e97a9f2e18ba37d35",
"sha256": "4a7d23d9e9325a64bab344b505a9ec101ec6b23639b40e4ea098ddeacd2778c3"
},
"downloads": -1,
"filename": "markdown_pytest-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46ef3ae14c36f52e97a9f2e18ba37d35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 9255,
"upload_time": "2024-04-09T22:30:53",
"upload_time_iso_8601": "2024-04-09T22:30:53.723298Z",
"url": "https://files.pythonhosted.org/packages/df/ba/3ba329759752e2453cc7c8b0bf01205f4d3bf5debfba8dbfab422d959b77/markdown_pytest-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6ad050654de126cd72648580dc1a1ef57a95d34b38eb7d2cbd49000caad7e2a8",
"md5": "e08a9e1aeae93edc8fcfa1720a575890",
"sha256": "c3841666dcd7ada909c6b04d5929b7ffd9781ec7cfa59d084be5d3f9022d510f"
},
"downloads": -1,
"filename": "markdown_pytest-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "e08a9e1aeae93edc8fcfa1720a575890",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 8562,
"upload_time": "2024-04-09T22:30:55",
"upload_time_iso_8601": "2024-04-09T22:30:55.052913Z",
"url": "https://files.pythonhosted.org/packages/6a/d0/50654de126cd72648580dc1a1ef57a95d34b38eb7d2cbd49000caad7e2a8/markdown_pytest-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-09 22:30:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mosquito",
"github_project": "markdown-pytest",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "markdown-pytest"
}
JSON
