Add stable ut-run-tests launcher scripts

Add docker/ut-run-tests and docker/ut-run-tests.cmd as simple, stable
entrypoints for local containerized runs without uv project coupling.

Update docs to recommend the launcher command and keep run_tests.py as
the underlying implementation detail.

Author: kaste

.gitattributes

@@ -4,6 +4,7 @@
 
 # Shell scripts used in Linux containers must stay LF in the working tree.
 /docker/*.sh               text eol=lf
+/docker/ut-run-tests       text eol=lf
 /docker/xvfb               text eol=lf
 /sbin/*.sh                 text eol=lf
 

README.md

@@ -115,18 +115,27 @@ so that <kbd>ctrl</kbd>+<kbd>b</kbd> would invoke the testing action.
 ### Headless container runner
 
 To run tests without affecting your interactive Sublime Text session,
-use the bundled `docker/run_tests.py` script.
+use the bundled `docker/ut-run-tests` launcher.
 
 ```sh
 # run all tests from current package root
-uv run docker/run_tests.py .
+/path/to/UnitTesting/docker/ut-run-tests .
 
 # run just one test file (faster)
-uv run docker/run_tests.py . --file tests/test_example.py
+/path/to/UnitTesting/docker/ut-run-tests . --file tests/test_example.py
 ```
 
-This script runs tests in a Docker container (headless), streams output to
-stdout/stderr and keeps a cache volume so repeated runs are fast.
+(Use `docker/ut-run-tests.cmd` in cmd.exe/PowerShell.)
+
+If `UnitTesting/docker` is on your `PATH`, you can simply run:
+
+```sh
+ut-run-tests .
+```
+
+This launcher calls `docker/run_tests.py`, which runs tests in a Docker
+container (headless), streams output to stdout/stderr and keeps a cache
+volume so repeated runs are fast.
 
 By default it:
 
@@ -142,9 +151,6 @@ Useful options:
 - `--pattern test_foo.py --tests-dir tests/subdir`
 - `--coverage`
 - `--failfast`
-- `--docker-image <name>`
-- `--no-cache-volume`
-- `--scheduler-delay-ms 0` (default)
 
 > [!TIP]
 >

docker/README.md

@@ -2,15 +2,33 @@
 
 ## Recommended usage
 
-Use the docker wrapper script:
+Use the launcher script:
 
 ```sh
-uv run docker/run_tests.py /path/to/package
-uv run docker/run_tests.py /path/to/package --file tests/test_example.py
+# from UnitTesting repo root
+./docker/ut-run-tests /path/to/package
+./docker/ut-run-tests /path/to/package --file tests/test_example.py
 ```
 
-It builds/uses a local image, mounts the package at `/project`, runs tests
-headlessly, and keeps a cache volume for fast reruns.
+Or call it via absolute path from any package directory:
+
+```sh
+/path/to/UnitTesting/docker/ut-run-tests .
+```
+
+If this directory is on your `PATH`, you can run `ut-run-tests` directly.
+
+The launcher calls `docker/run_tests.py`, builds/uses a local image,
+mounts the package at `/project`, runs tests headlessly, and keeps a cache
+volume for fast reruns.
+
+By default it:
+
+- builds `unittesting-local` image from `./docker` if missing
+- mounts your repo as `/project`
+- runs UnitTesting through the same CI shell entrypoints
+- stores Sublime install/cache in docker volume `unittesting-home`
+- synchronizes only changed files into `Packages/<Package>` using `rsync`
 
 ## Manual docker usage
 

docker/run_tests.py

@@ -1,15 +1,16 @@
 #!/usr/bin/env python3
 """Run Sublime Text UnitTesting in a Docker container.
 
+Usually invoked via the sibling launcher script `ut-run-tests`.
 Examples:
-    uv run docker/run_tests.py .
-    uv run docker/run_tests.py . --file tests/test_main.py
+    ./docker/ut-run-tests .
+    ./docker/ut-run-tests . --file tests/test_main.py
 """
 
 from __future__ import annotations
 
 import argparse
-from datetime import datetime, timezone
+import hashlib
 import shutil
 import subprocess
 import sys
@@ -18,6 +19,13 @@
 
 DEFAULT_IMAGE = "unittesting-local"
 DEFAULT_CACHE_VOLUME = "unittesting-home"
+DOCKER_CONTEXT_HASH_LABEL = "org.sublimetext.unittesting.context-hash"
+DOCKER_CONTEXT_INPUTS = (
+    "Dockerfile",
+    "docker.sh",
+    "entrypoint.sh",
+    "xvfb",
+)
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -171,8 +179,10 @@ def maybe_build_image(image: str, args: argparse.Namespace) -> None:
     if not context_dir.is_dir():
         raise SystemExit(f"Error: missing docker build context: {context_dir}")
 
+    context_hash = docker_context_hash(context_dir)
     image_exists = docker_image_exists(image)
-    context_changed = image_exists and docker_context_changed(context_dir, image)
+    image_hash = docker_image_context_hash(image) if image_exists else None
+    context_changed = image_exists and image_hash != context_hash
 
     should_build = args.build_image
     should_build = should_build or (args.build_if_missing and not image_exists)
@@ -185,7 +195,15 @@ def maybe_build_image(image: str, args: argparse.Namespace) -> None:
         print("Docker context changed since last image build, rebuilding...")
 
     print(f"Building docker image '{image}' from {context_dir} ...")
-    run_checked(["docker", "build", "-t", image, str(context_dir)])
+    run_checked([
+        "docker",
+        "build",
+        "--label",
+        f"{DOCKER_CONTEXT_HASH_LABEL}={context_hash}",
+        "-t",
+        image,
+        str(context_dir),
+    ])
 
 
 def docker_image_exists(image: str) -> bool:
@@ -197,53 +215,43 @@ def docker_image_exists(image: str) -> bool:
     return result.returncode == 0
 
 
-def docker_context_changed(context_dir: Path, image: str) -> bool:
-    image_created = docker_image_created_at(image)
-    if image_created is None:
-        return True
+def docker_context_hash(context_dir: Path) -> str:
+    digest = hashlib.sha256()
+    for rel_path in DOCKER_CONTEXT_INPUTS:
+        file_path = context_dir / rel_path
+        if not file_path.is_file():
+            raise SystemExit(f"Error: missing docker context file: {file_path}")
 
-    context_mtime = newest_mtime(context_dir)
-    return context_mtime > image_created
+        digest.update(rel_path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(file_path.read_bytes())
+        digest.update(b"\0")
 
+    return digest.hexdigest()
 
-def docker_image_created_at(image: str) -> float | None:
+
+def docker_image_context_hash(image: str) -> str | None:
     result = subprocess.run(
-        ["docker", "image", "inspect", image, "--format", "{{.Created}}"],
+        [
+            "docker",
+            "image",
+            "inspect",
+            image,
+            "--format",
+            "{{ index .Config.Labels \"%s\" }}" % DOCKER_CONTEXT_HASH_LABEL,
+        ],
         stdout=subprocess.PIPE,
         stderr=subprocess.DEVNULL,
         text=True,
     )
     if result.returncode != 0:
         return None
 
-    created = result.stdout.strip()
-    if not created:
-        return None
-
-    # Example: 2026-03-13T21:47:06.123456789Z
-    if created.endswith("Z"):
-        created = created[:-1]
-    if "." in created:
-        created = created.split(".", 1)[0]
-
-    try:
-        dt = datetime.strptime(created, "%Y-%m-%dT%H:%M:%S").replace(tzinfo=timezone.utc)
-    except ValueError:
+    value = result.stdout.strip()
+    if not value or value == "<no value>":
         return None
 
-    return dt.timestamp()
-
-
-def newest_mtime(path: Path) -> float:
-    latest = path.stat().st_mtime
-    for child in path.rglob("*"):
-        try:
-            mtime = child.stat().st_mtime
-        except OSError:
-            continue
-        if mtime > latest:
-            latest = mtime
-    return latest
+    return value
 
 
 def ensure_docker_volume(name: str) -> None:

docker/ut-run-tests

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+exec python "$SCRIPT_DIR/run_tests.py" "$@"

docker/ut-run-tests.cmd

@@ -0,0 +1,4 @@
+@echo off
+setlocal
+set "SCRIPT_DIR=%~dp0"
+python "%SCRIPT_DIR%run_tests.py" %*

sbin/README.md

@@ -1,6 +1,8 @@
 ## Status
 
-For GitHub CI, prefer the official composite [actions](https://github.com/SublimeText/UnitTesting/actions).
+For GitHub CI, prefer the official composite
+[actions](https://github.com/SublimeText/UnitTesting/actions).
 
-These scripts are still used for local/containerized automation (for example the Docker runner path used by `docker/run_tests.py`).
+These scripts are still used for local/containerized automation
+(for example the Docker runner path used by `docker/ut-run-tests`).
 They should be treated as supported for that workflow.