claude-dev-env 4.2.0 → 4.3.0

package/.agents/skills/test-runner/scripts/run_tests.py

@@ -0,0 +1,316 @@
+#!/usr/bin/env python3
+"""Run pytest or Playwright after Django and Playwright readiness checks.
+
+::
+
+    python run_tests.py -- python -m pytest tests/
+    python run_tests.py -- npx playwright test tests/account.spec.ts
+
+The selected child receives its arguments unchanged, inherits this process's
+environment and output streams, and runs from the selected project directory.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NoReturn
+
+import preflight_checks
+from test_runner_constants.config.constants import (
+    ALL_EXECUTABLE_SUFFIXES,
+    ALL_URL_TRAILING_PUNCTUATION,
+    ARGUMENT_ASSIGNMENT_SEPARATOR,
+    BASE_URL_FLAG,
+    COMMAND_SEPARATOR,
+    DEFAULT_DJANGO_URL,
+    DEFAULT_PLAYWRIGHT_URL,
+    ERROR_CHILD_COMMAND_REQUIRED,
+    ERROR_CHILD_LAUNCH_TEMPLATE,
+    ERROR_COMMAND_SEPARATOR_REQUIRED,
+    ERROR_PREFLIGHT_FAILURE_TEMPLATE,
+    ERROR_PROJECT_NOT_DIRECTORY_TEMPLATE,
+    ERROR_UNSUPPORTED_RUNNER,
+    EXIT_CODE_FAILURE,
+    EXIT_CODE_INVALID_ARGUMENTS,
+    MANAGE_PY_FILENAME,
+    MINIMUM_NPX_ARGUMENT_COUNT,
+    MINIMUM_PLAYWRIGHT_ARGUMENT_COUNT,
+    NPX_EXECUTABLE_NAME,
+    PLAYWRIGHT_EXECUTABLE_NAME,
+    PLAYWRIGHT_RUNNER_NAME,
+    PLAYWRIGHT_TEST_COMMAND_INDEX,
+    PLAYWRIGHT_TEST_SUBCOMMAND,
+    PROJECT_FLAG,
+    PWD_ENVIRONMENT_NAME,
+    PYTEST_EXECUTABLE_PREFIX,
+    PYTEST_RUNNER_NAME,
+    PYTHON_EXECUTABLE_PREFIX,
+    PYTHON_MODULE_FLAG,
+    SERVER_URL_PATTERN,
+)
+
+build_frontend = preflight_checks.build_frontend
+check_django_database = preflight_checks.check_django_database
+check_runserver_port_conflicts = preflight_checks.check_runserver_port_conflicts
+check_server_health = preflight_checks.check_server_health
+check_test_db_flag = preflight_checks.check_test_db_flag
+
+
+@dataclass(frozen=True)
+class SelectedRunner:
+    """The supported runner selected from the child arguments."""
+
+    name: str
+    is_playwright: bool
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        raise ValueError(message)
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = _ArgumentParser(add_help=True)
+    parser.add_argument(PROJECT_FLAG, type=Path, default=None)
+    return parser
+
+
+def _split_command_arguments(
+    all_arguments: Sequence[str],
+) -> tuple[list[str], list[str]]:
+    all_arguments_as_list = list(all_arguments)
+    if COMMAND_SEPARATOR not in all_arguments_as_list:
+        raise ValueError(ERROR_COMMAND_SEPARATOR_REQUIRED)
+    separator_index = all_arguments_as_list.index(COMMAND_SEPARATOR)
+    launcher_arguments = all_arguments_as_list[:separator_index]
+    child_arguments = all_arguments_as_list[separator_index + 1 :]
+    if not child_arguments:
+        raise ValueError(ERROR_CHILD_COMMAND_REQUIRED)
+    return launcher_arguments, child_arguments
+
+
+def _resolve_project_root(maybe_project_path: Path | None) -> Path:
+    selected_path = maybe_project_path or Path(
+        os.environ.get(PWD_ENVIRONMENT_NAME, os.getcwd())
+    )
+    resolved_path = selected_path.expanduser().resolve()
+    if not resolved_path.is_dir():
+        raise ValueError(ERROR_PROJECT_NOT_DIRECTORY_TEMPLATE.format(resolved_path))
+    return resolved_path
+
+
+def _parse_command_arguments(
+    all_arguments: Sequence[str],
+) -> tuple[Path, list[str]]:
+    launcher_arguments, child_arguments = _split_command_arguments(all_arguments)
+    parsed_arguments = _build_argument_parser().parse_args(launcher_arguments)
+    project_root = _resolve_project_root(parsed_arguments.project)
+    return project_root, child_arguments
+
+
+def _basename_without_suffix(executable_path: str) -> str:
+    executable_name = Path(executable_path).name.casefold()
+    for each_suffix in ALL_EXECUTABLE_SUFFIXES:
+        if executable_name.endswith(each_suffix):
+            return executable_name.removesuffix(each_suffix)
+    return executable_name
+
+
+def _is_python_module_runner(
+    all_child_arguments: Sequence[str],
+) -> bool:
+    executable_name = _basename_without_suffix(all_child_arguments[0])
+    if not executable_name.startswith(PYTHON_EXECUTABLE_PREFIX):
+        return False
+    for each_index, each_argument in enumerate(all_child_arguments[1:], start=1):
+        if each_argument != PYTHON_MODULE_FLAG:
+            continue
+        return (
+            each_index + 1 < len(all_child_arguments)
+            and all_child_arguments[each_index + 1] == PYTEST_RUNNER_NAME
+        )
+    return False
+
+
+def _is_pytest_executable(executable_path: str) -> bool:
+    return _basename_without_suffix(executable_path).startswith(
+        PYTEST_EXECUTABLE_PREFIX
+    )
+
+
+def _is_playwright_executable(
+    all_child_arguments: Sequence[str],
+) -> bool:
+    executable_name = _basename_without_suffix(all_child_arguments[0])
+    if executable_name == PLAYWRIGHT_EXECUTABLE_NAME:
+        return (
+            len(all_child_arguments) >= MINIMUM_PLAYWRIGHT_ARGUMENT_COUNT
+            and all_child_arguments[1] == PLAYWRIGHT_TEST_SUBCOMMAND
+        )
+    return (
+        executable_name == NPX_EXECUTABLE_NAME
+        and len(all_child_arguments) >= MINIMUM_NPX_ARGUMENT_COUNT
+        and all_child_arguments[1] == PLAYWRIGHT_EXECUTABLE_NAME
+        and all_child_arguments[PLAYWRIGHT_TEST_COMMAND_INDEX]
+        == PLAYWRIGHT_TEST_SUBCOMMAND
+    )
+
+
+def select_runner(all_child_arguments: Sequence[str]) -> SelectedRunner:
+    """Select one supported runner from the child arguments.
+
+    Args:
+        all_child_arguments: Child executable and its arguments.
+
+    Returns:
+        The selected runner classification.
+
+    Raises:
+        ValueError: The child arguments are empty or unsupported.
+    """
+    if not all_child_arguments:
+        raise ValueError(ERROR_CHILD_COMMAND_REQUIRED)
+    if _is_playwright_executable(all_child_arguments):
+        return SelectedRunner(PLAYWRIGHT_RUNNER_NAME, True)
+    if _is_pytest_executable(all_child_arguments[0]) or _is_python_module_runner(
+        all_child_arguments
+    ):
+        return SelectedRunner(PYTEST_RUNNER_NAME, False)
+    raise ValueError(ERROR_UNSUPPORTED_RUNNER)
+
+
+def extract_target_url(
+    all_child_arguments: Sequence[str],
+    is_playwright: bool,
+) -> str:
+    """Return a URL from the child arguments, or the runner default.
+
+    Args:
+        all_child_arguments: Child executable and its arguments.
+        is_playwright: Whether to use the Playwright default URL.
+
+    Returns:
+        A URL from the child arguments, or the runner default.
+    """
+    for each_index, each_argument in enumerate(all_child_arguments):
+        if each_argument == BASE_URL_FLAG and each_index + 1 < len(all_child_arguments):
+            return all_child_arguments[each_index + 1].rstrip(
+                ALL_URL_TRAILING_PUNCTUATION
+            )
+        if each_argument.startswith(f"{BASE_URL_FLAG}{ARGUMENT_ASSIGNMENT_SEPARATOR}"):
+            return each_argument.split(ARGUMENT_ASSIGNMENT_SEPARATOR, 1)[1].rstrip(
+                ALL_URL_TRAILING_PUNCTUATION
+            )
+        url_match = SERVER_URL_PATTERN.search(each_argument)
+        if url_match:
+            return url_match.group(0).rstrip(ALL_URL_TRAILING_PUNCTUATION)
+    return DEFAULT_PLAYWRIGHT_URL if is_playwright else DEFAULT_DJANGO_URL
+
+
+def _run_django_preflight(project_root: Path, target_url: str) -> str | None:
+    database_error = check_django_database(project_root)
+    if database_error:
+        return database_error
+    return check_server_health(target_url)
+
+
+def _run_playwright_preflight(
+    project_root: Path,
+    target_url: str,
+) -> str | None:
+    conflict_error = check_runserver_port_conflicts(target_url, project_root)
+    if conflict_error:
+        return conflict_error
+    test_database_error = check_test_db_flag(target_url, project_root)
+    if test_database_error:
+        return test_database_error
+    return build_frontend(project_root) or check_server_health(target_url)
+
+
+def run_preflight(
+    selected_runner: SelectedRunner,
+    project_root: Path,
+    all_child_arguments: Sequence[str],
+) -> str | None:
+    """Run checks required by the selected runner before child launch.
+
+    Args:
+        selected_runner: Runner selected from child arguments.
+        project_root: Directory used for project checks.
+        all_child_arguments: Complete child arguments used for URL selection.
+
+    Returns:
+        A blocking diagnostic when a readiness check fails, otherwise None.
+    """
+    is_django_project = (project_root / MANAGE_PY_FILENAME).is_file()
+    if not selected_runner.is_playwright and not is_django_project:
+        return None
+    target_url = extract_target_url(all_child_arguments, selected_runner.is_playwright)
+    if is_django_project and not selected_runner.is_playwright:
+        return _run_django_preflight(project_root, target_url)
+    if selected_runner.is_playwright:
+        return _run_playwright_preflight(project_root, target_url)
+    return check_server_health(target_url)
+
+
+def run_child_process(
+    all_child_arguments: Sequence[str],
+    project_root: Path,
+) -> int:
+    """Run the child with inherited streams and environment.
+
+    Args:
+        all_child_arguments: Child executable and its arguments.
+        project_root: Working directory for the child.
+
+    Returns:
+        The child's exit status, or one when the child cannot start.
+    """
+    try:
+        completed_process = subprocess.run(
+            list(all_child_arguments),
+            cwd=project_root,
+            check=False,
+        )
+    except OSError as error:
+        print(ERROR_CHILD_LAUNCH_TEMPLATE.format(error), file=sys.stderr)
+        return EXIT_CODE_FAILURE
+    return completed_process.returncode
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Validate arguments, run preflight, then launch the child.
+
+    Args:
+        all_arguments: Command arguments without the executable name.
+
+    Returns:
+        A validation or child exit status.
+    """
+    try:
+        project_root, all_child_arguments = _parse_command_arguments(all_arguments)
+        selected_runner = select_runner(all_child_arguments)
+    except ValueError as error:
+        print(str(error), file=sys.stderr)
+        return EXIT_CODE_INVALID_ARGUMENTS
+    try:
+        preflight_error = run_preflight(
+            selected_runner, project_root, all_child_arguments
+        )
+    except (OSError, ValueError, subprocess.SubprocessError) as error:
+        print(ERROR_PREFLIGHT_FAILURE_TEMPLATE.format(error), file=sys.stderr)
+        return EXIT_CODE_FAILURE
+    if preflight_error:
+        print(preflight_error, file=sys.stderr)
+        return EXIT_CODE_FAILURE
+    return run_child_process(all_child_arguments, project_root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/.agents/skills/test-runner/scripts/test_preflight_checks.py

@@ -0,0 +1,185 @@
+"""Focused tests for explicit test-runner preflight helpers."""
+
+from __future__ import annotations
+
+import importlib
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+preflight_checks = importlib.import_module("preflight_checks")
+
+
+def test_check_server_health_reports_unhealthy_response(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    completed_process = subprocess.CompletedProcess(
+        args=["curl"], returncode=0, stdout="503", stderr=""
+    )
+    monkeypatch.setattr(
+        preflight_checks.subprocess,
+        "run",
+        lambda *_arguments, **_keywords: completed_process,
+    )
+
+    assert preflight_checks.check_server_health("http://localhost:3000") == (
+        "BLOCKED: Server at http://localhost:3000 is not healthy (HTTP 503). "
+        "Fix the server before running tests."
+    )
+
+
+def test_check_django_database_requires_db_sqlite3(tmp_path: Path) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+
+    assert preflight_checks.check_django_database(tmp_path) == (
+        f"BLOCKED: No database file (db.sqlite3) found in {tmp_path}. "
+        "Run migrations before running tests."
+    )
+
+
+def test_extract_port_from_url_uses_explicit_or_default_port() -> None:
+    assert preflight_checks.extract_port_from_url("http://localhost:9000") == "9000"
+    assert preflight_checks.extract_port_from_url("http://localhost") == "8000"
+
+
+def test_check_test_db_flag_requires_detected_server_flag(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+    monkeypatch.setattr(
+        preflight_checks,
+        "_read_process_listing",
+        lambda: "python manage.py runserver",
+    )
+
+    assert preflight_checks.check_test_db_flag("http://localhost:8000", tmp_path) == (
+        "BLOCKED: Django server on port 8000 is not running with --test-db. "
+        "Restart with: python manage.py runserver --test-db 0.0.0.0:8000"
+    )
+
+
+def test_check_test_db_flag_ignores_test_database_flag_on_another_port(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+    monkeypatch.setattr(
+        preflight_checks,
+        "_read_process_listing",
+        lambda: (
+            "python manage.py runserver --test-db 9000\n8000 python manage.py runserver"
+        ),
+    )
+
+    assert preflight_checks.check_test_db_flag("http://localhost:8000", tmp_path) == (
+        "BLOCKED: Django server on port 8000 is not running with --test-db. "
+        "Restart with: python manage.py runserver --test-db 0.0.0.0:8000"
+    )
+
+
+def test_check_test_db_flag_skips_value_taking_runserver_options(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+    monkeypatch.setattr(
+        preflight_checks,
+        "_read_process_listing",
+        lambda: "python manage.py runserver --settings project.settings 8000",
+    )
+
+    assert preflight_checks.check_test_db_flag("http://localhost:8000", tmp_path) == (
+        "BLOCKED: Django server on port 8000 is not running with --test-db. "
+        "Restart with: python manage.py runserver --test-db 0.0.0.0:8000"
+    )
+
+
+def test_check_test_db_flag_accepts_value_taking_options_with_test_db(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+    monkeypatch.setattr(
+        preflight_checks,
+        "_read_process_listing",
+        lambda: "python manage.py runserver --settings project.settings --test-db 8000",
+    )
+
+    assert (
+        preflight_checks.check_test_db_flag("http://localhost:8000", tmp_path) is None
+    )
+
+
+def test_check_runserver_port_conflicts_reports_other_worktree(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    project_root = tmp_path / "project"
+    other_project_root = tmp_path / "other-project"
+    project_root.mkdir()
+    other_project_root.mkdir()
+    monkeypatch.setattr(
+        preflight_checks,
+        "_get_runserver_processes_on_port",
+        lambda _port: [(1, str(project_root)), (2, str(other_project_root))],
+    )
+
+    assert (
+        preflight_checks.check_runserver_port_conflicts(
+            "http://localhost:8000", project_root
+        )
+        == f"BLOCKED: Multiple Django runserver processes are bound to port 8000 across worktrees: {other_project_root.resolve()}. Stop stale servers first."
+    )
+
+
+def test_build_frontend_runs_build_then_collectstatic(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "manage.py").write_text("", encoding="utf-8")
+    (tmp_path / "frontend").mkdir()
+    all_calls: list[tuple[list[str], Path]] = []
+
+    def run_process(
+        all_arguments: list[str], **keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        all_calls.append((all_arguments, keyword_arguments["cwd"]))
+        return subprocess.CompletedProcess(
+            args=all_arguments, returncode=0, stdout="", stderr=""
+        )
+
+    monkeypatch.setattr(preflight_checks.subprocess, "run", run_process)
+
+    assert preflight_checks.build_frontend(tmp_path) is None
+    assert all_calls == [
+        (["npm", "run", "build"], tmp_path / "frontend"),
+        (["python", "manage.py", "collectstatic", "--noinput"], tmp_path),
+    ]
+
+
+def test_build_frontend_skips_collectstatic_without_manage_py(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    (tmp_path / "frontend").mkdir()
+    all_calls: list[list[str]] = []
+
+    def run_process(
+        all_arguments: list[str], **_keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        all_calls.append(all_arguments)
+        return subprocess.CompletedProcess(
+            args=all_arguments, returncode=0, stdout="", stderr=""
+        )
+
+    monkeypatch.setattr(preflight_checks.subprocess, "run", run_process)
+
+    assert preflight_checks.build_frontend(tmp_path) is None
+    assert all_calls == [["npm", "run", "build"]]