# Welcome to pytest-watcher
[](https://pypi.org/project/pytest-watcher/)
[](https://pypi.org/project/pytest-watcher/)
[](https://github.com/olzhasar/pytest-watcher/blob/master/LICENSE)
## 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](#motivation)
- [File Events](#file-events)
- [Installation](#installation)
- [Usage](#usage)
- [Using a different test runner](#using-a-different-test-runner)
- [Watching different patterns](#watching-different-patterns)
- [Delay](#delay)
- [Differences with pytest-watch](#differences-with-pytest-watch)
- [Configuring](#configuring)
- [Compatibility](#compatibility)
- [License](#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](https://python-watchdog.readthedocs.io/en/stable/installation.html#supported-platforms-and-caveats))
- Listens for new file, delete file, change and move events
- Runs your tests with latest changes in case of post-processing events (see [delay](#delay))
- Has an interactive mode with handy keyboard shortcuts (Currently only available on POSIX systems)
### What about pytest-watch
[pytest-watch](https://github.com/joeyespo/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](#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](#watching-different-patterns)
## Installation
```sh
pip install pytest-watcher
```
## Usage
Specify the path that you want to watch:
```sh
ptw .
```
or
```sh
ptw /home/repos/project
```
`pytest-watcher` will pass any arguments (excepted [reserved options](#available-options)) after `<path>` to the test runner (which is `pytest` by default). For example:
```sh
ptw . -x --lf --nf
```
will call `pytest` with the following arguments:
```sh
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
### Using a different test runner
You can specify an alternative test runner using the `--runner` flag:
```sh
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:
```sh
ptw . --patterns '*.py,pyproject.toml'
```
You can also **ignore** certain patterns using the `--ignore-patterns` flag:
```sh
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:
```sh
ptw . --delay 0.2
```
To disable the delay altogether, you can set zero as a value:
```sh
ptw . --delay 0
```
### Screen clearing
Use the `--clear` flag to clear the terminal screen before each test run
```sh
ptw . --clear
```
### Differences with `pytest-watch`
Even though this project was inspired by [`pytest-watch`](https://github.com/joeyespo/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:
```sh
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:
```toml
[tool.pytest-watcher]
now = false
clear = true
delay = 0.2
runner = "pytest"
runner_args = []
patterns = ["*.py"]
ignore_patterns = []
```
## Compatibility
The code is compatible with Python versions 3.7+
## License
This project is licensed under the [MIT License](LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/olzhasar/pytest-watcher",
"name": "pytest-watcher",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.7.0",
"maintainer_email": null,
"keywords": "pytest, watch, watcher",
"author": "Olzhas Arystanov",
"author_email": "o.arystanov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/72/72/a2a1e81f1b272ddd9a1848af4959c87c39aa95c0bbfb3007cacb86c47fa9/pytest_watcher-0.4.3.tar.gz",
"platform": null,
"description": "# Welcome to pytest-watcher\n\n[](https://pypi.org/project/pytest-watcher/)\n[](https://pypi.org/project/pytest-watcher/)\n[](https://github.com/olzhasar/pytest-watcher/blob/master/LICENSE)\n\n## Overview\n\n**pytest-watcher** is a tool to automatically rerun tests (using `pytest` by default) whenever your code changes.\n\nWorks on Unix (Linux, MacOS, BSD) and Windows.\n\nExample:\n\n\n\n## Table of contents\n\n- [Motivation](#motivation)\n- [File Events](#file-events)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Using a different test runner](#using-a-different-test-runner)\n- [Watching different patterns](#watching-different-patterns)\n- [Delay](#delay)\n- [Differences with pytest-watch](#differences-with-pytest-watch)\n- [Configuring](#configuring)\n- [Compatibility](#compatibility)\n- [License](#license)\n\n## Motivation\n\n### Why not general tools\n\n- Easy to use and remember\n- Works for most Python projects out of the box\n- Uses native system monitoring API instead of polling on supported systems (see [watchdog documentation](https://python-watchdog.readthedocs.io/en/stable/installation.html#supported-platforms-and-caveats))\n- Listens for new file, delete file, change and move events\n- Runs your tests with latest changes in case of post-processing events (see [delay](#delay))\n- Has an interactive mode with handy keyboard shortcuts (Currently only available on POSIX systems)\n\n### What about pytest-watch\n\n[pytest-watch](https://github.com/joeyespo/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.\n\nSee also: [Differences with pytest-watch](#differences-with-pytest-watch)\n\n## File events\n\nBy default `pytest-watcher` looks for the following events:\n\n- New `*.py` file created\n- Existing `*.py` file modified\n- Existing `*.py` file deleted\n- A `*.py` file moved either from or to the watched path\n\nYou can specify alternative file patterns to watch. See [Watching different patterns](#watching-different-patterns)\n\n## Installation\n\n```sh\npip install pytest-watcher\n```\n\n## Usage\n\nSpecify the path that you want to watch:\n\n```sh\nptw .\n```\n\nor\n\n```sh\nptw /home/repos/project\n```\n\n`pytest-watcher` will pass any arguments (excepted [reserved options](#available-options)) after `<path>` to the test runner (which is `pytest` by default). For example:\n\n```sh\nptw . -x --lf --nf\n```\n\nwill call `pytest` with the following arguments:\n\n```sh\npytest -x --lf --nf\n```\n\n### Available options\n\nThe following options are reserved for `pytest-watcher` and will not be passed to the test runner:\n\n- `--runner` - Specify an alternative test runner\n- `--patterns` - Specify file patterns to watch\n- `--ignore-patterns` - Specify file patterns to ignore\n- `--now` - Run tests immediately after starting the watcher\n- `--delay` - Specify the delay before running tests\n- `--clear` - Clear the terminal screen before each test run\n\n### Using a different test runner\n\nYou can specify an alternative test runner using the `--runner` flag:\n\n```sh\nptw . --runner tox\n```\n\n### Watching different patterns\n\nYou 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\"\n\nExample:\n\n```sh\nptw . --patterns '*.py,pyproject.toml'\n```\n\nYou can also **ignore** certain patterns using the `--ignore-patterns` flag:\n\n```sh\nptw . --ignore-patterns 'settings.py,db.py'\n```\n\n### Delay\n\n`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.\n\nYou can control the actual delay value with the `--delay` flag:\n\n```sh\nptw . --delay 0.2\n```\n\nTo disable the delay altogether, you can set zero as a value:\n\n```sh\nptw . --delay 0\n```\n\n### Screen clearing\n\nUse the `--clear` flag to clear the terminal screen before each test run\n\n```sh\nptw . --clear\n```\n\n### Differences with `pytest-watch`\n\nEven though this project was inspired by [`pytest-watch`](https://github.com/joeyespo/pytest-watch), it's not a fork of it. Therefore, there are **differences** in behavior:\n\n- `pytest-watcher` needs you to specify a path to watch as a first argument:\n\n```sh\nptw .\n```\n\n- `pytest-watcher` doesn't start tests immediately by default. You can customize this behavior using `--now` flag.\n\n## Configuring\n\nYou can configure `pytest-watcher` via `pyproject.toml` file. Here is the default configuration:\n\n```toml\n[tool.pytest-watcher]\nnow = false\nclear = true\ndelay = 0.2\nrunner = \"pytest\"\nrunner_args = []\npatterns = [\"*.py\"]\nignore_patterns = []\n```\n\n## Compatibility\n\nThe code is compatible with Python versions 3.7+\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically rerun your tests on file modifications",
"version": "0.4.3",
"project_urls": {
"Documentation": "https://pytest-watcher.readthedocs.io/en/latest/",
"Homepage": "https://github.com/olzhasar/pytest-watcher",
"Repository": "https://github.com/olzhasar/pytest-watcher"
},
"split_keywords": [
"pytest",
" watch",
" watcher"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5b3ac44a76c6bb5e9e896d9707fb1c704a31a0136950dec9514373ced0684d56",
"md5": "fa72e3436ec1c5fc4e21301b9bda31b1",
"sha256": "d59b1e1396f33a65ea4949b713d6884637755d641646960056a90b267c3460f9"
},
"downloads": -1,
"filename": "pytest_watcher-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa72e3436ec1c5fc4e21301b9bda31b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.7.0",
"size": 11852,
"upload_time": "2024-08-28T17:37:45",
"upload_time_iso_8601": "2024-08-28T17:37:45.731697Z",
"url": "https://files.pythonhosted.org/packages/5b/3a/c44a76c6bb5e9e896d9707fb1c704a31a0136950dec9514373ced0684d56/pytest_watcher-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7272a2a1e81f1b272ddd9a1848af4959c87c39aa95c0bbfb3007cacb86c47fa9",
"md5": "2185e3a2b4bf9768270e6b4f5c1d037b",
"sha256": "0cb0e4661648c8c0ff2b2d25efa5a8e421784b9e4c60fcecbf9b7c30b2d731b3"
},
"downloads": -1,
"filename": "pytest_watcher-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "2185e3a2b4bf9768270e6b4f5c1d037b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.7.0",
"size": 10386,
"upload_time": "2024-08-28T17:37:46",
"upload_time_iso_8601": "2024-08-28T17:37:46.662325Z",
"url": "https://files.pythonhosted.org/packages/72/72/a2a1e81f1b272ddd9a1848af4959c87c39aa95c0bbfb3007cacb86c47fa9/pytest_watcher-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-28 17:37:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "olzhasar",
"github_project": "pytest-watcher",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pytest-watcher"
}
JSON
