1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
==================
pytest-flake8-path
==================
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/pytest-flake8-path/main.yml.svg?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/pytest-flake8-path/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/pytest-flake8-path.svg?style=for-the-badge
:target: https://pypi.org/project/pytest-flake8-path/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
A pytest fixture for testing flake8 plugins.
A quick example:
.. code-block:: python
def test_simple_run(flake8_path):
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator"
]
----
**Working on a Django project?**
Check out my book `Speed Up Your Django Tests <https://adamchainz.gumroad.com/l/suydt>`__ which covers loads of ways to write faster, more accurate tests.
----
Installation
============
Use **pip**:
.. code-block:: sh
python -m pip install pytest-flake8-path
Python 3.9 to 3.13 supported.
API
===
``flake8_path`` fixture
-----------------------
A pytest fixture that wraps Pytest's built-in ``tmp_path`` fixture
(`docs <https://docs.pytest.org/en/latest/how-to/tmp_path.html>`__), to create
a temporary directory, allow adding files, and running flake8. It acts like a
`pathlib.Path <https://docs.python.org/3/library/pathlib.html#pathlib.Path>`__
object, with one extra method.
If you're using this to test a flake8 plugin, make sure flake8 is picking up
your plugin during tests. Normally this is done with a ``setup.cfg``
entrypoint, which makes ``tox`` the easiest way to guarantee this is ready as
it will install your project before running tests.
``flake8dir.run_flake8(extra_args: list[str] | None = None) -> Flake8Result``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Runs flake8 and returns a ``Flake8Result`` representing the results.
``extra_args`` may be a list of extra flags to pass to flake8, for example
passing ``["--ignore", "E101"]``. Note some arguments are already passed to
ensure Flake8 runs in an isolated manner - see source.
``Flake8Result``
----------------
Represents the parsed output of a flake8 run.
``Flake8Result.out: str``
~~~~~~~~~~~~~~~~~~~~~~~~~
The full string of output (stdout) generated by flake8.
``Flake8Result.err: str``
~~~~~~~~~~~~~~~~~~~~~~~~~
The full string of error output (stderr) generated by flake8.
``Flake8Result.exit_code: int``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The exit code that the flake8 run exited with.
``Flake8Result.out_lines: list[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A list of individual lines of output, without trailing newlines.
This is the most useful tool for making assertions against.
On Windows, file paths are normalized into the Unix format (``\`` is replaced
with ``/``). This allows test suites to run the same on all operating systems.
For example, given a result you can check for a particular line being output:
.. code-block:: python
result = flake8_path.run_flake8()
expected = "./example.py:1:2: E221 multiple spaces before operator"
assert expected in result.out_lines
``Flake8Result.err_lines: list[str]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Like ``out_lines``, but for error output.
Examples
========
Basic
-----
Using ``Path.write_text()`` (`docs <https://docs.python.org/3/library/pathlib.html#pathlib.Path.write_text>`__) we can create an ``example.py`` file with code.
Then with ``flake8_path.run_flake8()`` we can run flake8 and check for an expected error:
.. code-block:: python
def test_simple(flake8_path):
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator"
]
assert result.err_lines == []
assert result.exit_code == 1
With dedent
-----------
The standard library’s ``textwrap.dedent()`` (`docs <https://docs.python.org/3/library/textwrap.html#textwrap.dedent>`__) is useful for including multi-line files.
Use a triple quoted multi-line string, with an initial backslash to prevent a blank first line:
.. code-block:: python
def test_multi_line(flake8_path):
(flake8_path / "example.py").write_text(
dedent(
"""\
x = 1
y = 2
"""
)
)
result = flake8_path.run_flake8()
assert result.out_lines == [
"./example.py:1:2: E221 multiple spaces before operator",
"./example.py:2:2: E221 multiple spaces before operator",
]
assert result.err_lines == []
assert result.exit_code == 1
Configuring flake8
------------------
Write a ``setup.cfg`` file to configure flake8 before running it:
.. code-block:: python
def test_with_setup_cfg(flake8_path):
(flake8_path / "setup.cfg").write_text(
dedent(
"""\
[flake8]
ignore = E221
"""
)
)
(flake8_path / "example.py").write_text("x = 1\n")
result = flake8_path.run_flake8()
assert result.out_lines == []
assert result.err_lines == []
assert result.exit_code == 0
History
=======
pytest-flake8-path is the successor to `pytest-flake8dir <https://pypi.org/project/pytest-flake8dir/>`__.
pytest-flake8dir was based upon pytest’s ``tmpdir`` fixture, which returned a legacy ``py.path.local`` object.
Since version 3.9.0, pytest has provided the ``tmp_path`` fixture, which returns a standard library ``pathlib.Path`` object.
pytest-flake8-path is a rewrite of pytest-flake8dir to use ``tmp_path`` instead of ``tmpdir``.
|
