Automatically rerun your tests on file modifications
pytest-watcher is a tool to automatically rerun tests (using pytest
by default) whenever your code changes.
Works on Unix (Linux, MacOS, BSD) and Windows.
Example:
pytest-watch has been around for a long time and used to address exactly this problem. Unfortunately, pytest-watch is no longer maintained and doesn't work for many users. This project provides an alternative for it.
See also: Differences with pytest-watch
By default pytest-watcher
looks for the following events:
*.py
file created*.py
file modified*.py
file deleted*.py
file moved either from or to the watched pathYou can specify alternative file patterns to watch. See Watching different patterns
pip install pytest-watcher
Specify the path that you want to watch:
ptw .
or
ptw /home/repos/project
pytest-watcher
will pass any arguments after <path>
to the test runner (which is pytest
by default). For example:
ptw . -x --lf --nf
will call pytest
with the following arguments:
pytest -x --lf --nf
You can specify an alternative test runner using the --runner
flag:
ptw . --runner tox
You can use the --patterns
flag to specify file patterns that you want to watch. It accepts a list of Unix-style patterns separated by a comma. The default value is "*.py"
Example:
ptw . --patterns '*.py,pyproject.toml'
You can also ignore certain patterns using the --ignore-patterns
flag:
ptw . --ignore-patterns 'settings.py,db.py'
pytest-watcher
uses a short delay (0.2 seconds by default) before triggering the actual test run. The main motivation for this is post-processors that can run after you save the file (for example, black
plugin in your IDE). This ensures that tests will run with the latest version of your code.
You can control the actual delay value with the --delay
flag:
ptw . --delay 0.2
To disable the delay altogether, you can set zero as a value:
ptw . --delay 0
Use the --clear
flag to clear the terminal screen before each test run
ptw . --clear
pytest-watch
Even though this project was inspired by pytest-watch
, it's not a fork of it. Therefore, there are differences in behavior:
pytest-watcher
needs you to specify a path to watch as a first argument:ptw .
pytest-watcher
doesn't start tests immediately by default. You can customize this behavior using --now
flag.You can configure pytest-watcher
via pyproject.toml
file. Here is the default configuration:
[tool.pytest-watcher]
now = false
clear = true
delay = 0.2
runner = "pytest"
runner_args = []
patterns = ["*.py"]
ignore_patterns = []
The code is compatible with Python versions 3.7+
This project is licensed under the MIT License.