pl-e2e-test 0.1.2__tar.gz → 0.1.3__tar.gz

{pl_e2e_test-0.1.2/src/pl_e2e_test.egg-info → pl_e2e_test-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pl-e2e-test
-Version: 0.1.2
+Version: 0.1.3
 Summary: Fuzz PrairieLearn question lifecycles against the real Python element runtime
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/PrairieLearn/pl-e2e-test
@@ -18,6 +18,7 @@ Requires-Dist: platformdirs>=4.5
 Requires-Dist: prairielearn
 Requires-Dist: pyright>=1.1.414
 Requires-Dist: pytest>=9.1
+Requires-Dist: rich>=14
 Requires-Dist: ruff>=0.16
 Dynamic: license-file
 
@@ -34,6 +35,7 @@ The package installs the reusable `prairielearn_e2e` Python API and a single
 - `pl-e2e-test` (no command, or any pytest/harness options) 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 add-seed` records a failing concrete variant seed.
 - `pl-e2e-test reports` merges parallel shard results into terminal and JUnit reports.
 - `pl-e2e-test version` prints the installed version.
@@ -96,6 +98,68 @@ uv run pl-e2e-test \
 variant set with `--fuzz-seed N`. Without either option, deterministic seeds start at
 zero. Question metadata with `singleVariant: true` always uses seed zero.
 
+### Local parallel runs
+
+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 -- \
+  --question-path questions --fuzz-seeds
+
+uv run pl-e2e-test parallel --shard-count 6 --junitxml results.xml diff -- \
+  --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
+`--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.
+Interrupting the launcher stops and reaps its children.
+
+Intermediate reports are temporary. Pass the launcher's `--junitxml` option to retain
+merged JUnit output. Forwarded `--shard`, `--shard-report`, `--junitxml`, and
+`--junit-xml` options are rejected because the launcher manages those outputs.
+Choose the course with the working directory, or `course_root` in the Python API.
+
+The same orchestration is available to Python callers:
+
+```python
+from prairielearn_e2e import run_parallel
+
+status = run_parallel(
+    ["--question-path", "questions", "--fuzz-seeds"],
+    command="run",
+    shard_count=6,
+    course_root="/path/to/course",
+    junitxml="results.xml",
+)
+```
+
+`run_parallel` returns an integer exit status, including 130 on interruption.
+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
+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)
+
+test-e2e-fuzz-sharded:
+	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" diff -- \
+		--base "$(E2E_DIFF_BASE)" --head "$(E2E_DIFF_HEAD)" \
+		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) $(PYTEST_ARGS)
+```
+
 ### CI sharding
 
 Use `--shard INDEX/COUNT` to divide the selected question variants between parallel

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/README.md

@@ -11,6 +11,7 @@ The package installs the reusable `prairielearn_e2e` Python API and a single
 - `pl-e2e-test` (no command, or any pytest/harness options) 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 add-seed` records a failing concrete variant seed.
 - `pl-e2e-test reports` merges parallel shard results into terminal and JUnit reports.
 - `pl-e2e-test version` prints the installed version.
@@ -73,6 +74,68 @@ uv run pl-e2e-test \
 variant set with `--fuzz-seed N`. Without either option, deterministic seeds start at
 zero. Question metadata with `singleVariant: true` always uses seed zero.
 
