Welcome to pytest-watcher

Overview

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:

Table of contents

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

Motivation

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)
• Has an interactive mode with handy keyboard shortcuts (Currently only available on POSIX systems)

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

File events

By default pytest-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. See Watching different patterns

Installation

pip install pytest-watcher

Usage

Specify the path that you want to watch:

ptw .

or

ptw /home/repos/project

pytest-watcher will pass any arguments (excepted reserved options) 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

Available options

The following options are reserved for pytest-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

Debug logging

Set PTW_DEBUG=1 to enable debug-level logging for troubleshooting:

PTW_DEBUG=1 ptw .

Using a different test runner

You can specify an alternative test runner using the --runner flag:

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"

Example:

ptw . --patterns '*.py,pyproject.toml'

You can also ignore certain patterns using the --ignore-patterns flag:

ptw . --ignore-patterns 'settings.py,db.py'

Delay

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

Screen clearing

Use the --clear flag to clear the terminal screen before each test run

ptw . --clear

Enable BEL notification

Use the --notify-on-failure flag to emit the BEL 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

Differences with 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.

Configuring

You can configure pytest-watcher via pyproject.toml file. Here is the default configuration:

[tool.pytest-watcher]
now = false
clear = true
notify_on_failure = false
delay = 0.2
runner = "pytest"
runner_args = []
patterns = ["*.py"]
ignore_patterns = []

Compatibility

The code is compatible with Python versions 3.9+

Contributing

Please, check CONTRIBUTING.md

License

This project is licensed under the MIT License.