# How to Run Tests Using uv

If your project lists [pytest](https://pydevtools.com/handbook/reference/pytest.md) as a dev dependency, run every test with a single command:

```bash
uv run pytest
```

`uv run` syncs the [virtual environment](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md) automatically, so the project and its dependencies are always installed before pytest starts.

If pytest is not in the project's dependencies and you don't want to add it, inject it at runtime:

```bash
uv run --with pytest pytest
```

## Run a Subset of Tests

Target a single file, a single function, or a keyword pattern:

```bash
uv run pytest tests/test_api.py
uv run pytest tests/test_api.py::test_login
uv run pytest -k "login or signup"
```

The `-k` flag matches against test names, so `-k "login or signup"` runs every test whose name contains either word.

Run only tests tagged with a [marker](https://docs.pytest.org/en/stable/how-to/mark.html):

```bash
uv run pytest -m slow
```

## Control Output

Show each test name instead of a dot:

```bash
uv run pytest -v
```

Print `print()` output and logging to the terminal (pytest captures them by default):

```bash
uv run pytest -s
```

Shorten tracebacks to just the failing assertion:

```bash
uv run pytest --tb=short
```

## Stop Early on Failure

Stop after the first failure:

```bash
uv run pytest -x
```

Stop after _n_ failures:

```bash
uv run pytest --maxfail=3
```

## Re-run Only Failed Tests

pytest records which tests passed and failed in `.pytest_cache/`. On the next run, `--last-failed` skips everything that passed:

```bash
uv run pytest --last-failed
```

Combine with `--fail-first` to run the previously failed tests first, then the rest:

```bash
uv run pytest --fail-first
```

## Set Persistent Defaults

Add flags to [pyproject.toml](https://pydevtools.com/handbook/reference/pyproject.toml.md) so they apply on every run without typing them:

```toml
[tool.pytest.ini_options]
addopts = "-x --tb=short"
```

Any flags passed on the command line are appended to `addopts`, so `uv run pytest -v` becomes `-x --tb=short -v`.

## Learn More

- [uv: A Complete Guide](https://pydevtools.com/handbook/explanation/uv-complete-guide.md) covers what uv does, how fast it is, the core workflows, and recent releases.
- [Setting up testing with pytest and uv](https://pydevtools.com/handbook/tutorial/setting-up-testing-with-pytest-and-uv.md) walks through creating a project with tests from scratch
- [How to test against multiple Python versions using uv](https://pydevtools.com/handbook/how-to/how-to-test-against-multiple-python-versions-using-uv.md) covers `--python` for cross-version testing
- [How to run tests in parallel with pytest-xdist](https://pydevtools.com/handbook/how-to/how-to-run-tests-in-parallel-with-pytest-xdist.md) distributes tests across CPU cores
- [How to fix common pytest errors with uv](https://pydevtools.com/handbook/how-to/how-to-fix-common-pytest-errors-with-uv.md) covers ModuleNotFoundError and other setup issues
- [pytest reference](https://pydevtools.com/handbook/reference/pytest.md)