+### Local parallel runs
+
+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 -- \
+  --question-path questions --fuzz-seeds
+
+uv run pl-e2e-test parallel --shard-count 6 --junitxml results.xml diff -- \
+  --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
+`--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.
+Interrupting the launcher stops and reaps its children.
+
+Intermediate reports are temporary. Pass the launcher's `--junitxml` option to retain
+merged JUnit output. Forwarded `--shard`, `--shard-report`, `--junitxml`, and
+`--junit-xml` options are rejected because the launcher manages those outputs.
+Choose the course with the working directory, or `course_root` in the Python API.
+
+The same orchestration is available to Python callers:
+
+```python
+from prairielearn_e2e import run_parallel
+
+status = run_parallel(
+    ["--question-path", "questions", "--fuzz-seeds"],
+    command="run",
+    shard_count=6,
+    course_root="/path/to/course",
+    junitxml="results.xml",
+)
+```
+
+`run_parallel` returns an integer exit status, including 130 on interruption.
+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
+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)
+
+test-e2e-fuzz-sharded:
+	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" diff -- \
+		--base "$(E2E_DIFF_BASE)" --head "$(E2E_DIFF_HEAD)" \
+		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) $(PYTEST_ARGS)
+```
+
 ### CI sharding
 
 Use `--shard INDEX/COUNT` to divide the selected question variants between parallel

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pl-e2e-test"
-version = "0.1.2"
+version = "0.1.3"
 description = "Fuzz PrairieLearn question lifecycles against the real Python element runtime"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -19,6 +19,7 @@ dependencies = [
   "prairielearn",
   "pyright>=1.1.414",
   "pytest>=9.1",
+  "rich>=14",
   "ruff>=0.16",
 ]
 

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3/src/pl_e2e_test.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pl-e2e-test
-Version: 0.1.2
+Version: 0.1.3
 Summary: Fuzz PrairieLearn question lifecycles against the real Python element runtime
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/PrairieLearn/pl-e2e-test
@@ -18,6 +18,7 @@ Requires-Dist: platformdirs>=4.5
 Requires-Dist: prairielearn
 Requires-Dist: pyright>=1.1.414
 Requires-Dist: pytest>=9.1
+Requires-Dist: rich>=14
 Requires-Dist: ruff>=0.16
 Dynamic: license-file
 
