# pytest-spec2md
[](https://badge.fury.io/py/pytest-spec2md)
This project is an add-on to pytest. It generates a markdown files as specification, while running the tests.
This project is inspired by [pytest-spec](https://github.com/pchomik/pytest-spec) and [pytest-honors](https://github.com/aminohealth/pytest-honors) .
## Getting started
Install the module using pip.
```
pip install pytest-spec2md
```
Then you can activate the module using *--spec2md* Parameter when calling pytest.
You should set *--spec2md-version* to embed this value in the final document.
You find the generated markdown files under *docs* folder, if not changed in config.
## Configuration
You can change the target directory using the parameter *spec_target_file*.
```ini
[pytest]
test_spec_target_file = path/to/target/test/spec/file
spec_source_file = path/to/source/spec/file
spec_target_file = path/to/target/spec/with/test/file
```
## Using markers
The plugin provides the marker *func_reference*. This marker can be used to connect a test_case with the testing object.
The name of testing object will than be added to the documentation. If an optional documentation is provided, this will
also be displayed.
The marker can be used at every layer of testing object, so you can also use it at a class.
Furthermore, it provides the marker *spec_identifier*. This identifier can be used, to connect tests with the identifier
in the specification document.
Additionally, there is the marker *test_type*. This can be used to define the type of the test to be displayed in the
specification document. The default displayed is UnitTest. The module provides an enum with some default types to use,
own types can be used as well.
#### Example
```python
import pytest
from pytest_spec2md import TestType
def function_to_ref():
""" Simple doc comment
with two lines
"""
pass
@pytest.mark.func_reference(function_to_ref.__name__, function_to_ref.__doc__)
def test_use_a_reference_in_doc():
assert True
@pytest.mark.spec_identifier('Spec.FuntionA')
def test_uses_identifier_from_spec():
assert True
@pytest.mark.spec_identifier('Spec.FuntionA')
@pytest.mark.test_type(TestType.PERFORMANCE)
def test_this_is_a_performance_test():
assert True
```
This is how the identifier should be used on a specification file.
```markdown
# Specification File
Here you find more information for the requirement.
<!-- TestRef: Spec.FuntionA -->
```
As a result, a block is added at each position of the comment ``` <!-- TestRef: add_reference_here --> ```.
Therefore, the comment has to be a single line.
After this comment the information about the referenced tests are added.
## Examples
Examples for the usage can be found here:
[UseCases on GitHub](https://github.com/mh7d/pytest-spec2md/tree/main/pytester_cases)
Raw data
{
"_id": null,
"home_page": "https://dev.azure.com/h7d/Quality/",
"name": "pytest-spec2md",
"maintainer": "mh7d",
"docs_url": null,
"requires_python": "<4,>3.9",
"maintainer_email": null,
"keywords": "pytest, test, unittest, specification, markdown",
"author": "mh7d",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# pytest-spec2md\n\n[](https://badge.fury.io/py/pytest-spec2md)\n\nThis project is an add-on to pytest. It generates a markdown files as specification, while running the tests.\n\nThis project is inspired by [pytest-spec](https://github.com/pchomik/pytest-spec) and [pytest-honors](https://github.com/aminohealth/pytest-honors) .\n\n## Getting started\n\nInstall the module using pip.\n\n```\npip install pytest-spec2md\n```\n\nThen you can activate the module using *--spec2md* Parameter when calling pytest. \nYou should set *--spec2md-version* to embed this value in the final document.\n\nYou find the generated markdown files under *docs* folder, if not changed in config.\n\n## Configuration\n\nYou can change the target directory using the parameter *spec_target_file*.\n\n```ini\n[pytest]\ntest_spec_target_file = path/to/target/test/spec/file\nspec_source_file = path/to/source/spec/file\nspec_target_file = path/to/target/spec/with/test/file\n```\n\n## Using markers\n\nThe plugin provides the marker *func_reference*. This marker can be used to connect a test_case with the testing object.\nThe name of testing object will than be added to the documentation. If an optional documentation is provided, this will\nalso be displayed.\n\nThe marker can be used at every layer of testing object, so you can also use it at a class.\n\nFurthermore, it provides the marker *spec_identifier*. This identifier can be used, to connect tests with the identifier \nin the specification document.\n\nAdditionally, there is the marker *test_type*. This can be used to define the type of the test to be displayed in the \nspecification document. The default displayed is UnitTest. The module provides an enum with some default types to use, \nown types can be used as well.\n\n#### Example\n\n```python\nimport pytest\nfrom pytest_spec2md import TestType\n\n\ndef function_to_ref():\n \"\"\" Simple doc comment\n with two lines\n \"\"\"\n pass\n\n\n@pytest.mark.func_reference(function_to_ref.__name__, function_to_ref.__doc__)\ndef test_use_a_reference_in_doc():\n assert True\n\n \n@pytest.mark.spec_identifier('Spec.FuntionA')\ndef test_uses_identifier_from_spec():\n assert True\n\n\n@pytest.mark.spec_identifier('Spec.FuntionA')\n@pytest.mark.test_type(TestType.PERFORMANCE)\ndef test_this_is_a_performance_test():\n assert True\n```\n\nThis is how the identifier should be used on a specification file.\n\n```markdown\n# Specification File\n\nHere you find more information for the requirement.\n\n<!-- TestRef: Spec.FuntionA -->\n```\n\nAs a result, a block is added at each position of the comment ``` <!-- TestRef: add_reference_here --> ```. \nTherefore, the comment has to be a single line. \nAfter this comment the information about the referenced tests are added.\n\n## Examples\n\nExamples for the usage can be found here:\n[UseCases on GitHub](https://github.com/mh7d/pytest-spec2md/tree/main/pytester_cases)\n\n",
"bugtrack_url": null,
"license": "GPL-2.0-or-later",
"summary": "Library pytest-spec2md is a pytest plugin to create a markdown specification while running pytest.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://dev.azure.com/h7d/Quality/",
"Repository": "https://dev.azure.com/h7d/Quality/_git/pytest-spec2md"
},
"split_keywords": [
"pytest",
" test",
" unittest",
" specification",
" markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "334e9f9830712b08bb2048d5da7af602949a27adb03f6375f2fb210c9e220c29",
"md5": "e85183a947ba0e42927bb3cd6bac16fe",
"sha256": "f0321d14875a57cb404cd314c227a02009ea1758509daa2dc82a0fc714de729f"
},
"downloads": -1,
"filename": "pytest_spec2md-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e85183a947ba0e42927bb3cd6bac16fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>3.9",
"size": 21816,
"upload_time": "2024-04-10T14:29:01",
"upload_time_iso_8601": "2024-04-10T14:29:01.703009Z",
"url": "https://files.pythonhosted.org/packages/33/4e/9f9830712b08bb2048d5da7af602949a27adb03f6375f2fb210c9e220c29/pytest_spec2md-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 14:29:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pytest-spec2md"
}
JSON