jitcatch 0.2.0__py3-none-any.whl

jitcatch/__init__.py

@@ -0,0 +1,2 @@
+"""JiTCatch: Just-in-Time catching test generation (after Becker et al., FSE '26)."""
+__version__ = "0.2.0"

jitcatch/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

jitcatch/adapters/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .base import Adapter, TestPlacement
+from .golang import GoAdapter
+from .java import JavaAdapter
+from .javascript import TypeScriptAdapter
+from .python import PythonAdapter
+
+ADAPTER_CLASSES: dict[str, type[Adapter]] = {
+    "python": PythonAdapter,
+    "typescript": TypeScriptAdapter,
+    "java": JavaAdapter,
+    "go": GoAdapter,
+}
+
+
+def build_adapters(settings: dict[str, Any], repo: Path) -> list[Adapter]:
+    out = []
+    for name, cls in ADAPTER_CLASSES.items():
+        s = settings.get(name, {})
+        if s.get("enabled", True):
+            out.append(cls(s, repo))
+    return out
+
+
+def adapter_for(adapters: list[Adapter], rel_path: str) -> Adapter | None:
+    for a in adapters:
+        if a.handles(rel_path):
+            return a
+    return None
+
+
+__all__ = ["Adapter", "TestPlacement", "build_adapters", "adapter_for", "ADAPTER_CLASSES"]

jitcatch/adapters/base.py

@@ -0,0 +1,137 @@
+"""Language adapter interface: where generated tests go, how they run, and how outcomes are classified."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..models import Outcome, TestRun
+
+SKIP_DIRS = {".git", ".jitcatch", "node_modules", ".venv", "venv", "target", "build", "dist", "__pycache__", "vendor"}
+
+
+@dataclass
+class TestPlacement:
+    __test__ = False
+    rel_path: str                 # repo-relative path of the generated test file
+    instructions: str             # language/framework-specific constraints for the LLM
+    test_name_prefix: str = ""    # e.g. Go test function prefix used to select the test
+
+
+class Adapter:
+    name: str = "base"
+    fence_langs: tuple[str, ...] = ()
+    source_exts: tuple[str, ...] = ()
+
+    def __init__(self, settings: dict[str, Any], repo: Path):
+        self.settings = settings
+        self.repo = repo
+
+    # -- classification ---------------------------------------------------------------
+    def handles(self, rel_path: str) -> bool:
+        return rel_path.endswith(self.source_exts) and not self.is_test_file(rel_path)
+
+    def is_test_file(self, rel_path: str) -> bool:
+        raise NotImplementedError
+
+    # -- placement & prompting --------------------------------------------------------
+    def placement(self, source_rel: str, test_id: str, source_text: str) -> TestPlacement:
+        raise NotImplementedError
+
+    def related_test(self, source_rel: str) -> str | None:
+        """Repo-relative path of an existing test that most likely tests `source_rel`."""
+        stem = Path(source_rel).stem.lower()
+        best: tuple[int, str] | None = None
+        src_dir = Path(source_rel).parent
+        for dirpath, dirnames, filenames in os.walk(self.repo):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+            for fn in filenames:
+                rel = str(Path(dirpath, fn).relative_to(self.repo))
+                if not self.is_test_file(rel) or "jitcatch" in fn.lower():
+                    continue
+                name = fn.lower()
+                if stem and stem in name:
+                    # prefer tests closest to the source file
+                    distance = len(set(Path(rel).parent.parts) ^ set(src_dir.parts))
+                    score = distance
+                    if best is None or score < best[0]:
+                        best = (score, rel)
+        return best[1] if best else None
+
+    def any_test_example(self) -> str | None:
+        for dirpath, dirnames, filenames in os.walk(self.repo):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+            for fn in sorted(filenames):
+                rel = str(Path(dirpath, fn).relative_to(self.repo))
+                if self.is_test_file(rel) and "jitcatch" not in fn.lower():
+                    return rel
+        return None
+
+    # -- execution --------------------------------------------------------------------
+    def run_test(self, worktree: Path, test_rel: str, placement: TestPlacement, timeout: float) -> TestRun:
+        raise NotImplementedError
+
+    def run_existing_tests(self, worktree: Path, source_rel: str, timeout: float) -> TestRun | None:
+        """Run the project's existing tests relevant to `source_rel`. None = unsupported."""
+        return None
+
+    def available(self) -> tuple[bool, str]:
+        """Is the toolchain usable? Returns (ok, reason)."""
+        return True, ""
+
+    def can_test(self, rel_path: str) -> tuple[bool, str]:
+        """Can this particular file be tested (e.g. its package has a supported runner)? Returns (ok, reason)."""
+        return True, ""
+
+
+# -- helpers ------------------------------------------------------------------------------
+
+def run_cmd(cmd: list[str], cwd: Path, timeout: float, env_extra: dict[str, str] | None = None) -> tuple[int, str, float, bool]:
+    """Run a command; returns (exit_code, combined_output, seconds, timed_out)."""
+    env = dict(os.environ)
+    env.update({"CI": "1", "NO_COLOR": "1", "FORCE_COLOR": "0", "PYTHONDONTWRITEBYTECODE": "1"})
+    if env_extra:
+        env.update(env_extra)
+    t0 = time.monotonic()
+    try:
+        proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, encoding="utf-8",
+                              errors="replace", timeout=timeout, env=env)
+        out = (proc.stdout or "") + ("\n" + proc.stderr if proc.stderr else "")
+        return proc.returncode, strip_ansi(out), time.monotonic() - t0, False
+    except subprocess.TimeoutExpired as e:
+        out = (e.stdout or b"")
+        out = out.decode("utf-8", "replace") if isinstance(out, bytes) else out
+        return -1, strip_ansi(out) + f"\n[jitcatch] TIMEOUT after {timeout}s", time.monotonic() - t0, True
+    except FileNotFoundError as e:
+        return -2, f"[jitcatch] command not found: {e}", time.monotonic() - t0, False
+
+
+_ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+
+
+def strip_ansi(s: str) -> str:
+    return _ANSI.sub("", s)
+
+
+def make_run(outcome: Outcome, code: int, out: str, secs: float, cmd: list[str]) -> TestRun:
+    return TestRun(outcome=outcome, exit_code=code, output=truncate_output(out), duration_s=round(secs, 2), command=cmd)
+
+
+def truncate_output(out: str, head: int = 3000, tail: int = 12000) -> str:
+    if len(out) <= head + tail:
+        return out
+    return out[:head] + f"\n... [{len(out) - head - tail} chars truncated] ...\n" + out[-tail:]
+
+
+def nearest_dir_with(start: Path, stop: Path, names: tuple[str, ...]) -> Path | None:
+    d = start
+    while True:
+        if any((d / n).exists() for n in names):
+            return d
+        if d == stop or d.parent == d:
+            return None
+        d = d.parent

