pl-e2e-test 0.2.0__tar.gz → 0.2.2__tar.gz

{pl_e2e_test-0.2.0 → pl_e2e_test-0.2.2}/MANIFEST.in

@@ -1,2 +1,3 @@
 graft tests
+include scripts/demo_cli.py
 global-exclude *.py[cod]

{pl_e2e_test-0.2.0/src/pl_e2e_test.egg-info → pl_e2e_test-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pl-e2e-test
-Version: 0.2.0
+Version: 0.2.2
 Summary: Fuzz PrairieLearn question lifecycles against the real Python element runtime
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/PrairieLearn/pl-e2e-test
@@ -10,6 +10,7 @@ Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: chevron==0.14.0
+Requires-Dist: cyclopts<6,>=5.3
 Requires-Dist: filelock>=3.20
 Requires-Dist: jsonschema>=4.26
 Requires-Dist: lxml>=6.1
@@ -20,6 +21,7 @@ Requires-Dist: pyright>=1.1.414
 Requires-Dist: pytest>=9.1
 Requires-Dist: rich>=14
 Requires-Dist: ruff>=0.16
+Requires-Dist: tomlkit>=0.15.2
 Dynamic: license-file
 
 # pl-e2e-test
@@ -32,16 +34,18 @@ instead of copying the harness and its support scripts.
 The package installs the reusable `prairielearn_e2e` Python API and a single
 `pl-e2e-test` command:
 
-- `pl-e2e-test` (no command, or any pytest/harness options) runs the installed
-  lifecycle pytest suite.
+- `pl-e2e-test run` runs the installed lifecycle pytest suite.
 - `pl-e2e-test diff` fuzzes questions selected from a Git diff.
-- `pl-e2e-test parallel` runs local shards and merges their results.
+- `pl-e2e-test parallel run` and `parallel diff` run local shards and merge them.
 - `pl-e2e-test add-seed` records a failing concrete variant seed.
 - `pl-e2e-test reports` merges parallel shard results into terminal and JUnit reports.
 - `pl-e2e-test instances` shows configured, installed, cached, and local PrairieLearn
   revisions.
-- `pl-e2e-test version` prints the installed version.
-- `pl-e2e-test help [COMMAND]` prints top-level help, or one command's help.
+- `pl-e2e-test version [REVISION]` reads or updates the configured PrairieLearn revision.
+- `pl-e2e-test cache clean` clears the managed PrairieLearn instance cache.
+- `pl-e2e-test --version` prints the installed CLI version.
+- `pl-e2e-test help [COMMAND...]` prints top-level or nested command help. A bare
+  invocation also prints top-level help.
 
 ## Requirements and installation
 
@@ -83,20 +87,37 @@ Pass a question, a directory of questions, or an `info.json` file. Repeat
 `--question-path` to select multiple roots:
 
 ```sh
-uv run pl-e2e-test \
+uv run pl-e2e-test run \
   --question-path questions \
   --seed-count 3
 ```
 
 The installed suite exposes separate `generate`, `prepare`, `render`, and `grade`
-pytest markers. Any remaining arguments are passed to pytest:
+pytest markers. Put pytest selection and execution arguments after `--`:
 
 ```sh
-uv run pl-e2e-test \
+uv run pl-e2e-test -vv run \
   --question-path questions/chapter/example \
-  --fuzz-seeds -m render -x -vv
+  --fuzz-seeds -- -m render -x
 ```
 
+The native reporter owns progress, capture, tracebacks, summaries, and color. Use
+repeatable global `-q` or `-v` flags and `--color auto|always|never`; pytest
+presentation flags such as `-q`, `-v`, `--tb`, `-r`, `--color`, and `-s` are rejected
+after `--`. `NO_COLOR`, `FORCE_COLOR`, and `CLICOLOR_FORCE` are also honored.
+
+To preview the terminal UX without a PrairieLearn course or network access, run:
+
+```sh
+uv run python scripts/demo_cli.py
+uv run python scripts/demo_cli.py --color always mixed verbose cli-error
+uv run python scripts/demo_cli.py --list
+```
+
+The demo covers help and CLI errors plus passing, failing, skipped, xfailed/xpassed,
+warning, collection-error, empty-selection, quiet, verbose, and aggregate shard progress
+output.
+
 `--fuzz-seeds` creates and reports a random 64-bit master seed. Reproduce the same
 variant set with `--fuzz-seed N`. Without either option, deterministic seeds start at
 zero. Question metadata with `singleVariant: true` always uses seed zero.
@@ -106,22 +127,23 @@ zero. Question metadata with `singleVariant: true` always uses seed zero.
 Run multiple shards in one machine or CI job, with six concurrent processes by default:
 
 ```sh
-uv run pl-e2e-test parallel --shard-count 6 run -- \
+uv run pl-e2e-test parallel run --shard-count 6 \
   --question-path questions --fuzz-seeds
 
-uv run pl-e2e-test parallel --shard-count 6 --junitxml results.xml diff -- \
+uv run pl-e2e-test parallel diff --shard-count 6 --junitxml results.xml \
   --base main --fuzz-seed 42
 ```
 
-Launcher options go before the required `run` or `diff` selector; arguments after
-`--` are forwarded to that command. Normal runs remain deterministic. For
+Native options go after `parallel run` or `parallel diff` and before an optional `--`;
+only pytest arguments follow that boundary. Normal runs remain deterministic. For
 `--fuzz-seeds` and diff runs, the launcher generates one shared master seed unless
 `--fuzz-seed` is supplied, and prints a command for replaying the run without sharding.
 
 Each shard runs in a separate Python process using the current environment and
-working directory. Terminals show Rich progress; redirected output prints completion
-lines. All shards finish before reports are merged, even when a test fails. Captured
-failure output and successful stderr are shown before the combined summary.
+working directory. Terminals show aggregate progress; redirected output uses stable
+start and summary lines. All shards finish before reports are merged, even when a test
+fails. Raw child output is shown only when a launch or internal failure cannot produce
+a usable report.
 Interrupting the launcher stops and reaps its children.
 
 Intermediate reports are temporary. Pass the launcher's `--junitxml` option to retain
@@ -148,19 +170,19 @@ Relative JUnit paths are resolved against the course root. With `junitxml=None`,
 merged output is temporary. Invalid launcher settings raise `ValueError`.
 
 Courses using `scripts/run_e2e_shards.py` can replace its invocation with
-`pl-e2e-test parallel`, move `--fuzz-seed` into the forwarded arguments, and explicitly
+`pl-e2e-test parallel run`, move `--fuzz-seed` into the native arguments, and explicitly
 pass `--fuzz-seeds` for full-suite runs to preserve the script's fuzzing behavior.
 For example:
 
 ```make
 test-e2e-sharded:
-	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" run -- \
-		$(E2E_TEST_ARGS) $(E2E_PRAIRIELEARN_ARG) --fuzz-seeds $(E2E_FUZZ_SEED_ARG) $(PYTEST_ARGS)
+	uv run --active pl-e2e-test parallel run --shard-count "$(E2E_SHARD_COUNT)" \
+		$(E2E_TEST_ARGS) $(E2E_PRAIRIELEARN_ARG) --fuzz-seeds $(E2E_FUZZ_SEED_ARG) -- $(PYTEST_ARGS)
 
 test-e2e-fuzz-sharded:
-	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" diff -- \
+	uv run --active pl-e2e-test parallel diff --shard-count "$(E2E_SHARD_COUNT)" \
 		--base "$(E2E_DIFF_BASE)" --head "$(E2E_DIFF_HEAD)" \
-		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) $(PYTEST_ARGS)
+		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) -- $(PYTEST_ARGS)
 ```
 
 ### CI sharding
@@ -202,7 +224,7 @@ jobs:
       - run: uv python install && uv sync --locked
       - name: Run shard
         run: |
-          uv run pl-e2e-test \
+          uv run pl-e2e-test run \
             --question-path questions \
             --seed-count 10 \
             --fuzz-seed "${{ github.run_id }}" \
@@ -272,6 +294,34 @@ Add `--refresh` to resolve the configured moving selector and verify remote acce
 The table distinguishes fully hydrated runtime revisions from legacy element-only cache
 entries. Standard cache environment settings such as `XDG_CACHE_HOME` can relocate the
 managed cache; CI systems can persist that directory between runs if desired.
+Cache use refreshes each repository or hydrated runtime's last-use timestamp. Whenever
+the managed cache is used, unlocked items that have been idle for more than 30 days are
+removed automatically across all configured PrairieLearn sources.
+
+Read the effective configured selector without resolving it or contacting the network:
+
+```sh
+uv run pl-e2e-test version
+```
+
+Set `tool.pl-e2e-test.prairielearnVersion` in an existing `pyproject.toml` to a full
+commit or verified PrairieLearn release tag with:
+
+```sh
+uv run pl-e2e-test version 3.2.0
+```
+
+Release tags are verified against the configured PrairieLearn Git source before the
+file is changed. Use `--config PATH` to update another existing TOML file. Comments and
+unrelated formatting are preserved, and a missing file is not created.
+
+Remove all managed bare repositories and hydrated runtime revisions with:
+
+```sh
+uv run pl-e2e-test cache clean
+```
+
+The next test run fetches and hydrates its selected PrairieLearn revision again.
 
 ### Harness configuration
 
@@ -296,8 +346,8 @@ answers from grading checks. Each supplied list replaces its default; omitted se
 keep their defaults, and `[]` disables a list.
 
 Use `--config path/to/settings.toml` to select another TOML file with the same
-`[tool.pl-e2e-test]` table. This works with normal runs, `diff`, and arguments after
-`parallel run` or `parallel diff`. Explicit paths are relative to the working directory.
+`[tool.pl-e2e-test]` table. This works with `run`, `diff`, `parallel run`, and
+`parallel diff`. Explicit paths are relative to the working directory.
 
 ### Lifecycle JSON boundary
 
@@ -451,7 +501,7 @@ diffignore = [
 
 Rules use Git's native ignore syntax and are evaluated in order, so later rules may
 negate earlier ones with `!`. A missing `pyproject.toml`, tool table, or `diffignore`
-entry means that no paths are ignored. Additional arguments are forwarded to pytest.
+entry means that no paths are ignored. Additional pytest arguments must follow `--`.
 
 To migrate from `.question-e2e.diffignore`, copy its non-comment rules into the
 `diffignore` array. The former file and `--e2ediffignore` option are no longer used.

{pl_e2e_test-0.2.0 → pl_e2e_test-0.2.2}/README.md

@@ -8,16 +8,18 @@ instead of copying the harness and its support scripts.
 The package installs the reusable `prairielearn_e2e` Python API and a single
 `pl-e2e-test` command:
 
-- `pl-e2e-test` (no command, or any pytest/harness options) runs the installed
-  lifecycle pytest suite.
+- `pl-e2e-test run` runs the installed lifecycle pytest suite.
 - `pl-e2e-test diff` fuzzes questions selected from a Git diff.
-- `pl-e2e-test parallel` runs local shards and merges their results.
+- `pl-e2e-test parallel run` and `parallel diff` run local shards and merge them.
 - `pl-e2e-test add-seed` records a failing concrete variant seed.
 - `pl-e2e-test reports` merges parallel shard results into terminal and JUnit reports.
 - `pl-e2e-test instances` shows configured, installed, cached, and local PrairieLearn
   revisions.
-- `pl-e2e-test version` prints the installed version.
-- `pl-e2e-test help [COMMAND]` prints top-level help, or one command's help.
+- `pl-e2e-test version [REVISION]` reads or updates the configured PrairieLearn revision.
+- `pl-e2e-test cache clean` clears the managed PrairieLearn instance cache.
+- `pl-e2e-test --version` prints the installed CLI version.
+- `pl-e2e-test help [COMMAND...]` prints top-level or nested command help. A bare
+  invocation also prints top-level help.
 
 ## Requirements and installation
 
@@ -59,20 +61,37 @@ Pass a question, a directory of questions, or an `info.json` file. Repeat
 `--question-path` to select multiple roots:
 
 ```sh
-uv run pl-e2e-test \
+uv run pl-e2e-test run \
   --question-path questions \
   --seed-count 3
 ```
 
 The installed suite exposes separate `generate`, `prepare`, `render`, and `grade`
-pytest markers. Any remaining arguments are passed to pytest:
+pytest markers. Put pytest selection and execution arguments after `--`:
 
 ```sh
-uv run pl-e2e-test \
+uv run pl-e2e-test -vv run \
   --question-path questions/chapter/example \
-  --fuzz-seeds -m render -x -vv
+  --fuzz-seeds -- -m render -x
 ```
 
+The native reporter owns progress, capture, tracebacks, summaries, and color. Use
+repeatable global `-q` or `-v` flags and `--color auto|always|never`; pytest
+presentation flags such as `-q`, `-v`, `--tb`, `-r`, `--color`, and `-s` are rejected
+after `--`. `NO_COLOR`, `FORCE_COLOR`, and `CLICOLOR_FORCE` are also honored.
+
+To preview the terminal UX without a PrairieLearn course or network access, run:
+
+```sh
+uv run python scripts/demo_cli.py
+uv run python scripts/demo_cli.py --color always mixed verbose cli-error
+uv run python scripts/demo_cli.py --list
+```
+
+The demo covers help and CLI errors plus passing, failing, skipped, xfailed/xpassed,
+warning, collection-error, empty-selection, quiet, verbose, and aggregate shard progress
+output.
+
 `--fuzz-seeds` creates and reports a random 64-bit master seed. Reproduce the same
 variant set with `--fuzz-seed N`. Without either option, deterministic seeds start at
 zero. Question metadata with `singleVariant: true` always uses seed zero.
@@ -82,22 +101,23 @@ zero. Question metadata with `singleVariant: true` always uses seed zero.
 Run multiple shards in one machine or CI job, with six concurrent processes by default:
 
 ```sh
-uv run pl-e2e-test parallel --shard-count 6 run -- \
+uv run pl-e2e-test parallel run --shard-count 6 \
   --question-path questions --fuzz-seeds
 
-uv run pl-e2e-test parallel --shard-count 6 --junitxml results.xml diff -- \
+uv run pl-e2e-test parallel diff --shard-count 6 --junitxml results.xml \
   --base main --fuzz-seed 42
 ```
 
-Launcher options go before the required `run` or `diff` selector; arguments after
-`--` are forwarded to that command. Normal runs remain deterministic. For
+Native options go after `parallel run` or `parallel diff` and before an optional `--`;
+only pytest arguments follow that boundary. Normal runs remain deterministic. For
 `--fuzz-seeds` and diff runs, the launcher generates one shared master seed unless
 `--fuzz-seed` is supplied, and prints a command for replaying the run without sharding.
 
 Each shard runs in a separate Python process using the current environment and
-working directory. Terminals show Rich progress; redirected output prints completion
-lines. All shards finish before reports are merged, even when a test fails. Captured
-failure output and successful stderr are shown before the combined summary.
+working directory. Terminals show aggregate progress; redirected output uses stable
+start and summary lines. All shards finish before reports are merged, even when a test
+fails. Raw child output is shown only when a launch or internal failure cannot produce
+a usable report.
 Interrupting the launcher stops and reaps its children.
 
 Intermediate reports are temporary. Pass the launcher's `--junitxml` option to retain
@@ -124,19 +144,19 @@ Relative JUnit paths are resolved against the course root. With `junitxml=None`,
 merged output is temporary. Invalid launcher settings raise `ValueError`.
 
 Courses using `scripts/run_e2e_shards.py` can replace its invocation with
-`pl-e2e-test parallel`, move `--fuzz-seed` into the forwarded arguments, and explicitly
+`pl-e2e-test parallel run`, move `--fuzz-seed` into the native arguments, and explicitly
 pass `--fuzz-seeds` for full-suite runs to preserve the script's fuzzing behavior.
 For example:
 
 ```make
 test-e2e-sharded:
-	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" run -- \
-		$(E2E_TEST_ARGS) $(E2E_PRAIRIELEARN_ARG) --fuzz-seeds $(E2E_FUZZ_SEED_ARG) $(PYTEST_ARGS)
+	uv run --active pl-e2e-test parallel run --shard-count "$(E2E_SHARD_COUNT)" \
+		$(E2E_TEST_ARGS) $(E2E_PRAIRIELEARN_ARG) --fuzz-seeds $(E2E_FUZZ_SEED_ARG) -- $(PYTEST_ARGS)
 
 test-e2e-fuzz-sharded:
-	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" diff -- \
+	uv run --active pl-e2e-test parallel diff --shard-count "$(E2E_SHARD_COUNT)" \
 		--base "$(E2E_DIFF_BASE)" --head "$(E2E_DIFF_HEAD)" \
-		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) $(PYTEST_ARGS)
+		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) -- $(PYTEST_ARGS)
 ```
 
 ### CI sharding
@@ -178,7 +198,7 @@ jobs:
       - run: uv python install && uv sync --locked
       - name: Run shard
         run: |
-          uv run pl-e2e-test \
+          uv run pl-e2e-test run \
             --question-path questions \
             --seed-count 10 \
             --fuzz-seed "${{ github.run_id }}" \
@@ -248,6 +268,34 @@ Add `--refresh` to resolve the configured moving selector and verify remote acce
 The table distinguishes fully hydrated runtime revisions from legacy element-only cache
 entries. Standard cache environment settings such as `XDG_CACHE_HOME` can relocate the
 managed cache; CI systems can persist that directory between runs if desired.
+Cache use refreshes each repository or hydrated runtime's last-use timestamp. Whenever
+the managed cache is used, unlocked items that have been idle for more than 30 days are
+removed automatically across all configured PrairieLearn sources.
+
+Read the effective configured selector without resolving it or contacting the network:
+
+```sh
+uv run pl-e2e-test version
+```
+
+Set `tool.pl-e2e-test.prairielearnVersion` in an existing `pyproject.toml` to a full
+commit or verified PrairieLearn release tag with:
+
+```sh
+uv run pl-e2e-test version 3.2.0
+```
+
+Release tags are verified against the configured PrairieLearn Git source before the
+file is changed. Use `--config PATH` to update another existing TOML file. Comments and
+unrelated formatting are preserved, and a missing file is not created.
+
+Remove all managed bare repositories and hydrated runtime revisions with:
+
+```sh
+uv run pl-e2e-test cache clean
+```
+
+The next test run fetches and hydrates its selected PrairieLearn revision again.
 
 ### Harness configuration
 
@@ -272,8 +320,8 @@ answers from grading checks. Each supplied list replaces its default; omitted se
 keep their defaults, and `[]` disables a list.
 
 Use `--config path/to/settings.toml` to select another TOML file with the same
-`[tool.pl-e2e-test]` table. This works with normal runs, `diff`, and arguments after
-`parallel run` or `parallel diff`. Explicit paths are relative to the working directory.
+`[tool.pl-e2e-test]` table. This works with `run`, `diff`, `parallel run`, and
+`parallel diff`. Explicit paths are relative to the working directory.
 
 ### Lifecycle JSON boundary
 
@@ -427,7 +475,7 @@ diffignore = [
 
 Rules use Git's native ignore syntax and are evaluated in order, so later rules may
 negate earlier ones with `!`. A missing `pyproject.toml`, tool table, or `diffignore`
-entry means that no paths are ignored. Additional arguments are forwarded to pytest.
+entry means that no paths are ignored. Additional pytest arguments must follow `--`.
 
 To migrate from `.question-e2e.diffignore`, copy its non-comment rules into the
 `diffignore` array. The former file and `--e2ediffignore` option are no longer used.

{pl_e2e_test-0.2.0 → pl_e2e_test-0.2.2}/pyproject.toml

@@ -4,13 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pl-e2e-test"
-version = "0.2.0"
+version = "0.2.2"
 description = "Fuzz PrairieLearn question lifecycles against the real Python element runtime"
 readme = "README.md"
 requires-python = ">=3.13"
 license = "MIT"
 dependencies = [
   "chevron==0.14.0",
+  "cyclopts>=5.3,<6",
   "filelock>=3.20",
   "jsonschema>=4.26",
   "lxml>=6.1",
@@ -21,6 +22,7 @@ dependencies = [
   "pytest>=9.1",
   "rich>=14",
   "ruff>=0.16",
+  "tomlkit>=0.15.2",
 ]
 
 [dependency-groups]

pl_e2e_test-0.2.2/scripts/demo_cli.py

@@ -0,0 +1,219 @@
+"""Show the pl-e2e-test terminal UX without a course or network access."""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import textwrap
+from collections.abc import Callable, Sequence
+from itertools import count
+from pathlib import Path
+from typing import cast
+
+import pytest
+
+from prairielearn_e2e import cli
+from prairielearn_e2e.parallel import _shard_progress
+from prairielearn_e2e.reporting import NativeReporter
+from prairielearn_e2e.ui import CliContext, ColorChoice, make_console
+
+type Demo = Callable[[ColorChoice], int]
+_CASE_IDS = count()
+
+
+def _pytest_demo(
+    color: ColorChoice,
+    source: str,
+    *,
+    quiet: int = 0,
+    verbose: int = 0,
+    pytest_args: Sequence[str] = (),
+) -> int:
+    with tempfile.TemporaryDirectory(prefix="pl-e2e-terminal-demo-") as temporary:
+        root = Path(temporary)
+        test_file = root / f"test_demo_{next(_CASE_IDS)}.py"
+        test_file.write_text(textwrap.dedent(source), encoding="utf-8")
+        context = CliContext(color=color, quiet=quiet, verbose=verbose)
+        reporter = NativeReporter(context)
+        return int(
+            pytest.main(
+                [
+                    os.fspath(test_file),
+                    "--rootdir",
+                    os.fspath(root),
+                    *pytest_args,
+                ],
+                plugins=[reporter],
+            )
+        )
+
+
+def _help(color: ColorChoice) -> int:
+    return cli.main(["--color", color, "--help"])
+
+
+def _cli_error(color: ColorChoice) -> int:
+    return cli.main(["--color", color, "rn"])
+
+
+def _passing(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        def test_passes():
+            print("captured output from a passing test")
+        """,
+    )
+
+
+def _mixed(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        import warnings
+        import pytest
+
+        def test_passes():
+            print("passing capture is hidden at default verbosity")
+
+        def test_fails():
+            print("captured stdout from the failing test")
+            assert {"actual": 1} == {"expected": 2}
+
+        @pytest.mark.skip(reason="optional service is unavailable")
+        def test_skips():
+            pass
+
+        @pytest.mark.xfail(reason="known upstream issue")
+        def test_expected_failure():
+            assert False
+
+        @pytest.mark.xfail(reason="the upstream issue may be fixed")
+        def test_unexpected_pass():
+            pass
+
+        def test_warns():
+            warnings.warn("example lifecycle warning", UserWarning)
+        """,
+    )
+
+
+def _collection_error(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        def test_broken(:
+            pass
+        """,
+    )
+
+
+def _empty(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        def test_passes():
+            pass
+        """,
+        pytest_args=("-k", "does-not-exist"),
+    )
+
+
+def _quiet(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        def test_passes_silently():
+            pass
+        """,
+        quiet=2,
+    )
+
+
+def _verbose(color: ColorChoice) -> int:
+    return _pytest_demo(
+        color,
+        """
+        def test_verbose_capture():
+            print("captured output shown by -vv")
+        """,
+        verbose=2,
+    )
+
+
+def _shards(color: ColorChoice) -> int:
+    console = make_console(color=color)
+    outcomes = (True, True, False, True)
+    with _shard_progress(console, len(outcomes), disable=False) as complete:
+        for index, succeeded in enumerate(outcomes, start=1):
+            complete(index, succeeded)
+    return 1
+
+
+DEMOS: dict[str, Demo] = {
+    "help": _help,
+    "cli-error": _cli_error,
+    "passing": _passing,
+    "mixed": _mixed,
+    "collection-error": _collection_error,
+    "empty": _empty,
+    "quiet": _quiet,
+    "verbose": _verbose,
+    "shards": _shards,
+}
+
+
+def _arguments(argv: Sequence[str]) -> tuple[ColorChoice, list[str], bool]:
+    color: ColorChoice = "auto"
+    selected: list[str] = []
+    list_only = False
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--list":
+            list_only = True
+        elif token.startswith("--color="):
+            value = token.split("=", 1)[1]
+            if value not in {"auto", "always", "never"}:
+                raise ValueError("--color must be auto, always, or never")
+            color = cast(ColorChoice, value)
+        elif token == "--color":
+            index += 1
+            if index >= len(argv) or argv[index] not in {"auto", "always", "never"}:
+                raise ValueError("--color must be followed by auto, always, or never")
+            color = cast(ColorChoice, argv[index])
+        elif token.startswith("-"):
+            raise ValueError(f"unknown option: {token}")
+        else:
+            selected.append(token)
+        index += 1
+    return color, selected, list_only
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        color, selected, list_only = _arguments(sys.argv[1:] if argv is None else argv)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if list_only:
+        print("\n".join(DEMOS))
+        return 0
+    unknown = [name for name in selected if name not in DEMOS]
+    if unknown:
+        print(f"error: unknown demo {unknown[0]!r}", file=sys.stderr)
+        print(f"available demos: {', '.join(DEMOS)}", file=sys.stderr)
+        return 2
+
+    console = make_console(color=color)
+    for name in selected or list(DEMOS):
+        console.rule(f"demo: {name}", style="bold cyan")
+        status = DEMOS[name](color)
+        console.print(f"[dim]exit status: {status}[/dim]")
+        console.print()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())