pytest-tui-run 0.1.0rc3__tar.gz

pytest_tui_run-0.1.0rc3/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Teemu Peltonen <peltonen.teemu.89@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pytest_tui_run-0.1.0rc3/PKG-INFO

@@ -0,0 +1,113 @@
+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.

pytest_tui_run-0.1.0rc3/README.md

@@ -0,0 +1,96 @@
+# 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.

pytest_tui_run-0.1.0rc3/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "pytest-tui-run"
+version = "0.1.0rc3"
+description = "TUI runner for `pytest` tests"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">= 3.11, < 3.15"
+classifiers = [
+  "Environment :: Console",
+  "Framework :: Pytest",
+  "Operating System :: POSIX",
+  "Programming Language :: Python",
+  "Topic :: Software Development :: Testing",
+]
+dependencies = [
+  "pydantic >= 2.7", # Data (config) validation
+  "pytest",
+  "textual", # TUI library
+]
+
+[dependency-groups]
+test = [
+  "pytest-asyncio",
+  "pytest-xdist", # Parallel test execution
+  "ruff", # Linting and formatting
+  "taplo", # Validate and format TOML
+  "ty", # Type checking and LSP
+]
+dev = [
+  "icecream", # Better debugging
+  "textual-dev",
+  "tomlkit", # Write TOML files
+  { include-group = "test" },
+]
+
+[project.scripts]
+pytest-tui-run = "pytest_tui_run.cli:main"
+
+# Register this as a pytest plugin
+[project.entry-points.pytest11]
+tui-run = "pytest_tui_run.plugin"
+
+[tool.pytest]
+testpaths = ["pytest_tui_run", "tests"]
+addopts = ["--doctest-modules"]
+doctest_optionflags = ["NORMALIZE_WHITESPACE", "IGNORE_EXCEPTION_DETAIL"]
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+docstring-code-format = true
+line-ending = "lf"
+
+[tool.ruff.lint]
+select = [
+  "ANN", # flake8-annotations
+  "B", # flake8-bugbear
+  "E", # pycodestyle
+  "F", # Pyflakes
+  "I", # isort
+  "SIM", # flake8-simplify
+  "UP", # pyupgrade
+]
+ignore = [
+  "E501", # line-too-long
+  "SIM108", # if-else-block-instead-of-if-exp
+]
+
+[build-system]
+requires = ["uv_build>=0.11.11,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# Need to configure these for a non-src layout
+module-name = "pytest_tui_run"
+module-root = ""
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

pytest_tui_run-0.1.0rc3/pytest_tui_run/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

pytest_tui_run-0.1.0rc3/pytest_tui_run/app.py

@@ -0,0 +1,236 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, ClassVar
+
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.containers import Vertical
+from textual.css.query import NoMatches
+from textual.driver import Driver
+from textual.types import CSSPathType
+from textual.widgets import Footer, HelpPanel, RichLog
+
+from .constants import WidgetID
+from .filter_modal import (
+    FilterModal,
+    filter_modal_cls_factory,
+)
+from .pytest_utils import PyTestConfig
+from .tree import PyTestTree, py_test_tree_cls_factory
+from .tree_node_data import PyTestNodeIDParser
+from .types import PyTestNodeID
+from .utils import SubprocessRunner, parse_pytest_collect_output_line
+from .vim_log import vim_log_cls_factory
+
+if TYPE_CHECKING:
+    from .config import Config
+
+
+class TreeApp(App, inherit_bindings=False):
+    """TUI for viewing, selecting, and running pytest tests."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding(
+            "s", "toggle_output", "Output", tooltip="Show/hide pytest output", show=True
+        ),
+        Binding("f5", "refresh", "Refresh", tooltip="Refresh tests", show=False),
+        Binding(
+            "q,ctrl+q",
+            "quit",
+            "Quit",
+            tooltip="Quit the app",
+            show=True,
+            priority=True,
+        ),
+        Binding(
+            "question_mark",
+            "toggle_help_panel",
+            "Help",
+            tooltip="Show/hide keybinds",
+            show=True,
+        ),
+        Binding(
+            "escape",
+            "hide_unnecessary_widgets",
+            "Hide",
+            tooltip="Hide unnecessary widgets",
+            show=False,
+        ),
+    ]
+    DEFAULT_CSS = """
+    ScrollableContainer {
+        scrollbar-size-horizontal: 1;
+        scrollbar-size-vertical: 1;
+    }
+    """
+    FILTER_MODAL_CLS: ClassVar[type[FilterModal]]
+
+    CONFIG: ClassVar[Config]
+    """App configuration."""
+
+    pytest_config: PyTestConfig
+    """Pytest configuration object."""
+    pytest_nodeid_parser: PyTestNodeIDParser
+    """Pytest `nodeid` parser."""
+    tests: list[PyTestNodeID]
+    """Collected pytest test `nodeid`s."""
+    _subprocess_runner: SubprocessRunner
+    """Subprocess runner (for running pytest in a subprocess)."""
+
+    def __init__(
+        self,
+        # Custom arguments
+        pytest_args: list[str],
+        pytest_nodeid_parser: PyTestNodeIDParser,
+        # Inherited arguments
+        driver_class: type[Driver] | None = None,
+        css_path: CSSPathType | None = None,
+        watch_css: bool = False,
+        ansi_color: bool = False,
+    ) -> None:
+        """Create an app instance.
+
+        Args:
+            pytest_args: Raw user-given arguments passed to pytest
+            pytest_nodeid_parser: Pytest `nodeid` parser
+            driver_class: See `textual.app.App` documentation
+            css_path: See `textual.app.App` documentation
+            watch_css: See `textual.app.App` documentation
+            ansi_color: See `textual.app.App` documentation
+
+        Raises:
+            CssPathError: See `textual.app.App` documentation
+        """
+        super().__init__(driver_class, css_path, watch_css, ansi_color)
+
+        self.pytest_config = PyTestConfig.from_args(pytest_args)
+        self.pytest_nodeid_parser = pytest_nodeid_parser
+
+        self.tests = []
+        self._pytest_collect_proc = None
+        self._subprocess_runner = SubprocessRunner()
+
+    def _build_tree(self, pytest_nodeids: list[PyTestNodeID]) -> None:
+        """Build the tree."""
+        tree = self.query_one(PyTestTree)
+        tree.clear()
+        tree.build(pytest_nodeids, self.pytest_nodeid_parser)
+        tree.root.expand_all()
+
+    def action_toggle_output(self) -> None:
+        """Toggle output widget visibility."""
+        output = self.query_one(WidgetID.output.query)
+        output.display = not output.display
+
+    def _finish_refresh(self) -> None:
+        """Finish refresh action."""
+        tree = self.query_one(PyTestTree)
+        output = self.query_one(WidgetID.output.query)
+
+        tree.set_loading(False)
+        # Force UI update
+        self.refresh()
+        output.display = False
+        if self.CONFIG.app.notifications.enable_test_collection:
+            self.notify("Test collection complete")
+
+    @work(thread=True)
+    def _pytest_collect_worker(self, args: list[str], output: RichLog) -> None:
+        """Worker to collect pytest test `nodeid`s."""
+
+        def handle_output(output: RichLog, line: str) -> None:
+            output.write(Text.from_ansi(line))
+            nodeid = parse_pytest_collect_output_line(line)
+            if nodeid is not None:
+                self.tests.append(nodeid)
+
+        self.tests = []
+        self._subprocess_runner.run(args, output, handle_output)
+
+        self.call_from_thread(self._build_tree, self.tests)
+        self.call_from_thread(self._finish_refresh)
+
+    def _collect_and_build_tree(self) -> None:
+        """Collect tests and build the tree."""
+        tree = self.query_one(PyTestTree)
+        output = self.query_one(WidgetID.output.query, RichLog)
+
+        if self.CONFIG.app.notifications.enable_test_collection:
+            self.notify("Collecting tests...")
+        tree.set_loading(True)
+
+        user_args = self.pytest_config.args
+        # Make sure we use the needed `-q` flag
+        user_args = [arg for arg in user_args if arg not in ["-v", "--verbose", "-vv"]]
+        args = ["pytest", "--collect-only", "-q", "--color=yes"] + user_args
+
+        output.clear()
+        output.display = True
+        cmd = f"> {' '.join(args)}\n"
+        output.write(Text(cmd))
+
+        self._pytest_collect_worker(args, output)
+
+    def refresh_tests(self) -> None:
+        """Refresh tests: collect tests and build the tree."""
+        self._collect_and_build_tree()
+
+    def action_refresh(self) -> None:
+        """Refresh tests: collect tests and build the tree."""
+        self.refresh_tests()
+
+    def is_help_panel_open(self) -> bool:
+        """Is the help panel open?"""
+        try:
+            self.screen.query_one(HelpPanel)
+            return True
+        except NoMatches:
+            return False
+
+    def action_toggle_help_panel(self) -> None:
+        """Toggle help panel visibility."""
+        if self.is_help_panel_open():
+            self.action_hide_help_panel()
+        else:
+            self.action_show_help_panel()
+
+    def action_hide_unnecessary_widgets(self) -> None:
+        """Hide all unnecessary widgets."""
+        self.action_hide_help_panel()
+        self.query_one(WidgetID.output.query).display = False
+
+
+def tree_app_cls_factory(config: Config) -> type[TreeApp]:
+    """Create a `TreeApp` class with the given config."""
+
+    class ConfiguredTreeApp(
+        TreeApp, inherit_bindings=config.app.inherit_default_bindings
+    ):
+        BINDINGS = config.app.bindings
+        CONFIG = config
+        FILTER_MODAL_CLS = filter_modal_cls_factory(config.filter_modal)
+
+        def compose(self) -> ComposeResult:
+            with Vertical():
+                tree_cls = py_test_tree_cls_factory(config.tree)
+                tree = tree_cls(label=os.getcwd())
+                yield tree
+
+                log_cls = vim_log_cls_factory(config.output)
+                output = log_cls(id=WidgetID.output, markup=True, wrap=True)
+                output.border_title = "Output"
+                yield output
+            yield Footer()
+
+        def on_mount(self) -> None:
+            if config.app.notifications.enable_config_loading:
+                if config.found:
+                    self.notify(f"Config loaded from `{config.path}`")
+                else:
+                    self.notify(f"No config found at `{config.path}`; using defaults")
+            self._collect_and_build_tree()
+
+    return ConfiguredTreeApp

pytest_tui_run-0.1.0rc3/pytest_tui_run/cli.py

@@ -0,0 +1,125 @@
+import argparse
+import shutil
+import sys
+import textwrap
+from importlib.metadata import version
+
+from .app import TreeApp, tree_app_cls_factory
+from .config import Config
+from .constants import APP_NAME, PackageConfigPaths, UserConfigPaths
+from .tree_node_data import PyTestNodeIDParser
+
+
+def init_user_config(overwrite: bool = False) -> None:
+    """Initialize user config: copy default config and symlink schema."""
+
+    config_dir = UserConfigPaths.config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    pkg_paths = PackageConfigPaths()
+    print(f"Found package installation directory: {pkg_paths.pkg_dir}")
+    initialized = False
+
+    # Copy the default config
+    config_src = pkg_paths.config_file
+    config_dst = UserConfigPaths.config_file()
+    print(f"Copying config to: {config_dst}")
+    if not config_dst.exists() or overwrite:
+        shutil.copy2(config_src, config_dst)
+        initialized = True
+    else:
+        print("Config already exists, overwrite? [y/N]")
+        if input().lower() == "y":
+            shutil.copy2(config_src, config_dst)
+            initialized = True
+
+    # Symlink the schema
+    schema_src = pkg_paths.schema_file
+    schema_dst = UserConfigPaths.schema_file()
+    print(f"Symlinking schema to: {schema_dst}")
+    if not schema_dst.exists() or overwrite:
+        schema_dst.unlink()
+        schema_dst.symlink_to(schema_src)
+        initialized = True
+    else:
+        print("Schema already exists, overwrite? [y/N]")
+        if input().lower() == "y":
+            schema_dst.unlink()
+            schema_dst.symlink_to(schema_src)
+            initialized = True
+
+    if initialized:
+        print(f"Config/schema initialized at: {config_dir}")
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the argument parser for the app."""
+    parser = argparse.ArgumentParser(
+        prog=APP_NAME,
+        description="TUI for running pytest tests",
+        epilog=textwrap.dedent("""
+        All unrecognized arguments are passed through to pytest.
+
+        Examples:
+          %(prog)s -v                   # Run with verbose pytest output
+          %(prog)s tests/test_mod.py    # Run specific test file
+          %(prog)s -k test_foo -m slow  # Filter with pytest -k and -m flags
+
+        You can also use it as a pytest plugin:
+          pytest --tui-run
+
+        For pytest help:
+          pytest --help
+        """),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="store_true",
+        help="Show version and exit",
+    )
+    parser.add_argument(
+        "--init-config",
+        action="store_true",
+        help="Initialize config: create config directory, and copy default config "
+        "and symlink its schema there",
+    )
+    parser.add_argument(
+        "--finit-config",
+        action="store_true",
+        help="Forced --init-config: overwrites existing config and schema if present",
+    )
+    return parser
+
+
+def main_app(
+    config: Config | None = None, argv: list[str] | None = None
+) -> TreeApp | None:
+    """Main (CLI) entry point to the TUI app, without running it."""
+    if argv is None:
+        argv = sys.argv[1:]
+    parser = create_parser()
+    args, pytest_args = parser.parse_known_args(argv)
+
+    if args.version:
+        print(APP_NAME, version(APP_NAME))
+        return
+    if args.init_config or args.finit_config:
+        init_user_config(overwrite=args.finit_config)
+        return
+
+    if config is None:
+        config = Config.from_file()
+    app_cls = tree_app_cls_factory(config)
+    nodeid_parser = PyTestNodeIDParser(config.tree.nodes)
+    app = app_cls(pytest_args, nodeid_parser)
+    return app
+
+
+def main(config: Config | None = None, argv: list[str] | None = None) -> None:
+    """Main (CLI) entry point to the TUI app."""
+    app = main_app(config, argv)
+    if app is None:
+        return
+    app.run()