jitcatch/adapters/golang.py

@@ -0,0 +1,88 @@
+"""Go adapter (go test)."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path, PurePosixPath
+
+from ..models import Outcome, TestRun
+from .base import Adapter, TestPlacement, make_run, nearest_dir_with, run_cmd
+
+_PKG_RE = re.compile(r"^\s*package\s+(\w+)", re.M)
+
+
+class GoAdapter(Adapter):
+    name = "go"
+    fence_langs = ("go", "golang")
+    source_exts = (".go",)
+
+    def is_test_file(self, rel_path: str) -> bool:
+        return rel_path.endswith("_test.go")
+
+    def handles(self, rel_path: str) -> bool:
+        return super().handles(rel_path) and "/vendor/" not in f"/{rel_path}" and "/testdata/" not in f"/{rel_path}"
+
+    def related_test(self, source_rel: str) -> str | None:
+        p = PurePosixPath(source_rel)
+        cand = p.with_name(p.stem + "_test.go")
+        if (self.repo / cand).exists():
+            return str(cand)
+        for f in sorted((self.repo / p.parent).glob("*_test.go")):
+            if "jitcatch" not in f.name:
+                return str(f.relative_to(self.repo))
+        return None
+
+    def available(self) -> tuple[bool, str]:
+        code, _, _, _ = run_cmd(["go", "version"], self.repo, 60)
+        return (code == 0, "" if code == 0 else "go not available")
+
+    def placement(self, source_rel: str, test_id: str, source_text: str) -> TestPlacement:
+        p = PurePosixPath(source_rel)
+        m = _PKG_RE.search(source_text)
+        pkg = m.group(1) if m else "main"
+        rel = str(p.parent / f"{p.stem}_jitcatch_{test_id}_test.go")
+        prefix = f"TestJitcatch{test_id.upper()}"
+        instr = (
+            f"Framework: Go's standard `testing` package. The file must start with `package {pkg}` (same package, "
+            f"so unexported identifiers are accessible) and every test function name must start with `{prefix}` "
+            f"(e.g. `func {prefix}Something(t *testing.T)`). Only import the standard library and modules already "
+            "in go.mod. Do not use network, sleeps, randomness or time.Now; avoid reflect."
+        )
+        return TestPlacement(rel_path=rel, instructions=instr, test_name_prefix=prefix)
+
+    def _module(self, base: Path, rel: str) -> Path:
+        return nearest_dir_with((base / rel).parent, base, ("go.mod",)) or base
+
+    def run_test(self, worktree: Path, test_rel: str, placement: TestPlacement, timeout: float) -> TestRun:
+        mod = self._module(worktree, test_rel)
+        pkg_dir = os.path.relpath(worktree / PurePosixPath(test_rel).parent, mod)
+        target = "./" + pkg_dir.replace(os.sep, "/") if pkg_dir != "." else "."
+        cmd = ["go", "test", target, "-run", f"^{placement.test_name_prefix}", "-count=1", "-v",
+               *self.settings.get("extra_args", [])]
+        code, out, secs, timed_out = run_cmd(cmd, mod, timeout)
+        return make_run(self._classify(code, out, timed_out), code, out, secs, cmd)
+
+    def run_existing_tests(self, worktree: Path, source_rel: str, timeout: float) -> TestRun | None:
+        mod = self._module(worktree, source_rel)
+        pkg_dir = os.path.relpath(worktree / PurePosixPath(source_rel).parent, mod)
+        target = "./" + pkg_dir.replace(os.sep, "/") if pkg_dir != "." else "."
+        cmd = ["go", "test", target, "-count=1"]
+        code, out, secs, timed_out = run_cmd(cmd, mod, timeout)
+        outcome = Outcome.PASS if code == 0 else self._classify(code, out, timed_out)
+        return make_run(outcome, code, out, secs, cmd)
+
+    @staticmethod
+    def _classify(code: int, out: str, timed_out: bool) -> Outcome:
+        if timed_out or code == -2:
+            return Outcome.INFRA
+        if re.search(r"\[(build|setup) failed\]|^# \S+|cannot find package|no required module provides", out, re.M):
+            return Outcome.ERROR
+        if code == 0:
+            if "no tests to run" in out or "[no test files]" in out:
+                return Outcome.NO_TESTS
+            return Outcome.PASS
+        if re.search(r"^--- FAIL|^panic:|^FAIL\s", out, re.M):
+            return Outcome.FAIL
+        if re.search(r"go: (downloading|error loading)|dial tcp|proxy\.golang\.org", out):
+            return Outcome.INFRA
+        return Outcome.ERROR

jitcatch/adapters/java.py

@@ -0,0 +1,136 @@
+"""Java adapter for JUnit 4/5 via Maven or Gradle."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path, PurePosixPath
+
+from ..models import Outcome, TestRun
+from .base import Adapter, TestPlacement, make_run, nearest_dir_with, run_cmd
+
+_PKG_RE = re.compile(r"^\s*package\s+([\w.]+)\s*;", re.M)
+_BUILD_FILES = ("pom.xml", "build.gradle", "build.gradle.kts")
+
+
+class JavaAdapter(Adapter):
+    name = "java"
+    fence_langs = ("java",)
+    source_exts = (".java",)
+
+    def is_test_file(self, rel_path: str) -> bool:
+        p = PurePosixPath(rel_path)
+        return "test" in p.parts or bool(re.search(r"(Test|Tests|IT)\.java$", p.name))
+
+    def handles(self, rel_path: str) -> bool:
+        return super().handles(rel_path) and "/src/main/java/" in f"/{rel_path}"
+
+    def module_dir(self, base: Path, rel: str) -> Path:
+        return nearest_dir_with((base / rel).parent, base, _BUILD_FILES) or base
+
+    def build_tool(self, module: Path) -> str:
+        forced = self.settings.get("build", "auto")
+        if forced in ("maven", "gradle"):
+            return forced
+        if (module / "pom.xml").exists():
+            return "maven"
+        if (module / "build.gradle").exists() or (module / "build.gradle.kts").exists():
+            return "gradle"
+        return "maven"
+
+    def junit_version(self, module: Path) -> int:
+        text = ""
+        for n in _BUILD_FILES:
+            p = module / n
+            if p.exists():
+                text += p.read_text(encoding="utf-8", errors="replace")
+        if module != self.repo:
+            for n in _BUILD_FILES:
+                p = self.repo / n
+                if p.exists():
+                    text += p.read_text(encoding="utf-8", errors="replace")
+        if re.search(r"junit-jupiter|org\.junit\.jupiter|useJUnitPlatform", text):
+            return 5
+        if re.search(r"junit:junit|<artifactId>junit</artifactId>", text):
+            return 4
+        return 5
+
+    def placement(self, source_rel: str, test_id: str, source_text: str) -> TestPlacement:
+        src = PurePosixPath(source_rel)
+        m = _PKG_RE.search(source_text)
+        pkg = m.group(1) if m else ""
+        module_rel = PurePosixPath(os.path.relpath(self.module_dir(self.repo, source_rel), self.repo))
+        if str(module_rel) == ".":
+            module_rel = PurePosixPath("")
+        cls = f"{src.stem}JitcatchTest{test_id.upper()}"
+        rel = str(module_rel / "src/test/java" / PurePosixPath(*pkg.split(".")) / f"{cls}.java") if pkg else \
+            str(module_rel / "src/test/java" / f"{cls}.java")
+        junit = self.junit_version(self.module_dir(self.repo, source_rel))
+        fw = ("JUnit 5 (org.junit.jupiter.api.Test, org.junit.jupiter.api.Assertions.*)" if junit == 5
+              else "JUnit 4 (org.junit.Test, org.junit.Assert.*)")
+        instr = (
+            f"Framework: {fw}. The file must declare `package {pkg};` and a single public class named exactly "
+            f"`{cls}`. Only use libraries already on the test classpath (see the example test). Do not use "
+            "reflection, network, sleeps, randomness or the current time; test through the public API only."
+        )
+        return TestPlacement(rel_path=rel, instructions=instr, test_name_prefix=(f"{pkg}.{cls}" if pkg else cls))
+
+    def _wrapper(self, module: Path, tool: str) -> list[str]:
+        if tool == "maven":
+            for d in (module, self.repo):
+                if (d / "mvnw").exists():
+                    return [str(d / "mvnw")]
+            return ["mvn"]
+        for d in (module, self.repo):
+            if (d / "gradlew").exists():
+                return [str(d / "gradlew")]
+        return ["gradle"]
+
+    def available(self) -> tuple[bool, str]:
+        code, _, _, _ = run_cmd(["java", "-version"], self.repo, 60)
+        return (code == 0, "" if code == 0 else "java not available")
+
+    def run_test(self, worktree: Path, test_rel: str, placement: TestPlacement, timeout: float) -> TestRun:
+        module = self.module_dir(worktree, test_rel)
+        tool = self.build_tool(module)
+        exe = self._wrapper(module, tool)
+        fqcn = placement.test_name_prefix
+        if tool == "maven":
+            cmd = [*exe, "-B", "--no-transfer-progress", "test", f"-Dtest={fqcn}",
+                   "-Dsurefire.failIfNoSpecifiedTests=false", "-DfailIfNoTests=false", "-Djacoco.skip=true",
+                   *self.settings.get("extra_args", [])]
+        else:
+            cmd = [*exe, "test", "--tests", fqcn, "--console=plain", "--no-daemon", *self.settings.get("extra_args", [])]
+        code, out, secs, timed_out = run_cmd(cmd, module, timeout)
+        return make_run(self._classify(code, out, timed_out), code, out, secs, cmd)
+
+    def run_existing_tests(self, worktree: Path, source_rel: str, timeout: float) -> TestRun | None:
+        module = self.module_dir(worktree, source_rel)
+        tool = self.build_tool(module)
+        exe = self._wrapper(module, tool)
+        if tool == "maven":
+            cmd = [*exe, "-B", "--no-transfer-progress", "test", "-Djacoco.skip=true"]
+        else:
+            cmd = [*exe, "test", "--console=plain", "--no-daemon"]
+        code, out, secs, timed_out = run_cmd(cmd, module, timeout)
+        outcome = Outcome.PASS if code == 0 else self._classify(code, out, timed_out)
+        return make_run(outcome, code, out, secs, cmd)
+
+    @staticmethod
+    def _classify(code: int, out: str, timed_out: bool) -> Outcome:
+        if timed_out or code == -2:
+            return Outcome.INFRA
+        if re.search(r"Could not resolve dependencies|Could not transfer artifact|Could not GET|"
+                     r"Could not resolve all (files|dependencies)|Unable to access jarfile", out):
+            return Outcome.INFRA
+        if re.search(r"No tests found for given includes|No tests were executed|Tests run: 0,", out) and \
+                not re.search(r"Tests run: [1-9]", out):
+            return Outcome.NO_TESTS if code == 0 or "No tests" in out else Outcome.ERROR
+        if code == 0:
+            return Outcome.PASS
+        if re.search(r"Tests run: \d+, Failures: [1-9]|Tests run: \d+, Failures: \d+, Errors: [1-9]|"
+                     r"\d+ tests? completed, \d+ failed|FAILED\s*$", out, re.M) and \
+                not re.search(r"COMPILATION ERROR|Compilation failed|compile\w*Java FAILED", out):
+            return Outcome.FAIL
+        if re.search(r"COMPILATION ERROR|Compilation failed|compile\w*Java FAILED|error: cannot find symbol", out):
+            return Outcome.ERROR
+        return Outcome.FAIL

