Skip to main content
Help us improve Python packaging – donate today!

Local continuous test runner with pytest and watchdog.

Project Description

pytest-watch -- Continuous pytest runner

[![Current version on PyPI](][pypi]
[![Downloads/month on PyPI](][pypi]

**pytest-watch** a zero-config CLI tool that runs [pytest][], and re-runs it
when a file in your project changes. It beeps on failures and can run arbitrary
commands on each passing and failing test run.


Whether or not you use the test-driven development method, running tests
continuously is far more productive than waiting until you're finished
programming to test your code. Additionally, manually running `py.test` each
time you want to see if any tests were broken has more wait-time and cognitive
overhead than merely listening for a notification. This could be a crucial
difference when debugging a complex problem or on a tight deadline.


$ pip install pytest-watch


$ cd myproject
$ ptw
* Watching /path/to/myproject

*Note: It can also be run using its full name ``.*

Now develop normally and check the terminal every now and then to see if any
tests are broken. Alternatively, pytest-watch can **notify you** when tests
pass or fail:

- **OSX**

`$ ptw --onpass "say passed" --onfail "say failed"`

$ ptw --onpass "growlnotify -m \"All tests passed!\"" \
--onfail "growlnotify -m \"Tests failed\""

using [GrowlNotify][].

- **Windows**

> ptw --onfail flash

using [Console Flash][]

You can also run a command before the tests run, e.g. seeding your test database:

$ ptw --beforerun

Or after they finish, e.g. deleting a sqlite file. Note that this script receives
the exit code of `py.test` as an argument.

$ ptw --afterrun

You can also use a custom runner script for full `py.test` control:

$ ptw --runner "python"

Here's an minimal runner script that runs `py.test` and prints its exit code:


import sys
import pytest

print('py.test exited with code:', pytest.main(sys.argv[1:]))

Need to exclude directories from being observed or collected for tests?

$ ptw --ignore ./deep-directory --ignore ./integration_tests

For more information and for the full list of options, run:

$ ptw --help


CLI options can be added to a `[pytest-watch]` section in your
[pytest.ini file][pytest.ini] to persist them in your project. For example:

# pytest.ini

addopts = --maxfail=2

ignore = ./integration-tests
nobeep = True


- [xdist][] offers the `--looponfail` (`-f`) option (and distributed testing
options). This instead re-runs only those tests which have failed until you
make them pass. This can be a speed advantage when trying to get all tests
passing, but leaves out the discovery of new failures until then. It also
drops the colors outputted by py.test, whereas pytest-watch doesn't.
- [Nosey][] is the original codebase this was forked from. Nosey runs [nose][]
instead of pytest.


1. Check the open issues or open a new issue to start a discussion around
your feature idea or the bug you found
2. Fork the repository, make your changes, and add yourself to [][]
3. Send a pull request

If your PR has been waiting a while, feel free to [ping me on Twitter][twitter].

Use this software often? Please consider [supporting pytest-watch][support].

<a href="" title="Thank you!" target="_blank">
<img src="" align="center" alt="Thank you!">

[console flash]:
[]: ./

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (20.9 kB) Copy SHA256 hash SHA256 Source None Apr 8, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page