Repository files navigation

pytest-watcher is a tool to automatically rerun tests (usingpytest by default) whenever your code changes.

Works on Unix (Linux, MacOS, BSD) and Windows.

Example:

• Motivation
• File Events
• Installation
• Usage
• Using a different test runner
• Watching different patterns
• Delay
• Differences with pytest-watch
• Configuring
• Compatibility
• License

• 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 (seewatchdog documentation)
• Listens for new file, delete file, change and move events
• Runs your tests with latest changes in case of post-processing events (seedelay)
• Has an interactive mode with handy keyboard shortcuts (Currently only available on POSIX systems)

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 defaultpytest-watcher looks for the following events:

• New*.py file created
• Existing*.py file modified
• Existing*.py file deleted
• A*.py file moved either from or to the watched path

You can specify alternative file patterns to watch. SeeWatching 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 (exceptedreserved options) after<path> to the test runner (which ispytest by default). For example:

ptw. -x --lf --nf

will callpytest with the following arguments:

pytest -x --lf --nf

The following options are reserved forpytest-watcher and will not be passed to the test runner:

• --runner - Specify an alternative test runner
• --patterns - Specify file patterns to watch
• --ignore-patterns - Specify file patterns to ignore
• --now - Run tests immediately after starting the watcher
• --delay - Specify the delay before running tests
• --clear - Clear the terminal screen before each test run
• --notify-on-failure - Send BEL notification on test run failure

SetPTW_DEBUG=1 to enable debug-level logging for troubleshooting:

PTW_DEBUG=1 ptw.

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 alsoignore 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

Use the--notify-on-failure flag to emit theBEL symbol to the terminal when the test run fails. This will trigger an audible or visual alert in some terminal applications.

ptw. --notify-on-failure

Even though this project was inspired bypytest-watch, it's not a fork of it. Therefore, there aredifferences 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 configurepytest-watcher viapyproject.toml file. Here is the default configuration:

[tool.pytest-watcher]now =falseclear =truenotify_on_failure =falsedelay =0.2runner ="pytest"runner_args = []patterns = ["*.py"]ignore_patterns = []

The code is compatible with Python versions 3.9+

Please, checkCONTRIBUTING.md

This project is licensed under theMIT License.