jitcatch/adapters/javascript.py

@@ -0,0 +1,165 @@
+"""TypeScript / JavaScript adapter for Jest and Vitest."""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path, PurePosixPath
+
+from ..models import Outcome, TestRun
+from .base import SKIP_DIRS, Adapter, TestPlacement, make_run, nearest_dir_with, run_cmd
+
+_TEST_RE = re.compile(r"\.(test|spec)\.[cm]?[jt]sx?$")
+
+
+class TypeScriptAdapter(Adapter):
+    name = "typescript"
+    fence_langs = ("typescript", "ts", "tsx", "javascript", "js", "jsx")
+    source_exts = (".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs")
+
+    def is_test_file(self, rel_path: str) -> bool:
+        p = PurePosixPath(rel_path)
+        return bool(_TEST_RE.search(p.name)) or "__tests__" in p.parts
+
+    def handles(self, rel_path: str) -> bool:
+        if not super().handles(rel_path) or rel_path.endswith(".d.ts"):
+            return False
+        n = PurePosixPath(rel_path).name
+        return not re.match(r"^(jest|vitest|vite|webpack|rollup|babel|eslint|prettier|tsup)\.config\.", n)
+
+    # -- package / runner discovery ----------------------------------------------------
+    def package_dir(self, base: Path, source_rel: str) -> Path:
+        d = nearest_dir_with((base / source_rel).parent, base, ("package.json",))
+        return d or base
+
+    def runner(self, pkg_dir: Path) -> str:
+        return self.detect_runner(pkg_dir) or "jest"
+
+    def detect_runner(self, pkg_dir: Path) -> str | None:
+        """Jest or Vitest for this package (falling back to the repo root), or None if neither is set up."""
+        forced = self.settings.get("runner", "auto")
+        if forced in ("jest", "vitest"):
+            return forced
+        deps: dict[str, str] = {}
+        pj = pkg_dir / "package.json"
+        if pj.exists():
+            try:
+                data = json.loads(pj.read_text(encoding="utf-8"))
+                for k in ("dependencies", "devDependencies", "peerDependencies"):
+                    deps.update(data.get(k) or {})
+            except (json.JSONDecodeError, OSError):
+                pass
+        names = {p.name for p in pkg_dir.iterdir()} if pkg_dir.is_dir() else set()
+        if "vitest" in deps or any(n.startswith("vitest.config.") for n in names):
+            return "vitest"
+        if "jest" in deps or any(n.startswith("jest.config.") for n in names):
+            return "jest"
+        # monorepo: look at the repository root as a fallback
+        if pkg_dir != self.repo:
+            return self.detect_runner(self.repo)
+        return None
+
+    def available(self) -> tuple[bool, str]:
+        code, out, _, _ = run_cmd(["npx", "--version"], self.repo, 60)
+        if code != 0:
+            return False, "npx not available"
+        if self.settings.get("runner", "auto") in ("jest", "vitest"):
+            return True, ""
+        pkgs = self._package_dirs()
+        if not any(self.detect_runner(d) for d in pkgs):
+            return False, ("no Jest or Vitest found in any package.json (other runners, e.g. Playwright, "
+                           "are not supported; set [adapters.typescript] runner to force one)")
+        return True, ""
+
+    def can_test(self, rel_path: str) -> tuple[bool, str]:
+        pkg = self.package_dir(self.repo, rel_path)
+        if self.detect_runner(pkg):
+            return True, ""
+        where = os.path.relpath(pkg, self.repo).replace(os.sep, "/")
+        return False, f"no Jest or Vitest configured for package '{where}'"
+
+    def _package_dirs(self) -> list[Path]:
+        out: list[Path] = []
+        for dirpath, dirnames, filenames in os.walk(self.repo):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+            if "package.json" in filenames:
+                out.append(Path(dirpath))
+        return out
+
+    # -- placement --------------------------------------------------------------------
+    def placement(self, source_rel: str, test_id: str, source_text: str) -> TestPlacement:
+        src = PurePosixPath(source_rel)
+        related = self.related_test(source_rel)
+        test_dir = PurePosixPath(related).parent if related else src.parent
+        ext = {".tsx": ".tsx", ".ts": ".ts", ".mts": ".mts", ".cts": ".cts", ".jsx": ".jsx",
+               ".mjs": ".mjs", ".cjs": ".cjs"}.get(src.suffix, ".js")
+        rel = str(test_dir / f"{src.stem}.jitcatch-{test_id}.test{ext}")
+        runner = self.runner(self.package_dir(self.repo, source_rel))
+        rel_import = os.path.relpath(str(src.with_suffix("")), str(test_dir)).replace(os.sep, "/")
+        if not rel_import.startswith("."):
+            rel_import = "./" + rel_import
+        if runner == "vitest":
+            fw = ("Framework: Vitest. Import test helpers explicitly: "
+                  "`import { describe, it, expect, vi } from 'vitest'`.")
+        else:
+            fw = ("Framework: Jest. Use the Jest globals (describe/it/expect/jest) — mirror the example test's "
+                  "imports (e.g. '@jest/globals') if it has any.")
+        instr = (
+            f"{fw} The test file is located at `{rel}`; import the module under test with the relative path "
+            f"'{rel_import}' (keep the import style and extension conventions of the example test if shown). "
+            "Do not use network, timers, randomness or the current date. Do not access private/#private members."
+        )
+        return TestPlacement(rel_path=rel, instructions=instr)
+
+    # -- execution --------------------------------------------------------------------
+    def _cmd(self, runner: str, rel_to_pkg: str | None) -> list[str]:
+        extra = list(self.settings.get("extra_args", []))
+        if runner == "vitest":
+            cmd = ["npx", "--no-install", "vitest", "run"]
+            if rel_to_pkg:
+                cmd += [rel_to_pkg]
+            return cmd + extra
+        cmd = ["npx", "--no-install", "jest", "--ci", "--colors=false"]
+        if rel_to_pkg:
+            cmd += ["--runTestsByPath", rel_to_pkg]
+        else:
+            cmd += ["--testPathIgnorePatterns", r"\.jitcatch-[0-9a-f]+\.test\."]
+        return cmd + extra
+
+    def run_test(self, worktree: Path, test_rel: str, placement: TestPlacement, timeout: float) -> TestRun:
+        pkg = self.package_dir(worktree, test_rel)
+        runner = self.runner(pkg)
+        rel_to_pkg = os.path.relpath(worktree / test_rel, pkg).replace(os.sep, "/")
+        cmd = self._cmd(runner, rel_to_pkg)
+        code, out, secs, timed_out = run_cmd(cmd, pkg, timeout)
+        return make_run(self._classify(code, out, timed_out), code, out, secs, cmd)
+
+    def run_existing_tests(self, worktree: Path, source_rel: str, timeout: float) -> TestRun | None:
+        pkg = self.package_dir(worktree, source_rel)
+        runner = self.runner(pkg)
+        cmd = self._cmd(runner, None)
+        if runner == "vitest":
+            cmd += ["--exclude", "**/*.jitcatch-*.test.*", "--passWithNoTests"]
+        else:
+            cmd += ["--passWithNoTests"]
+        code, out, secs, timed_out = run_cmd(cmd, pkg, timeout)
+        return make_run(self._classify(code, out, timed_out), code, out, secs, cmd)
+
+    @staticmethod
+    def _classify(code: int, out: str, timed_out: bool) -> Outcome:
+        if timed_out or code == -2:
+            return Outcome.INFRA
+        if re.search(r"could not determine executable to run|npm ERR! could not|command not found|"
+                     r"Cannot find module '(jest|vitest)", out):
+            return Outcome.INFRA
+        if re.search(r"No tests found|No test files found|no tests? (were )?found", out, re.I):
+            return Outcome.NO_TESTS
+        if code == 0:
+            return Outcome.PASS
+        # suite-level failures: compile / import / transform errors before any test executed
+        if re.search(r"Test suite failed to run|Failed to load url|Transform failed|"
+                     r"error TS\d+|SyntaxError:|Failed to resolve import|Cannot find module|"
+                     r"FAIL\s+\S+\s+\[\s*\S+\s*\]", out):
+            if not re.search(r"(✕|×|●\s.+›|AssertionError|expect\()", out):
+                return Outcome.ERROR
+        return Outcome.FAIL