Welcome to pytest-watcher
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.
Table of contents
- File Events
- Using a different test runner
- Watching different patterns
- Differences with pytest-watch
Why not general tools
- Easy to use and remember
- Works for most python projects out of the box
- Uses native system monitoring API instead of polling on supported systems (see watchdog documentation)
- Listens for new file, delete file, change and move events
- Runs your tests with latest changes in case of post-processing events (see delay)
What about pytest-watch
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
pytest-watcher looks for the following events:
*.pyfile moved either from or to the watched path
You can specify alternative file patterns to watch. See Watching different patterns
pip install pytest-watcher
Specify the path that you want to watch:
pytest-watcher will pass any arguments after
<path> to the test runner (which is
pytest by default). For example:
ptw . -x --lf --nf
pytest with the following arguments:
pytest -x --lf --nf
Using a different test runner
You can specify an alternative test runner using the
ptw . --runner tox
Watching different patterns
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"
ptw . --patterns '*.py,pyproject.toml'
You can also ignore certain patterns using the
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
ptw . --delay 0.2
To disable the delay altogether, you can set zero as a value:
ptw . --delay 0
Even though this project was inspired by
pytest-watch, it's not a fork of it. Therefore, there are differences in behavior:
pytest-watchneeds you to specify a path to watch as a first argument:
pytest-watchdoesn't start tests immediately by default. You can customize this behavior using
You can configure
pyproject.toml file. Here is the default configuration:
[tool.pytest-watcher] now = false 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.