{"id":13772219,"url":"https://github.com/olzhasar/pytest-watcher","last_synced_at":"2025-10-21T20:04:00.219Z","repository":{"id":45217547,"uuid":"407304160","full_name":"olzhasar/pytest-watcher","owner":"olzhasar","description":"Automatically rerun your tests on file modifications","archived":false,"fork":false,"pushed_at":"2024-08-28T17:36:43.000Z","size":646,"stargazers_count":193,"open_issues_count":4,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-17T21:59:01.262Z","etag":null,"topics":["pytest","python","tdd","tdd-python","test-driven-development","testing","testing-tools","watch","watchdog","watcher"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olzhasar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-16T20:22:39.000Z","updated_at":"2025-04-15T17:32:40.000Z","dependencies_parsed_at":"2024-03-25T07:48:27.606Z","dependency_job_id":"30e31851-6b0b-4827-be7d-5944fd958f7f","html_url":"https://github.com/olzhasar/pytest-watcher","commit_stats":{"total_commits":159,"total_committers":8,"mean_commits":19.875,"dds":"0.13207547169811318","last_synced_commit":"cea020985fbd1c5615ba8fa82f6a6a4f850b481e"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olzhasar%2Fpytest-watcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olzhasar%2Fpytest-watcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olzhasar%2Fpytest-watcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olzhasar%2Fpytest-watcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olzhasar","download_url":"https://codeload.github.com/olzhasar/pytest-watcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253518941,"owners_count":21921074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pytest","python","tdd","tdd-python","test-driven-development","testing","testing-tools","watch","watchdog","watcher"],"created_at":"2024-08-03T17:01:01.447Z","updated_at":"2025-10-21T20:04:00.149Z","avatar_url":"https://github.com/olzhasar.png","language":"Python","funding_links":[],"categories":["Python","Plugins"],"sub_categories":[],"readme":"# Welcome to pytest-watcher\n\n[![PyPI](https://img.shields.io/pypi/v/pytest-watcher)](https://pypi.org/project/pytest-watcher/)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-watcher)](https://pypi.org/project/pytest-watcher/)\n[![GitHub](https://img.shields.io/github/license/olzhasar/pytest-watcher)](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![Preview](docs/_static/preview.gif)\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 `\u003cpath\u003e` 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folzhasar%2Fpytest-watcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folzhasar%2Fpytest-watcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folzhasar%2Fpytest-watcher/lists"}