py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/testcommands/test_commands.py

@@ -0,0 +1,786 @@
+"""
+Test command implementation for wl tool.
+"""
+
+import fnmatch
+import json
+import sys
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import click
+
+from ...utils.config import ConfigProvider
+from ...utils.output_context import (
+    get_output_config,
+    is_concise_mode,
+)
+from ...utils.root import Root, RootKind
+from ..base import BaseCommand
+from .cache_manager import CacheManager
+from .coverage_analyzer import (
+    CoverageAnalyzer,
+    CoverageStats,
+    collect_coverage_inputs,
+)
+from .coverage_cache_manager import CoverageCacheManager
+from .progress_manager import ProgressManager
+
+# Import modular components
+from .python_env_detector import PythonEnvDetector
+from .test_command_builder import TestCommandBuilder
+from .test_result_handler import TestResultHandler
+from .test_runner import TestRunner, _iter_python_files
+from .test_utils import _ensure_pytest_available, _process_command_args
+
+
+@dataclass(frozen=True)
+class ExistingCoverageResult:
+    coverage_data: dict[str, Any] | None = None
+    stale: bool = False
+
+
+# pytest's default ``python_files`` patterns: what a directory selector expands
+# to in step-by-step mode (step-by-step runs files, not node ids).
+_PYTEST_FILE_PATTERNS = ("test_*.py", "*_test.py")
+
+
+def _split_nodeid(selector: str) -> tuple[str, str]:
+    """Split ``tests/test_mod.py::TestFoo::test_bar`` into path and node part."""
+    path_part, _, node_part = selector.partition("::")
+    return path_part, node_part
+
+
+def _expand_directory(directory: Path) -> list[Path]:
+    """Test modules below ``directory``, by pytest's default file patterns.
+
+    The walk is ``test_runner._iter_python_files`` -- the one definition #191
+    gave a directory selector, so ``.venv``/``venv``/``site-packages``/
+    ``node_modules`` and hidden directories never become step-by-step targets.
+    A plain ``rglob`` turned this repository's own ``.venv`` into 39 extra
+    "test files" (rv192 MINOR-1).
+    """
+    return sorted(
+        path
+        for path in _iter_python_files(directory)
+        if any(
+            fnmatch.fnmatchcase(path.name, pattern) for pattern in _PYTEST_FILE_PATTERNS
+        )
+    )
+
+
+def _resolve_step_selectors(
+    selectors: list[str], project_root: str | Path
+) -> tuple[list[Path], list[str]]:
+    """Resolve ``wl test -s`` arguments to the test files they name.
+
+    Step-by-step mode runs one file at a time, so a selector may be a test
+    module, a directory of modules, or a pytest node id (``file::node``) --
+    the node id narrows the run to its file. Anything else (a stray option, a
+    missing path, a node id without a file) is returned as an error: silently
+    widening to the whole suite would run far more than the user asked for
+    (#192).
+
+    Returns:
+        ``(files, errors)`` -- files are de-duplicated in selector order.
+    """
+    files: list[Path] = []
+    errors: list[str] = []
+    root = Path(project_root)
+
+    def add(candidate: Path) -> None:
+        if candidate not in files:
+            files.append(candidate)
+
+    for selector in selectors:
+        if selector.startswith("-"):
+            errors.append(
+                f"unsupported option in step-by-step mode: {selector!r} "
+                "(pytest options are only forwarded in plain 'wl test')"
+            )
+            continue
+
+        path_part, node_part = _split_nodeid(selector)
+        if not path_part:
+            errors.append(f"node id has no file before '::': {selector!r}")
+            continue
+
+        candidate = Path(path_part)
+        if not candidate.exists():
+            candidate = root / path_part
+        if not candidate.exists():
+            errors.append(f"no such test file or directory: {path_part!r}")
+            continue
+
+        if candidate.is_dir():
+            expanded = _expand_directory(candidate)
+            if not expanded:
+                errors.append(f"no test modules under directory: {path_part!r}")
+                continue
+            for path in expanded:
+                add(path)
+            continue
+
+        if candidate.suffix != ".py":
+            errors.append(f"not a Python test file: {path_part!r}")
+            continue
+        if node_part:
+            print(f"[Step] Node id {selector!r} runs as its whole file: {candidate}")
+        add(candidate)
+
+    return files, errors
+
+
+class TestCommand(BaseCommand):
+    """Command to run tests for the project."""
+
+    # Tell pytest not to collect this class as a test class
+    __test__ = False
+
+    def __init__(self):
+        """Initialize TestCommand with modular components."""
+        super().__init__()
+        self.python_detector = PythonEnvDetector()
+        self.command_builder = TestCommandBuilder(self.python_detector)
+        self.result_handler = TestResultHandler()
+        self.cache_manager = CacheManager()
+        self.test_runner = TestRunner(self.cache_manager)
+        self.progress_manager = ProgressManager()
+        self.config_provider = ConfigProvider()
+
+    @property
+    def name(self) -> str:
+        """Get the command name."""
+        return "test"
+
+    @property
+    def help(self) -> str:
+        """Get the command help text."""
+        return "Run project tests"
+
+    def execute(self, *_, **kwargs: Any) -> None:
+        """
+        Execute the test command.
+
+        Args:
+            **kwargs: Keyword arguments
+        """
+        try:
+            # 处理命令行参数获取quiet/verbose first for output config
+            quiet = kwargs.get("quiet", False)
+            verbose = kwargs.get("verbose", False)
+            output_config = get_output_config(
+                override_quiet=quiet, override_verbose=verbose
+            )
+
+            # 显示当前使用的Python环境路径 - only in verbose mode
+            python_executable = self.python_detector.get_python_executable()
+            if output_config.verbose:
+                print(f"Running tests using Python environment: {python_executable}")
+
+            # 处理命令行参数
+            (
+                report_mode,
+                debug_mode,
+                step_by_step,
+                no_cache,
+                clean_cache,
+                cache_info,
+                quiet,
+                verbose,
+                passed_args,
+            ) = _process_command_args(self, kwargs)
+
+            # 获取coverage选项
+            cover_mode = kwargs.get("cover", False)
+
+            # 命令行参数优先级高于配置文件
+            fail_under_cmd = kwargs.get("fail_under", None)
+            if fail_under_cmd is not None:
+                fail_under = float(fail_under_cmd)
+            else:
+                # 从配置读取覆盖率阈值
+                fail_under = self.config_provider.get_config(
+                    "coverage.fail_under", 70.0
+                )
+
+            # 检查并安装pytest（如果需要）
+            python_executable = _ensure_pytest_available(python_executable)
+
+            # 处理缓存信息选项
+            if cache_info:
+                self.cache_manager.info()
+                return
+
+            # 处理清理缓存选项
+            if clean_cache:
+                self.cache_manager.purge_all()
+
+            # 获取coverage缓存和并行选项
+            no_cover_cache = kwargs.get("no_cover_cache", False)
+            cover_parallel_workers = kwargs.get("cover_parallel_workers", None)
+            no_skip = kwargs.get("no_skip", False)
+            evidence_json = kwargs.get("evidence_json")
+            evidence_path = Path(evidence_json) if evidence_json else None
+
+            # 如果是coverage模式，运行覆盖率分析
+            if cover_mode:
+                self._run_coverage_analysis(
+                    python_executable,
+                    step_by_step,
+                    fail_under,
+                    no_cover_cache,
+                    cover_parallel_workers,
+                )
+            else:
+                # 运行测试
+                self._run_tests(
+                    python_executable,
+                    report_mode,
+                    debug_mode,
+                    step_by_step,
+                    no_cache,
+                    quiet,
+                    verbose,
+                    passed_args,
+                    no_skip=no_skip,
+                    evidence_path=evidence_path,
+                )
+        except SystemExit:
+            # Re-raise SystemExit to allow tests to capture it
+            raise
+        except FileNotFoundError:
+            print(
+                "Error: pytest not found. Please install it using 'pip install pytest'"
+            )
+            sys.exit(1)
+        except Exception as e:
+            print(f"Error running tests: {e}")
+            sys.exit(1)
+
+    def _run_tests(
+        self,
+        python_executable: str,
+        report_mode: bool,
+        debug_mode: bool,
+        step_by_step: bool,
+        no_cache: bool,
+        quiet: bool,
+        verbose: bool,
+        passed_args: list[str],
+        no_skip: bool = False,
+        evidence_path: Path | None = None,
+    ) -> None:
+        """Run tests with the specified configuration."""
+        # ADR 0006: 回退是调用方策略 —— 由 project_root() 显式兜底 CWD
+        project_root = self.progress_manager.project_root()
+        # Create todos directory in current working directory
+        todo_dir = Path("todos")
+        todo_dir.mkdir(exist_ok=True)
+        concise = is_concise_mode(override_quiet=quiet, override_verbose=verbose)
+        self.progress_manager._log_project_paths(project_root, todo_dir, concise)
+
+        env = self.progress_manager._build_env(project_root)
+
+        # Handle step-by-step mode
+        if step_by_step:
+            if passed_args:
+                # Resolve selectors (files, directories, node ids) explicitly.
+                # An unrecognised selector is an error, never a silent fallback
+                # to the whole suite (#192).
+                test_files, selector_errors = _resolve_step_selectors(
+                    passed_args, project_root
+                )
+                # Both exits happen before any test run starts, so they write no
+                # `--evidence-json` record: there is no run for the file to
+                # describe (see docs/user/commands/test.md, "运行证据"). The
+                # contract covers terminating paths *after* a run begins.
+                if selector_errors:
+                    for error in selector_errors:
+                        print(f"Error: {error}")
+                    print("No tests were run. Fix the selector(s) and retry.")
+                    sys.exit(2)
+                if not test_files:
+                    print("Error: no test files matched the given selectors.")
+                    sys.exit(2)
+
+                # Run only specified test files
+                self.test_runner._run_specified_tests_step_by_step(
+                    python_executable,
+                    project_root,
+                    env,
+                    debug_mode,
+                    no_cache,
+                    quiet,
+                    verbose,
+                    test_files,
+                    no_skip=no_skip,
+                    evidence_path=evidence_path,
+                )
+            else:
+                # Run all test files
+                self.test_runner._run_tests_step_by_step(
+                    python_executable,
+                    project_root,
+                    env,
+                    debug_mode,
+                    no_cache,
+                    quiet,
+                    verbose,
+                    no_skip=no_skip,
+                    evidence_path=evidence_path,
+                )
+        else:
+            self.test_runner._run_tests_normal(
+                python_executable,
+                project_root,
+                env,
+                report_mode,
+                passed_args,
+                debug_mode,
+                todo_dir,
+                no_cache,
+                quiet,
+                verbose,
+                evidence_path=evidence_path,
+            )
+
+    def _run_coverage_analysis(
+        self,
+        python_executable: str,
+        step_by_step: bool = False,
+        fail_under: float | None = None,
+        no_cover_cache: bool = False,
+        cover_parallel_workers: int | None = None,
+    ) -> None:
+        """Run coverage analysis and generate improvement suggestions.
+
+        Three-phase flow:
+        1. Cache check - collect source and test files, check for cached coverage
+        2. Run pytest - only if cache miss, generate coverage.json
+        3. Foreground analysis - per-file check (step-by-step) or overall stats (normal)
+
+        Args:
+            python_executable: Path to Python executable
+            step_by_step: Whether to run in step-by-step mode (stop at first failure)
+            fail_under: If specified, fail if coverage is below this percentage
+            no_cover_cache: Whether to disable coverage caching
+            cover_parallel_workers: Number of parallel workers for coverage tests
+        """
+        # Root-anchored (#125): the test subsystem's own root policy, the same
+        # seam the non-coverage branch uses (`_run_tests` -> ``project_root()``),
+        # not the process CWD. The bare ``Path.cwd()`` this replaces fed both the
+        # analyzer and the ``.wl/coverage.json`` derivation below, so a run from
+        # a subdirectory read and wrote ``<subdir>/.wl``; and because
+        # ``CoverageAnalyzer.run_coverage`` mkdirs that parent, the stray ``.wl``
+        # *directory* then became a PROJECT marker and re-anchored the very sites
+        # this ticket root-anchored.
+        project_root = Path(self.progress_manager.project_root())
+        print("[Coverage] Running coverage analysis...")
+
+        analyzer = CoverageAnalyzer(project_root)
+
+        source_files = analyzer._find_source_files()
+        if not source_files:
+            print("[Coverage] No source files found to analyze")
+            return
+
+        # What the cached/stale coverage actually depended on: the whole test
+        # tree pytest executes plus conftest/pytest config -- not the at most
+        # one-to-one source->test mapping, which left every unmapped test file
+        # (e.g. tests/test_smoke.py) outside both the key and the freshness
+        # check (#192).
+        test_inputs = collect_coverage_inputs(project_root)
+
+        cache_mgr = CoverageCacheManager()
+        cache_enabled = (
+            self.config_provider.get_config("coverage.cache_enabled", True)
+            and not no_cover_cache
+        )
+        cache_key = cache_mgr.get_cache_key(source_files, test_inputs)
+
+        coverage_data = None
+        existing_result = ExistingCoverageResult()
+
+        if step_by_step:
+            existing_result = self._load_existing_coverage_json(
+                project_root,
+                source_files,
+                test_inputs,
+            )
+            coverage_data = existing_result.coverage_data
+
+            if not coverage_data and not existing_result.stale and cache_enabled:
+                coverage_data = cache_mgr.get_cached_coverage(cache_key)
+                if coverage_data:
+                    print("[Cache] Using cached coverage data")
+
+        if not coverage_data:
+            if existing_result.stale:
+                print(
+                    "[Coverage] Refreshing coverage data before step-by-step analysis..."
+                )
+            else:
+                print("[Coverage] Running pytest to generate coverage data...")
+            coverage_data = analyzer.run_coverage(
+                python_executable,
+                output_path=Root(project_root, RootKind.PROJECT).wl_dir()
+                / "coverage.json",
+            )
+
+            if coverage_data and cache_enabled:
+                # Only claim success when the entry was actually written. An
+                # unkeyed run (a file's stat failed) and a failed write both
+                # return False -- and the ledger already logs the write
+                # failure -- so a success line here would be a lie (#213
+                # review MEDIUM-1).
+                if cache_mgr.save_cached_coverage(cache_key, coverage_data):
+                    print("[Cache] Coverage data saved to cache")
+
+        if not coverage_data:
+            print("[Coverage] Failed to collect coverage data")
+            return
+
+        self._analyze_coverage(
+            analyzer,
+            coverage_data,
+            source_files,
+            step_by_step,
+            fail_under,
+            project_root,
+            python_executable,
+        )
+
+    def _load_existing_coverage_json(
+        self,
+        project_root: Path,
+        source_files: list[Path],
+        test_inputs: list[Path],
+    ) -> ExistingCoverageResult:
+        coverage_json_path = (
+            Root(project_root, RootKind.PROJECT).wl_dir() / "coverage.json"
+        )
+        if not coverage_json_path.exists():
+            return ExistingCoverageResult()
+
+        try:
+            content = coverage_json_path.read_text()
+            if not content.strip():
+                print("[Coverage] Existing coverage data is empty, skipping")
+                return ExistingCoverageResult()
+            coverage_data = json.loads(content)
+        except (OSError, json.JSONDecodeError):
+            print("[Coverage] Existing coverage data is unreadable, skipping")
+            return ExistingCoverageResult()
+
+        files = coverage_data.get("files")
+        if not isinstance(files, dict):
+            print("[Coverage] Existing coverage data has invalid schema, skipping")
+            return ExistingCoverageResult()
+
+        source_keys = {str(source_file) for source_file in source_files}
+        source_keys.update(
+            str(source_file.relative_to(project_root)) for source_file in source_files
+        )
+        if not source_keys.intersection(files):
+            print(
+                "[Coverage] Existing coverage data does not match current sources, skipping"
+            )
+            return ExistingCoverageResult()
+
+        updated = coverage_json_path.stat().st_mtime
+        checked_files = [*source_files, *test_inputs]
+        if any(
+            path.exists() and path.stat().st_mtime > updated for path in checked_files
+        ):
+            print(
+                "[Coverage] Existing coverage data is stale; source, test, "
+                "conftest or pytest config files changed after .wl/coverage.json."
+            )
+            return ExistingCoverageResult(stale=True)
+
+        updated_text = datetime.fromtimestamp(updated).strftime("%Y-%m-%d %H:%M:%S")
+        print(
+            "[Coverage] Using existing coverage data: .wl/coverage.json "
+            f"(updated {updated_text})"
+        )
+        return ExistingCoverageResult(coverage_data=coverage_data)
+
+    def _analyze_coverage(
+        self,
+        analyzer: CoverageAnalyzer,
+        coverage_data: dict[str, Any],
+        source_files: list[Path],
+        step_by_step: bool,
+        fail_under: float | None,
+        project_root: Path | None = None,
+        python_executable: str | None = None,
+    ) -> None:
+        """Analyze coverage data and generate report.
+
+        Args:
+            analyzer: CoverageAnalyzer instance
+            coverage_data: Coverage data from pytest
+            source_files: List of source files to analyze
+            step_by_step: Whether to run in step-by-step mode
+            fail_under: Coverage threshold percentage
+        """
+        analyzer.set_coverage_data(coverage_data)
+
+        if not step_by_step:
+            overall_stats = analyzer.get_overall_stats()
+            overall_percent = float(overall_stats.get("overall_percent", 0.0))
+
+            print(f"\n[Coverage] Total coverage: {overall_percent:.1f}%")
+
+            if fail_under is not None:
+                if overall_percent < fail_under:
+                    print(
+                        f"❌ [Coverage] FAILED: Overall coverage ({overall_percent:.1f}%) "
+                        f"is below threshold ({fail_under}%)"
+                    )
+                    sys.exit(1)
+                else:
+                    print(
+                        f"✓ [Coverage] PASS: Coverage meets threshold ({fail_under}%)"
+                    )
+            return
+
+        print(f"\n[Coverage] Checking coverage for {len(source_files)} files...")
+        if fail_under is not None:
+            print(f"[Coverage] Threshold: {fail_under}%")
+        print("=" * 60)
+
+        stats_list: list[CoverageStats | None] = []
+        all_suggestions = []
+
+        display_root = project_root or Path.cwd()
+
+        for i, file_path in enumerate(source_files, 1):
+            file_rel = file_path.relative_to(display_root)
+
+            test_file = analyzer._find_test_file(file_path)
+            if not test_file:
+                stats_list.append(None)
+                continue
+
+            stats, suggestions = analyzer.analyze_file(file_path)
+            stats_list.append(stats)
+            all_suggestions.extend(suggestions)
+
+            coverage_percent = stats.coverage_percent
+
+            if coverage_percent >= (fail_under or 0):
+                print(
+                    f"\r[{i}/{len(source_files)}] ✓ {file_rel.name}", end="", flush=True
+                )
+            else:
+                if self._handle_step_coverage_failure(
+                    i,
+                    len(source_files),
+                    file_path,
+                    file_rel,
+                    test_file,
+                    suggestions,
+                    fail_under or 0,
+                    python_executable,
+                    analyzer,
+                ):
+                    continue
+
+        print(f"\n\n[Coverage] All {len(source_files)} files passed ✓")
+
+    def _handle_step_coverage_failure(
+        self,
+        index: int,
+        total: int,
+        file_path: Path,
+        file_rel: Path,
+        test_file: Path,
+        suggestions: list[Any],
+        fail_under: float,
+        python_executable: str | None,
+        analyzer: CoverageAnalyzer | None,
+    ) -> bool:
+        print()
+        print(f"[Coverage] {file_rel} is below threshold in current coverage data.")
+        recheck_passed = False
+        if analyzer is not None and python_executable is not None:
+            print(f"[Coverage] Rechecking with {test_file} before failing...")
+            # The per-file recheck parses its own temporary report through
+            # ``_read_coverage_json``, which overwrites the analyzer's shared
+            # ``coverage_data`` with a one-file report. Snapshot it here so the
+            # aggregate report keeps driving every later file's threshold
+            # decision; otherwise each remaining file reports a bogus 0% and
+            # triggers its own recheck (#182).
+            saved_coverage_data = analyzer.coverage_data
+            try:
+                recheck_passed = analyzer.run_coverage_for_file(
+                    python_executable, file_path, fail_under=fail_under
+                )
+            finally:
+                analyzer.coverage_data = saved_coverage_data
+
+        if recheck_passed:
+            print(f"[Coverage] Recheck passed for {file_rel}; continuing analysis.")
+            return True
+
+        print(f"[Coverage] Recheck confirmed {file_rel} is below threshold.")
+        print(f"[{index}/{total}] ❌ FAIL: {file_rel}")
+        print("\n提高此文件测试覆盖率")
+
+        if suggestions:
+            print("\nSuggestions for improvement:")
+            severity_order = {"high": 0, "medium": 1, "low": 2}
+            sorted_suggestions = sorted(
+                suggestions, key=lambda x: severity_order.get(x.severity, 2)
+            )
+            for suggestion in sorted_suggestions:
+                print(f"  [{suggestion.severity.upper()}] {suggestion.suggestion}")
+
+        print("\n[Coverage] Stopping at first failure as requested.")
+        sys.exit(1)
+
+    def _run_single_test_file(
+        self,
+        python_executable,
+        test_file,
+        project_root,
+        env,
+        debug_mode,
+        no_cache=False,
+        step_by_step=False,
+        concise=False,
+    ):
+        """Run single test file."""
+        return self.test_runner.single_test_executor.execute(
+            python_executable,
+            test_file,
+            project_root,
+            env,
+            debug_mode,
+            no_cache,
+            step_by_step,
+            concise,
+        )
+
+    def _get_all_test_files(self, project_root):
+        """Get all test files."""
+        return self.test_runner._get_all_test_files(project_root)
+
+    def _ensure_pytest_available(self, python_executable):
+        """Ensure pytest is available."""
+        from .test_utils import _ensure_pytest_available
+
+        return _ensure_pytest_available(python_executable)
+
+    def _process_command_args(self, kwargs):
+        """Process command arguments."""
+        from .test_utils import _process_command_args
+
+        return _process_command_args(self, kwargs)
+
+    def _build_test_command(
+        self, python_executable, test_file, debug_mode, step_by_step=False
+    ):
+        """Build test command."""
+        return self.test_runner.single_test_executor._build_test_command(
+            python_executable, test_file, debug_mode, step_by_step
+        )
+
+
+@click.command(
+    # Everything wl doesn't define itself must reach pytest untouched (#192):
+    # ``wl test -k ...`` used to die with NoSuchOption instead of forwarding.
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True}
+)
+@click.option("--report", is_flag=True, help="Show detailed test report")
+@click.option("--debug", is_flag=True, help="Run tests in debug mode")
+@click.option("-s", "--step-by-step", is_flag=True, help="Run one test file at a time")
+@click.option("--no-cache", is_flag=True, help="Skip cache and run all tests")
+@click.option(
+    "--use-cache",
+    is_flag=True,
+    help=(
+        "Reuse cached test results (default in step-by-step mode; "
+        "plain 'wl test' defaults to --no-cache)"
+    ),
+)
+@click.option("--clean-cache", is_flag=True, help="Clean all test cache before running")
+@click.option("--cache-info", is_flag=True, help="Show cache information and exit")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress verbose output")
+@click.option("-v", "--verbose", is_flag=True, help="Force verbose output")
+@click.option("--cover", is_flag=True, help="Run coverage analysis")
+@click.option(
+    "--fail-under", type=float, default=None, help="Override coverage threshold"
+)
+@click.option("--no-cover-cache", is_flag=True, help="Disable coverage caching")
+@click.option(
+    "--cover-parallel-workers",
+    type=int,
+    default=None,
+    help="Number of parallel workers for coverage tests",
+)
+@click.option(
+    "--no-skip", is_flag=True, help="Don't skip slow test checks for known patterns"
+)
+@click.option(
+    "--evidence-json",
+    "evidence_json",
+    type=click.Path(dir_okay=False, path_type=str),
+    default=None,
+    metavar="PATH",
+    help=(
+        "Write structured evidence of this test run (executed files, cache "
+        "hits, exit code) to PATH, atomically"
+    ),
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+def test_command(
+    report: bool,
+    debug: bool,
+    step_by_step: bool,
+    no_cache: bool,
+    use_cache: bool,
+    clean_cache: bool,
+    cache_info: bool,
+    quiet: bool,
+    verbose: bool,
+    cover: bool,
+    fail_under: float | None,
+    no_cover_cache: bool,
+    cover_parallel_workers: int | None,
+    evidence_json: str | None,
+    args: tuple[str, ...],
+    no_skip: bool = False,
+) -> None:
+    """Run this project's tests with pytest.
+
+    Plain "wl test" runs the whole suite as one pytest batch with the cache
+    off; --use-cache opts back in. Unrecognised options and positional
+    selectors are forwarded to pytest untouched. With -s / --step-by-step, wl
+    resolves the selectors to test files, runs them one file at a time, reuses
+    cached results, and stops at the first failure. -s, -q and -v are wl's own
+    switches and are never passed through to pytest.
+    """
+    cmd = TestCommand()
+    cmd.execute(
+        report=report,
+        debug=debug,
+        step_by_step=step_by_step,
+        no_cache=no_cache,
+        use_cache=use_cache,
+        clean_cache=clean_cache,
+        cache_info=cache_info,
+        quiet=quiet,
+        verbose=verbose,
+        cover=cover,
+        fail_under=fail_under,
+        no_cover_cache=no_cover_cache,
+        cover_parallel_workers=cover_parallel_workers,
+        evidence_json=evidence_json,
+        no_skip=no_skip,
+        args=list(args),
+    )