Metadata-Version: 2.4
Name: pytest-tui-run
Version: 0.1.0rc3
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
Classifier: Topic :: Software Development :: Testing
Requires-Dist: pydantic>=2.7
Requires-Dist: pytest
Requires-Dist: textual
Requires-Python: >=3.11, <3.15
Description-Content-Type: text/markdown

# 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 exploring `pytest` tests. No tree view.
- [pytest-tui](https://github.com/jeffwright13/pytest-tui).
  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.toml)
includes all the available configuration options. A
[schema](https://gitlab.com/clov/pytest-tui-run/-/blob/main/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/`) 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.
