Metadata-Version: 2.4
Name: pytest-tui-run
Version: 0.1.1
Summary: TUI runner for `pytest` tests
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Framework :: Pytest
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2.7
Requires-Dist: pytest
Requires-Dist: textual
Requires-Python: >=3.11, <3.15
Project-URL: Changelog, https://gitlab.com/clov/pytest-tui-run/-/blob/main/CHANGELOG.md
Project-URL: Repository, https://gitlab.com/clov/pytest-tui-run
Project-URL: Tracker, https://gitlab.com/clov/pytest-tui-run/issues
Description-Content-Type: text/markdown

# pytest-tui-run

[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pytest-tui-run)](https://pypi.org/project/pytest-tui-run/)
[![PyPI - Version](https://img.shields.io/pypi/v/pytest-tui-run)](https://pypi.org/project/pytest-tui-run/)

TUI test runner for [pytest](https://docs.pytest.org/en/stable/).

![pytest-tui-run in action](https://gitlab.com/clov/pytest-tui-run/-/raw/main/screenshot.png)

## Motivation

Do you like running `pytest` from the terminal, but find it difficult to run a subset
of tests? Do you like VS Code's test tree view, but hate using the mouse? Then
`pytest-tui-run` is for you: it combines the best of both worlds by showing you the
collected test tree, but allows you to use your keyboard to select and run tests.
Even better, it comes with `vim`-like keybindings by default, which are fully
configurable.

## Alternatives

There are similar projects, but none with the same scope.
- [pytest-explorer](https://github.com/antonguzun/pytest-explorer).
  TUI for running pytest tests. Fast, but no tree view and no test selection
  (apart from filtering).
- [pytest-tui-runner](https://github.com/JanMalek03/pytest-tui-runner).
  TUI for running pytest tests that have been selected in a configuration file.
  Mouse centric and no view of all tests.
- [pytest-tui](https://github.com/jeffwright13/pytest-tui).
  Pytest plugin TUI for exploring pytest *results*. No test running.
- [VS Code Testing View](https://code.visualstudio.com/docs/debugtest/testing).
  GUI for running tests in a tree view. Plugins for multiple languages and test
  frameworks. Mouse centric and works only in VS Code.
- [Neotest](https://github.com/nvim-neotest/neotest) plugin for
  [Neovim](https://neovim.io/).
  TUI for running tests in a tree view. Plugins for multiple languages and test
  frameworks. Works only in Neovim.

## Philosophy

Don't reinvent the wheel: everything that can be delegated to `pytest`, is delegated to
`pytest`. This is to keep the plugin as lightweight as possible to minimize the burden
of maintaining. In practice this means that the plugin mostly just modifies the
user-given `pytest` arguments, and then runs `pytest` with those arguments.

## Installation

The package is distributed through PyPI, so simply use your favorite package manager.
For example using `pip`:
```bash
pip install pytest-tui-run
```

## Usage

This is a `pytest` plugin, so you can start it from the terminal by
```bash
pytest --tui-run
```
Just give it the arguments you would normally give to plain `pytest`. Another option
is to start the app directly:
```bash
pytest-tui-run
```

There are two ways to run the (selected) tests:

### Run tests in TUI

Press `r` to run the (selected) tests directly in the TUI. This shows you the output
and marks the test results in the tree.

### Run tests in CLI

Press `R` to run the (selected) tests in CLI. This exits the TUI and prints you the
proper `pytest` command to run.

## Configuration

The [default configuration](https://gitlab.com/clov/pytest-tui-run/-/blob/main/pytest_tui_run/config/pytest-tui-run.toml)
includes all the available configuration options. A
[schema](https://gitlab.com/clov/pytest-tui-run/-/blob/main/pytest_tui_run/config/pytest-tui-run.schema.json)
is included for validation. Both of these are included with the package to ensure
compatible versions. To get started, run
```bash
pytest --tui-run --init-config
```
This will copy the default config to your config directory
(usually `~/.config/pytest-tui-run/`, unless you have some custom `XDG_CONFIG_HOME` set)
and create a symlink to the schema. 

You may use your favorite validation tool, but a schema directive for
[Taplo](https://taplo.tamasfe.dev/)
(in VS Code the
[Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
plugin)
is included in the config file by default. In other words, if you have a
Taplo-compatible editor, you should get schema validation out of the box, assuming
you have properly symlinked the schema file.

## Contributing

Contributions are welcome. See
[CONTRIBUTING.md](https://gitlab.com/clov/pytest-tui-run/-/blob/main/CONTRIBUTING.md)
for details.
