pytest-tui-run

TUI for running pytest.

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. TUI for running pytest tests. Fast, but no tree view and no test selection (apart from filtering).
• 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. Pytest plugin TUI for exploring pytest results. No test running.
• VS Code Testing View. GUI for running tests in a tree view. Plugins for multiple languages and test frameworks. Mouse centric and works only in VS Code.
• Neotest plugin for Neovim. 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:

pip install pytest-tui-run

Usage

This is a pytest plugin, so you can start it from the terminal by

pytest --tui-run

Just give it the arguments you would normally give to plain pytest. Another option is to start the app directly:

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 includes all the available configuration options. A schema is included for validation. Both of these are included with the package to ensure compatible versions. To get started, run

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 (in VS Code the 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 for details.