@@ -34,6 +35,7 @@ The package installs the reusable `prairielearn_e2e` Python API and a single
 - `pl-e2e-test` (no command, or any pytest/harness options) 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 add-seed` records a failing concrete variant seed.
 - `pl-e2e-test reports` merges parallel shard results into terminal and JUnit reports.
 - `pl-e2e-test version` prints the installed version.
@@ -96,6 +98,68 @@ uv run pl-e2e-test \
 variant set with `--fuzz-seed N`. Without either option, deterministic seeds start at
 zero. Question metadata with `singleVariant: true` always uses seed zero.
 
+### Local parallel runs
+
+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 -- \
+  --question-path questions --fuzz-seeds
+
+uv run pl-e2e-test parallel --shard-count 6 --junitxml results.xml diff -- \
+  --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
+`--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.
+Interrupting the launcher stops and reaps its children.
+
+Intermediate reports are temporary. Pass the launcher's `--junitxml` option to retain
+merged JUnit output. Forwarded `--shard`, `--shard-report`, `--junitxml`, and
+`--junit-xml` options are rejected because the launcher manages those outputs.
+Choose the course with the working directory, or `course_root` in the Python API.
+
+The same orchestration is available to Python callers:
+
+```python
+from prairielearn_e2e import run_parallel
+
+status = run_parallel(
+    ["--question-path", "questions", "--fuzz-seeds"],
+    command="run",
+    shard_count=6,
+    course_root="/path/to/course",
+    junitxml="results.xml",
+)
+```
+
+`run_parallel` returns an integer exit status, including 130 on interruption.
+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
+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)
+
+test-e2e-fuzz-sharded:
+	uv run --active pl-e2e-test parallel --shard-count "$(E2E_SHARD_COUNT)" diff -- \
+		--base "$(E2E_DIFF_BASE)" --head "$(E2E_DIFF_HEAD)" \
+		--seed-count "$(E2E_FUZZ_SEED_COUNT)" $(E2E_FUZZ_SEED_ARG) $(E2E_PRAIRIELEARN_ARG) $(PYTEST_ARGS)
+```
+
 ### CI sharding
 
 Use `--shard INDEX/COUNT` to divide the selected question variants between parallel

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/src/pl_e2e_test.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/prairielearn_e2e/fuzz.py
 src/prairielearn_e2e/harness.py
 src/prairielearn_e2e/html_checks.py
 src/prairielearn_e2e/metadata.py
+src/prairielearn_e2e/parallel.py
 src/prairielearn_e2e/pytest_plugin.py
 src/prairielearn_e2e/question_tests.py
 src/prairielearn_e2e/regression.py
@@ -41,6 +42,7 @@ tests/test_git.py
 tests/test_harness.py
 tests/test_html_checks.py
 tests/test_metadata.py
+tests/test_parallel.py
 tests/test_publish_version.py
 tests/test_pytest_plugin.py
 tests/test_regression.py

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/src/pl_e2e_test.egg-info/requires.txt

@@ -7,4 +7,5 @@ platformdirs>=4.5
 prairielearn
 pyright>=1.1.414
 pytest>=9.1
+rich>=14
 ruff>=0.16

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/src/prairielearn_e2e/__init__.py

@@ -5,6 +5,7 @@ from importlib.metadata import version
 from .backend import PrairieLearnBackend
 from .discovery import QuestionCase, discover_questions
 from .harness import LifecycleResult, QuestionHarness
+from .parallel import run_parallel
 
 __version__ = version("pl-e2e-test")
 
@@ -15,4 +16,5 @@ __all__ = (
     "QuestionHarness",
     "__version__",
     "discover_questions",
+    "run_parallel",
 )

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/src/prairielearn_e2e/cli.py

@@ -6,10 +6,11 @@ import sys
 from collections.abc import Sequence
 from importlib.metadata import version
 
-from . import fuzz, regression, reporting, runner
+from . import fuzz, parallel, regression, reporting, runner
 
 _SUBCOMMANDS = {
     "diff": fuzz.main,
+    "parallel": parallel.main,
     "add-seed": regression.main,
     "reports": reporting.main,
 }
@@ -22,6 +23,7 @@ suite; any arguments (pytest options, --question-path, --seed-count, ...)
 are passed straight through to pytest.
 
 Commands:
+  parallel    run local shards and merge their results
   diff        fuzz questions changed between two Git refs
   add-seed    record a concrete regression seed for a question
   reports     merge parallel shard reports into one terminal/JUnit report

pl_e2e_test-0.1.3/src/prairielearn_e2e/parallel.py

@@ -0,0 +1,250 @@
+"""Run local shards in isolated processes and merge their results."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import shlex
+import subprocess
+import sys
+import time
+from collections.abc import Sequence
+from contextlib import ExitStack
+from dataclasses import dataclass
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import IO
+
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
+from rich.text import Text
+
+from .reporting import ReportError, merge_reports
+
+
+@dataclass
+class _Child:
+    index: int
+    report: Path
+    stdout: IO[str]
+    stderr: IO[str]
+    process: subprocess.Popen[str] | None = None
+    returncode: int | None = None
+    error: str = ""
+
+
+def _arguments(arguments: Sequence[str], command: str) -> tuple[list[str], int | None]:
+    arguments = list(arguments)
+    for argument in arguments:
+        option = argument.split("=", 1)[0]
+        if option in {"--shard", "--shard-report", "--junitxml", "--junit-xml"}:
+            raise ValueError(f"{option} is managed by the parallel launcher")
+        if option == "--course-root":
+            raise ValueError(
+                "use course_root or the working directory to select a course"
+            )
+    parser = argparse.ArgumentParser(
+        add_help=False, allow_abbrev=False, exit_on_error=False
+    )
+    parser.add_argument("--fuzz-seed", type=int)
+    parser.add_argument("--fuzz-seeds", action="store_true")
+    # Parse only the seed options; preserve all forwarded tokens and their order.
+    try:
+        args, _ = parser.parse_known_args(arguments)
+    except argparse.ArgumentError as exc:
+        raise ValueError(str(exc)) from exc
+    seed = args.fuzz_seed
+    if seed is None and (command == "diff" or args.fuzz_seeds):
+        seed = secrets.randbits(64)
+        arguments.extend(("--fuzz-seed", str(seed)))
+    return arguments, seed
+
+
+def _stop(children: Sequence[_Child]) -> None:
+    running = [child.process for child in children if child.process is not None]
+    for process in running:
+        if process.poll() is None:
+            process.terminate()
+    deadline = time.monotonic() + 3
+    for process in running:
+        try:
+            process.wait(timeout=max(0, deadline - time.monotonic()))
+        except subprocess.TimeoutExpired:
+            process.kill()
+            process.wait()
+
+
+def run_parallel(
+    arguments: Sequence[str],
+    *,
+    command: str = "run",
+    shard_count: int = 6,
+    course_root: str | Path | None = None,
+    junitxml: str | Path | None = None,
+) -> int:
+    """Run and merge local shards; return a CLI status (130 on interruption).
+
+    Invalid launcher options raise ValueError. Relative JUnit paths are resolved
+    against course_root. Child output is captured on disk until all shards finish.
+    """
+    if command not in {"run", "diff"}:
+        raise ValueError("command must be run or diff")
+    if (
+        isinstance(shard_count, bool)
+        or not isinstance(shard_count, int)
+        or shard_count < 1
+    ):
+        raise ValueError("shard_count must be a positive integer")
+    forwarded, seed = _arguments(arguments, command)
+    root = Path(course_root or Path.cwd()).resolve()
+    console = Console()
+    invocation = [sys.executable, "-m", "prairielearn_e2e"]
+    if command == "diff":
+        invocation.append("diff")
+    invocation.extend(forwarded)
+    if seed is not None:
+        console.print(f"E2E fuzz seed: {seed}", markup=False)
+    console.print(
+        f"Replay without sharding: {shlex.join(invocation)}",
+        markup=False,
+        soft_wrap=True,
+    )
+    console.print(f"Running {shard_count} shards in parallel", markup=False)
+
+    with TemporaryDirectory(prefix="pl-e2e-shards-") as temporary, ExitStack() as stack:
+        directory = Path(temporary)
+        children: list[_Child] = []
+        progress = Progress(
+            SpinnerColumn(),
+            TextColumn("{task.description}"),
+            TimeElapsedColumn(),
+            console=console,
+            disable=not console.is_terminal,
+        )
+        with progress:
+            try:
+                tasks = {}
+                for index in range(1, shard_count + 1):
+                    child = _Child(
+                        index,
+                        directory / f"shard-{index}.pl-e2e-report.json",
+                        stack.enter_context(
+                            (directory / f"{index}.stdout").open(
+                                "w+", encoding="utf-8", errors="replace"
+                            )
+                        ),
+                        stack.enter_context(
+                            (directory / f"{index}.stderr").open(
+                                "w+", encoding="utf-8", errors="replace"
+                            )
+                        ),
+                    )
+                    children.append(child)
+                    tasks[index] = progress.add_task(
+                        f"Shard {index}/{shard_count}: running", total=None
+                    )
+                    try:
+                        child.process = subprocess.Popen(
+                            [
+                                *invocation,
+                                "--shard",
+                                f"{index}/{shard_count}",
+                                "--shard-report",
+                                os.fspath(child.report),
+                            ],
+                            cwd=root,
+                            stdout=child.stdout,
+                            stderr=child.stderr,
+                            text=True,
+                        )
+                    except OSError as exc:
+                        child.returncode, child.error = 127, str(exc)
+                pending = list(children)
+                while pending:
+                    for child in pending[:]:
+                        if child.process is not None:
+                            child.returncode = child.process.poll()
+                        if child.returncode is None:
+                            continue
+                        status = (
+                            "passed"
+                            if child.returncode == 0
+                            else f"failed ({child.returncode})"
+                        )
+                        label = f"Shard {child.index}/{shard_count}: {status}"
+                        progress.update(
+                            tasks[child.index], description=label, total=1, completed=1
+                        )
+                        if not console.is_terminal:
+                            console.print(label, markup=False)
+                        pending.remove(child)
+                    if pending:
+                        time.sleep(0.05)
+            except KeyboardInterrupt:
+                console.print("Interrupted; stopping shards.", markup=False)
+                return 130
+            finally:
+                _stop(children)
+
+        for child in children:
+            failed = child.returncode != 0 or not child.report.is_file()
+            child.stdout.seek(0)
+            child.stderr.seek(0)
+            stderr = child.stderr.read()
+            if failed or stderr:
+                console.rule(f"Shard {child.index}: {'failed' if failed else 'notes'}")
+                if child.error:
+                    console.print(child.error, markup=False)
+                if failed:
+                    console.print(Text.from_ansi(child.stdout.read().rstrip()))
+                if stderr:
+                    console.print(Text.from_ansi(stderr.rstrip()))
+        output = (
+            directory / "results.xml" if junitxml is None else root / Path(junitxml)
+        )
+        try:
+            status = merge_reports([child.report for child in children], output)
+        except (OSError, ReportError) as exc:
+            console.print(f"Unable to merge shard reports: {exc}", markup=False)
+            return 2
+        if status:
+            return status
+        return next(
+            (
+                child.returncode if child.returncode > 0 else 128 - child.returncode
+                for child in children
+                if child.returncode
+            ),
+            0,
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pl-e2e-test parallel", description=__doc__, allow_abbrev=False
+    )
+    parser.add_argument(
+        "--shard-count",
+        type=int,
+        default=6,
+        help="number of concurrent shards (default: 6)",
+    )
+    parser.add_argument(
+        "--junitxml", type=Path, help="retain merged JUnit output at this path"
+    )
+    parser.add_argument("command", choices=("run", "diff"))
+    parser.add_argument(
+        "arguments", nargs=argparse.REMAINDER, help="arguments to forward after --"
+    )
+    args = parser.parse_args(argv)
+    arguments = args.arguments[1:] if args.arguments[:1] == ["--"] else args.arguments
+    try:
+        return run_parallel(
+            arguments,
+            command=args.command,
+            shard_count=args.shard_count,
+            junitxml=args.junitxml,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))

{pl_e2e_test-0.1.2 → pl_e2e_test-0.1.3}/tests/test_cli.py

@@ -16,7 +16,7 @@ def _stub(calls: list[Sequence[str]], result: int = 0):
     return _main
 
 
-@pytest.mark.parametrize("command", ["diff", "add-seed", "reports"])
+@pytest.mark.parametrize("command", ["diff", "add-seed", "reports", "parallel"])
 def test_dispatches_known_commands_to_their_module(
     monkeypatch: pytest.MonkeyPatch, command: str
 ) -> None:
@@ -60,7 +60,7 @@ def test_help_command_with_no_argument_prints_top_level_help(
     assert cli.main(["help"]) == 0
     out = capsys.readouterr().out
     assert "Commands:" in out
-    for command in ("diff", "add-seed", "reports", "version", "help"):
+    for command in ("diff", "add-seed", "reports", "parallel", "version", "help"):
         assert command in out
 
 

pl_e2e_test-0.1.3/tests/test_parallel.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+import io
+import json
+import os
+import shlex
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, cast
+
+import pytest
+from rich.console import Console
+
+from prairielearn_e2e import parallel, run_parallel
+from prairielearn_e2e.reporting import write_empty_shard_report
+from prairielearn_e2e.sharding import parse_shard
+
+
+@pytest.mark.parametrize(
+    ("command", "arguments", "expected"),
+    [
+        ("run", [], None),
+        ("run", ["--fuzz-seeds"], 123),
+        ("diff", [], 123),
+        ("run", ["--fuzz-seed=42"], 42),
+        ("diff", ["--fuzz-seed", "0"], 0),
+    ],
+)
+def test_seed_policy(
+    monkeypatch: pytest.MonkeyPatch,
+    command: str,
+    arguments: list[str],
+    expected: int | None,
+) -> None:
+    monkeypatch.setattr(parallel.secrets, "randbits", lambda _: 123)
+    forwarded, seed = parallel._arguments(arguments, command)
+    assert seed == expected
+    assert forwarded[: len(arguments)] == arguments
+    if expected == 123:
+        assert forwarded[-2:] == ["--fuzz-seed", "123"]
+    else:
+        assert forwarded == arguments
+
+
+@pytest.mark.parametrize(
+    "argument",
+    [
+        "--shard",
+        "--shard=1/2",
+        "--shard-report=x",
+        "--junitxml=x",
+        "--junit-xml",
+        "--course-root=x",
+    ],
+)
+def test_rejects_owned_options(argument: str) -> None:
+    with pytest.raises(ValueError):
+        run_parallel([argument])
+
+
+@pytest.mark.parametrize("count", [0, -1, True])
+def test_invalid_count(count: int) -> None:
+    with pytest.raises(ValueError, match="positive integer"):
+        run_parallel([], shard_count=count)
+
+
+class FinishedProcess:
+    def __init__(self, status: int):
+        self.status = status
+
+    def poll(self) -> int:
+        return self.status
+
+    def wait(self, timeout: float | None = None) -> int:
+        return self.status
+
+
+@pytest.mark.parametrize("terminal", [False, True])
+@pytest.mark.parametrize("failure", ["none", "missing", "corrupt", "launch", "exit"])
+def test_orchestration_and_diagnostics(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, terminal: bool, failure: str
+) -> None:
+    output = io.StringIO()
+    monkeypatch.setattr(
+        parallel,
+        "Console",
+        lambda: Console(file=output, force_terminal=terminal, width=120),
+    )
+    commands: list[list[str]] = []
+    reports: list[Path] = []
+
+    def popen(command: list[str], **kwargs: Any) -> FinishedProcess:
+        commands.append(command)
+        assert kwargs["cwd"] == tmp_path
+        assert command[:3] == [sys.executable, "-m", "prairielearn_e2e"]
+        assert command[3:8] == [
+            "--question-path",
+            "questions with spaces",
+            "-m",
+            "render",
+            "--fuzz-seeds",
+        ]
+        shard = parse_shard(command[command.index("--shard") + 1])
+        report = Path(command[command.index("--shard-report") + 1])
+        reports.append(report)
+        kwargs["stdout"].write(
+            "hidden success output" if shard.index != 1 else "failure details"
+        )
+        kwargs["stdout"].flush()
+        kwargs["stderr"].write("a warning\n")
+        kwargs["stderr"].flush()
+        if shard.index == 1 and failure == "launch":
+            raise OSError("cannot start child")
+        if shard.index != 1 or failure not in {"missing", "corrupt"}:
+            write_empty_shard_report(report, shard, fuzz_seed=42)
+        elif failure == "corrupt":
+            report.write_text("invalid json")
+        return FinishedProcess(7 if failure == "exit" and shard.index == 1 else 0)
+
+    monkeypatch.setattr(parallel.subprocess, "Popen", popen)
+    result = run_parallel(
+        [
+            "--question-path",
+            "questions with spaces",
+            "-m",
+            "render",
+            "--fuzz-seeds",
+            "--fuzz-seed=42",
+        ],
+        shard_count=3,
+        course_root=tmp_path,
+        junitxml="combined.xml",
+    )
+    assert (
+        result
+        == {"none": 0, "missing": 2, "corrupt": 2, "launch": 2, "exit": 7}[failure]
+    )
+    assert len(commands) == 3
+    assert all(not path.exists() for path in reports)
+    assert "a warning" in output.getvalue()
+    assert "hidden success output" not in output.getvalue()
+    assert "Shard 3/3: passed" in output.getvalue()
+    if failure in {"none", "exit"}:
+        assert (tmp_path / "combined.xml").is_file()
+    if failure == "launch":
+        assert "cannot start child" in output.getvalue()
+    if failure == "exit":
+        assert "failure details" in output.getvalue()
+
+
+def test_cli_forwards_arguments(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls: list[tuple[Sequence[str], dict[str, Any]]] = []
+
+    def run(arguments: Sequence[str], **kwargs: Any) -> int:
+        calls.append((arguments, kwargs))
+        return 3
+
+    monkeypatch.setattr(parallel, "run_parallel", run)
+    assert (
+        parallel.main(
+            [
+                "--shard-count",
+                "2",
+                "--junitxml",
+                "out.xml",
+                "diff",
+                "--",
+                "--base",
+                "main",
+                "--fuzz-seed",
+                "4",
+            ]
+        )
+        == 3
+    )
+    assert calls == [
+        (
+            ["--base", "main", "--fuzz-seed", "4"],
+            {"command": "diff", "shard_count": 2, "junitxml": Path("out.xml")},
+        )
+    ]
+
+
+def test_real_processes_overlap_and_cleanup_on_interrupt(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    original_popen = subprocess.Popen
+    processes: list[subprocess.Popen[str]] = []
+    reports: list[Path] = []
+    # Each child must observe both processes alive before it finishes. Serial
+    # execution times out and fails, without relying on a timing speedup assertion.
+    script = """
+import pathlib, sys, time
+root = pathlib.Path(sys.argv[1])
+(root / sys.argv[2]).touch()
+deadline = time.monotonic() + 10
+while len(list(root.glob('ready-*'))) != 2:
+    if time.monotonic() > deadline:
+        raise SystemExit(9)
+    time.sleep(.01)
+time.sleep(30)
+"""
+
+    def popen(command: list[str], **kwargs: Any) -> subprocess.Popen[str]:
+        reports.append(Path(command[command.index("--shard-report") + 1]))
+        process = original_popen(
+            [sys.executable, "-c", script, str(tmp_path), f"ready-{len(processes)}"],
+            **kwargs,
+        )
+        processes.append(process)
+        return process
+
+    original_sleep = parallel.time.sleep
+
+    interrupted = False
+
+    def interrupt_when_ready(seconds: float) -> None:
+        nonlocal interrupted
+        if not interrupted and len(list(tmp_path.glob("ready-*"))) == 2:
+            interrupted = True
+            assert all(process.poll() is None for process in processes)
+            raise KeyboardInterrupt
+        original_sleep(seconds)
+
+    monkeypatch.setattr(parallel.subprocess, "Popen", popen)
+    monkeypatch.setattr(parallel.time, "sleep", interrupt_when_ready)
+    assert run_parallel([], shard_count=2, course_root=tmp_path) == 130
+    assert len(processes) == 2
+    assert all(process.poll() is not None for process in processes)
+    assert all(not path.parent.exists() for path in reports)
+
+
+def test_real_shards_match_serial_replay(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("PYTEST_DISABLE_PLUGIN_AUTOLOAD", "1")
+    # Skip each phase before backend initialization: this exercises real discovery,
+    # seed generation, collection, execution and merging without network access.
+    question = tmp_path / "questions" / "example"
+    question.mkdir(parents=True)
+    (question / "info.json").write_text(json.dumps({"uuid": "test", "type": "v3"}))
+    (question / ".question-e2e.json").write_text(
+        json.dumps(
+            {
+                "skip_methods": {
+                    phase: "fixture"
+                    for phase in ("generate", "prepare", "render", "grade")
+                }
+            }
+        )
+    )
+    arguments = [
+        "--question-path",
+        "questions",
+        "--seed-count",
+        "2",
+        "--fuzz-seeds",
+        "--fuzz-seed",
+        "42",
+    ]
+    assert (
+        run_parallel(
+            arguments, shard_count=3, course_root=tmp_path, junitxml="parallel.xml"
+        )
+        == 0
+    )
+    output = capsys.readouterr().out
+    replay = next(
+        line.removeprefix("Replay without sharding: ")
+        for line in output.splitlines()
+        if line.startswith("Replay without sharding: ")
+    )
+    assert shlex.split(replay) == [sys.executable, "-m", "prairielearn_e2e", *arguments]
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "prairielearn_e2e",
+            *arguments,
+            "--junitxml",
+            str(tmp_path / "serial.xml"),
+        ],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
+
+    def cases(path: Path) -> list[str]:
+        return sorted(
+            case.attrib["name"].split("::")[-1]
+            for case in ET.parse(path).iter("testcase")
+        )
+
+    assert cases(tmp_path / "parallel.xml") == cases(tmp_path / "serial.xml")
+    assert len(cases(tmp_path / "parallel.xml")) == 8
+
+
+def test_real_no_change_diff(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("PYTEST_DISABLE_PLUGIN_AUTOLOAD", "1")
+    for arguments in [
+        ["init", "-q"],
+        [
+            "-c",
+            "user.name=Test",
+            "-c",
+            "user.email=test@example.com",
+            "commit",
+            "--allow-empty",
+            "-qm",
+            "initial",
+        ],
+    ]:
+        subprocess.run(
+            ["git", *arguments],
+            cwd=tmp_path,
+            check=True,
+            env={**os.environ, "GIT_CONFIG_NOSYSTEM": "1"},
+        )
+    assert (
+        run_parallel(
+            ["--base", "HEAD"],
+            command="diff",
+            shard_count=2,
+            course_root=tmp_path,
+            junitxml="diff.xml",
+        )
+        == 0
+    )
+    assert list(ET.parse(tmp_path / "diff.xml").iter("testcase")) == []
+
+
+def test_default_six_shards_and_merge_failure_precedence(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    commands: list[list[str]] = []
+    outputs: list[Path] = []
+
+    def popen(command: list[str], **kwargs: Any) -> FinishedProcess:
+        commands.append(command)
+        report = Path(command[command.index("--shard-report") + 1])
+        write_empty_shard_report(
+            report, parse_shard(command[command.index("--shard") + 1])
+        )
+        return FinishedProcess(7)
+
+    def merge(inputs: Sequence[Path], output: Path) -> int:
+        assert len(commands) == len(inputs) == 6
+        assert all(path.is_file() for path in inputs)
+        outputs.append(output)
+        output.write_text("merged")
+        return 1
+
+    monkeypatch.setattr(parallel.subprocess, "Popen", popen)
+    monkeypatch.setattr(parallel, "merge_reports", merge)
+    assert run_parallel([], course_root=tmp_path) == 1
+    assert all(not path.exists() for path in outputs)
+
+
+def test_force_kills_child_that_ignores_termination() -> None:
+    class StubbornProcess:
+        terminated = False
+        killed = False
+        reaped = False
+
+        def poll(self) -> None:
+            return None
+
+        def terminate(self) -> None:
+            self.terminated = True
+
+        def kill(self) -> None:
+            self.killed = True
+
+        def wait(self, timeout: float | None = None) -> int:
+            if not self.killed:
+                raise subprocess.TimeoutExpired("child", timeout or 0)
+            self.reaped = True
+            return -9
+
+    process = StubbornProcess()
+    child = parallel._Child(
+        1,
+        Path("unused"),
+        io.StringIO(),
+        io.StringIO(),
+        process=cast(subprocess.Popen[str], process),
+    )
+    parallel._stop([child])
+    assert process.terminated and process.killed and process.reaped
+
+
+@pytest.mark.parametrize("arguments", [["--fuzz-seed"], ["--fuzz-seed=bad"]])
+def test_invalid_seed_is_api_value_error(arguments: list[str]) -> None:
+    with pytest.raises(ValueError):
+        run_parallel(arguments)