| Name | flake8-test-docs JSON |
| Version |
1.0.8
JSON |
| download |
| home_page | |
| Summary | A linter that checks test docstrings for the arrange/act/assert structure |
| upload_time | 2023-01-04 07:54:36 |
| maintainer | |
| docs_url | None |
| author | David Andersson |
| requires_python | >=3.8.1,<4.0.0 |
| license | Apache 2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# flake8-test-docs
Have you ever needed to understand a new project and started reading the tests
only to find that you have no idea what the tests are doing? Good test
documentation is critical during test definition and when reviewing tests
written in the past or by someone else. This linter checks that the test
function docstring includes a description of the test setup, execution and
checks.
## Getting Started
```shell
python -m venv venv
source ./venv/bin/activate
pip install flake8 flake8-test-docs
flake8 test_source.py
```
On the following code:
```Python
# test_source.py
def test_foo():
value = foo()
assert value == "bar"
```
This will produce warnings such as:
```shell
flake8 test_source.py
test_source.py:2:1: TDO001 Docstring not defined on test function, more information: https://github.com/jdkandersson/flake8-test-docs#fix-tdo001
```
This can be resolved by changing the code to:
```Python
# test_source.py
def test_foo():
"""
arrange: given foo that returns bar
act: when foo is called
assert: then bar is returned
"""
value = foo()
assert value == "bar"
```
## Configuration
The plugin adds the following configurations to `flake8`:
* `--test-docs-patter`: The pattern the test documentation should follow,
e.g., `given/when/then`. Defaults to `arrange/act/assert`.
* `--test-docs-filename-pattern`: The filename pattern for test files. Defaults
to `test_.*\.py`.
* `--test-docs-function-pattern`: The function pattern for test functions.
Defaults to `test_.*`.
## Rules
A few rules have been defined to allow for selective suppression:
* `TDO001`: checks that test functions have a docstring.
* `TDO002`: checks that test function docstrings follow the documentation
pattern.
### Fix TDO001
This linting rule is triggered by a test function in a test file without a
docstring. For example:
```Python
# test_source.py
def test_foo():
result = foo()
assert result == "bar"
```
This example can be fixed by:
```Python
# test_source.py
def test_foo():
"""
arrange: given foo that returns bar
act: when foo is called
assert: then bar is returned
"""
result = foo()
assert result == "bar"
```
### Fix TDO002
This linting rule is triggered by a test function in a test file with a
docstring that doesn't follow the documentation pattern. For example:
```Python
# test_source.py
def test_foo():
"""Test foo."""
result = foo()
assert result == "bar"
```
This example can be fixed by:
```Python
# test_source.py
def test_foo():
"""
arrange: given foo that returns bar
act: when foo is called
assert: then bar is returned
"""
result = foo()
assert result == "bar"
```
The message of the linting rule should give you the specific problem with the
documentation. In general, the pattern is:
* start on the second line with the same indentation is the start of the
docstring
* the starting line should begin with `arrange:` (or whatever was set using
`--test-docs-patter`) followed by at least some words describing the test
setup
* long test setup descriptions can be broken over multiple lines by indenting
the lines after the first by one level (e.g., 4 spaces by default)
* this is followed by similar sections starting with `act:` describing the test
execution and `assert:` describing the checks
* the last line should be indented the same as the start of the docstring
Below are some valid examples. Starting with a vanilla example:
```Python
# test_source.py
def test_foo():
"""
arrange: given foo that returns bar
act: when foo is called
assert: then bar is returned
"""
result = foo()
assert result == "bar"
```
Here is an example where the test function is in a nested scope:
```Python
# test_source.py
class TestSuite:
def test_foo():
"""
arrange: given foo that returns bar
act: when foo is called
assert: then bar is returned
"""
result = foo()
assert result == "bar"
```
Here is an example where each of the descriptions go over multiple lines:
```Python
# test_source.py
def test_foo():
"""
arrange: given foo
that returns bar
act: when foo
is called
assert: then bar
is returned
"""
result = foo()
assert result == "bar"
```
Raw data
{
"_id": null,
"home_page": "",
"name": "flake8-test-docs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "",
"author": "David Andersson",
"author_email": "david@jdkandersson.com",
"download_url": "https://files.pythonhosted.org/packages/1a/cc/69bd58b17228835507aad88f8ebbd13bf3442ff7d6c5330e55aee9d847e1/flake8_test_docs-1.0.8.tar.gz",
"platform": null,
"description": "# flake8-test-docs\n\nHave you ever needed to understand a new project and started reading the tests\nonly to find that you have no idea what the tests are doing? Good test\ndocumentation is critical during test definition and when reviewing tests\nwritten in the past or by someone else. This linter checks that the test\nfunction docstring includes a description of the test setup, execution and\nchecks.\n\n## Getting Started\n\n```shell\npython -m venv venv\nsource ./venv/bin/activate\npip install flake8 flake8-test-docs\nflake8 test_source.py\n```\n\nOn the following code:\n\n```Python\n# test_source.py\ndef test_foo():\n value = foo()\n assert value == \"bar\"\n```\n\nThis will produce warnings such as:\n\n```shell\nflake8 test_source.py\ntest_source.py:2:1: TDO001 Docstring not defined on test function, more information: https://github.com/jdkandersson/flake8-test-docs#fix-tdo001\n```\n\nThis can be resolved by changing the code to:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"\n arrange: given foo that returns bar\n act: when foo is called\n assert: then bar is returned\n \"\"\"\n value = foo()\n assert value == \"bar\"\n```\n\n## Configuration\n\nThe plugin adds the following configurations to `flake8`:\n\n* `--test-docs-patter`: The pattern the test documentation should follow,\n e.g., `given/when/then`. Defaults to `arrange/act/assert`.\n* `--test-docs-filename-pattern`: The filename pattern for test files. Defaults\n to `test_.*\\.py`.\n* `--test-docs-function-pattern`: The function pattern for test functions.\n Defaults to `test_.*`.\n\n\n## Rules\n\nA few rules have been defined to allow for selective suppression:\n\n* `TDO001`: checks that test functions have a docstring.\n* `TDO002`: checks that test function docstrings follow the documentation\n pattern.\n\n### Fix TDO001\n\nThis linting rule is triggered by a test function in a test file without a\ndocstring. For example:\n\n```Python\n# test_source.py\ndef test_foo():\n result = foo()\n assert result == \"bar\"\n```\n\nThis example can be fixed by:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"\n arrange: given foo that returns bar\n act: when foo is called\n assert: then bar is returned\n \"\"\"\n result = foo()\n assert result == \"bar\"\n```\n\n### Fix TDO002\n\nThis linting rule is triggered by a test function in a test file with a\ndocstring that doesn't follow the documentation pattern. For example:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"Test foo.\"\"\"\n result = foo()\n assert result == \"bar\"\n```\n\nThis example can be fixed by:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"\n arrange: given foo that returns bar\n act: when foo is called\n assert: then bar is returned\n \"\"\"\n result = foo()\n assert result == \"bar\"\n```\n\nThe message of the linting rule should give you the specific problem with the\ndocumentation. In general, the pattern is:\n\n* start on the second line with the same indentation is the start of the\n docstring\n* the starting line should begin with `arrange:` (or whatever was set using\n `--test-docs-patter`) followed by at least some words describing the test\n setup\n* long test setup descriptions can be broken over multiple lines by indenting\n the lines after the first by one level (e.g., 4 spaces by default)\n* this is followed by similar sections starting with `act:` describing the test\n execution and `assert:` describing the checks\n* the last line should be indented the same as the start of the docstring\n\nBelow are some valid examples. Starting with a vanilla example:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"\n arrange: given foo that returns bar\n act: when foo is called\n assert: then bar is returned\n \"\"\"\n result = foo()\n assert result == \"bar\"\n```\n\nHere is an example where the test function is in a nested scope:\n\n```Python\n# test_source.py\nclass TestSuite:\n\n def test_foo():\n \"\"\"\n arrange: given foo that returns bar\n act: when foo is called\n assert: then bar is returned\n \"\"\"\n result = foo()\n assert result == \"bar\"\n```\n\nHere is an example where each of the descriptions go over multiple lines:\n\n```Python\n# test_source.py\ndef test_foo():\n \"\"\"\n arrange: given foo\n that returns bar\n act: when foo\n is called\n assert: then bar\n is returned\n \"\"\"\n result = foo()\n assert result == \"bar\"\n```\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A linter that checks test docstrings for the arrange/act/assert structure",
"version": "1.0.8",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "290a6b184345c259581a64169e894ed30a46dc05a7dd2f62e47118c61c26964e",
"md5": "dfc33292de84a4e244da3d4740a9e096",
"sha256": "09d1bcdb2472e272adb1130b0f5482973149690ca85ea68fca7f7af901d17f39"
},
"downloads": -1,
"filename": "flake8_test_docs-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfc33292de84a4e244da3d4740a9e096",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 11271,
"upload_time": "2023-01-04T07:54:35",
"upload_time_iso_8601": "2023-01-04T07:54:35.513592Z",
"url": "https://files.pythonhosted.org/packages/29/0a/6b184345c259581a64169e894ed30a46dc05a7dd2f62e47118c61c26964e/flake8_test_docs-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1acc69bd58b17228835507aad88f8ebbd13bf3442ff7d6c5330e55aee9d847e1",
"md5": "9c31a4d9dd0cca8dd932bcfc5cd4aa8a",
"sha256": "aea112f6dbf52518fd12d7e7959b809c504ebb379d1cde69f56d398900037bd3"
},
"downloads": -1,
"filename": "flake8_test_docs-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "9c31a4d9dd0cca8dd932bcfc5cd4aa8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 11427,
"upload_time": "2023-01-04T07:54:36",
"upload_time_iso_8601": "2023-01-04T07:54:36.771605Z",
"url": "https://files.pythonhosted.org/packages/1a/cc/69bd58b17228835507aad88f8ebbd13bf3442ff7d6c5330e55aee9d847e1/flake8_test_docs-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-04 07:54:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "flake8-test-docs"
}
