Scenario Matrix¶

The full set of scenarios is defined in src/launch_lab/matrix.py.

This document provides a human-readable summary.

Legend¶

Column	Meaning
Scenario ID	Unique string key used in artifact filenames
Launcher	Top-level executable
Mode	Script or tool invocation style
Fixture	Input package or script
Win-only	Scenario is skipped on non-Windows
Needs uv	Requires uv on PATH

Direct Python / PythonW¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Needs uv
`python-script-py`	`python`	`script.py`	`raw_py`	No	No
`python-script-pyw`	`python`	`script.pyw`	`raw_pyw`	Yes	No
`pythonw-script-py`	`pythonw`	`script.py`	`raw_py`	Yes	No
`pythonw-script-pyw`	`pythonw`	`script.pyw`	`raw_pyw`	Yes	No

uv run¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Needs uv
`uv-run-script-py`	`uv`	`run script.py`	`raw_py`	No	Yes
`uv-run-script-pyw`	`uv`	`run script.pyw`	`raw_pyw`	No	Yes
`uv-run-gui-script`	`uv`	`run --gui-script script.py`	`raw_py`	Yes	Yes
`uvw-run-script-py`	`uvw`	`run script.py`	`raw_py`	Yes	Yes

uvx / uv tool run¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Needs uv
`uvx-pkg-console`	`uvx`	`tool run console fixture`	`pkg_console`	No	Yes
`uv-tool-run-pkg-console`	`uv`	`tool run console fixture`	`pkg_console`	No	Yes

uv tool install¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Needs uv
`uv-tool-install-console`	`uv`	`tool install console fixture`	`pkg_console`	No	Yes
`uv-tool-install-gui`	`uv`	`tool install gui fixture`	`pkg_gui`	Yes	Yes

Virtual Environment (venv) Direct Execution¶

These scenarios test executables inside a Python virtual environment created with python -m venv. Because venv paths are dynamic (they depend on the temporary directory used by the test), these scenarios carry a skip_reason in the matrix runner and are exercised exclusively by the integration tests in tests/integration/test_venv.py.

venv python / pythonw executables¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Notes
`venv-python-script-py`	`venv-direct`	`venv python script.py`	`raw_py`	No	venv `python` is a CUI executable; allocates a console window on Windows
`venv-pythonw-script-py`	`venv-direct`	`venv pythonw script.py`	`raw_py`	Yes	venv `pythonw` is a GUI executable; does not allocate a console window

venv project.scripts / project.gui-scripts entrypoints¶

When a package with [project.scripts] is installed into a venv, pip generates a small CUI .exe wrapper (on Windows) that inherits or creates a console. [project.gui-scripts] entries receive a GUI .exe wrapper that does not create a console window.

Scenario ID	Launcher	Mode	Fixture	Win-only	Notes
`venv-console-entrypoint`	`venv-direct`	`venv project.scripts entrypoint`	`pkg_console`	No	CUI wrapper; console window expected
`venv-gui-entrypoint`	`venv-direct`	`venv project.gui-scripts entrypoint`	`pkg_gui`	Yes	GUI wrapper; no console window
`venv-dual-console-entrypoint`	`venv-direct`	`venv dual project.scripts entrypoint`	`pkg_dual`	No	CUI wrapper from a package that has both script types
`venv-dual-gui-entrypoint`	`venv-direct`	`venv dual project.gui-scripts entrypoint`	`pkg_dual`	Yes	GUI wrapper from a package that has both script types

Key observations (Windows)¶

venv python.exe — CUI copy/symlink of the base interpreter. It behaves identically to the system python.exe: allocates a console and supports stdout/stderr.
venv pythonw.exe — GUI copy/symlink of the base interpreter. Does not allocate a console; stdout writes are silently discarded.
[project.scripts] wrappers — CUI .exe files generated by pip. They launch the venv Python and call the entrypoint function, inheriting the console from the parent process.
[project.gui-scripts] wrappers — GUI .exe files generated by pip. They launch pythonw and call the entrypoint function without creating a console window.

Rust Shim¶

Scenario ID	Launcher	Mode	Fixture	Win-only	Needs uv
`shim-python-script-py`	`pyshim-win`	`--hide-console python script.py`	`raw_py`	Yes	No
`shim-uv-run-script-py`	`pyshim-win`	`--hide-console uv run script.py`	`raw_py`	Yes	Yes