Local runner - round 3

README.md

@@ -132,12 +132,20 @@ 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.
+volume so repeated runs are fast. By default it runs Python unit tests,
+syntax tests and syntax compatibility checks.
+
+`--file` chooses the runner from the selected file: Python files run as unit
+tests, `syntax_test*` files run as syntax tests, and `.sublime-syntax` files
+run compatibility checks.
 
 Useful options:
 
 - `--file tests/test_foo.py`
 - `--pattern test_foo.py --tests-dir tests/subdir`
+- `--no-unit-tests`
+- `--no-syntax-tests`
+- `--no-syntax-compatibility-checks`
 - `--coverage`
 - `--failfast`
 - `--reload-package-on-testing` (default: off)

docker/README.md

@@ -26,52 +26,63 @@ By default it:
 
 - builds `unittesting-local` image from `./docker` if missing
 - mounts your repo as `/project`
+- runs Python unit tests, syntax tests and syntax compatibility checks
 - 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`
+- excludes files ignored by Git, including repository-local and global rules
 
-## Manual docker usage
+A category with no matching resources is reported and succeeds. Disable
+categories that are not needed with:
 
 ```sh
-# build from UnitTesting/docker
-docker build -t unittesting-local .
+ut-run-tests . --no-unit-tests
+ut-run-tests . --no-syntax-tests
+ut-run-tests . --no-syntax-compatibility-checks
+```
 
-# run from package root
-docker run --rm -it \
-  -e PACKAGE=$PACKAGE \
-  -v $PWD:/project \
-  -v unittesting-home:/root \
-  unittesting-local run_tests
+`--file` selects its category automatically. Python files run as unit tests,
+files whose names start with `syntax_test` run as syntax tests, and
+`.sublime-syntax` files run compatibility checks:
+
+```sh
+ut-run-tests . --file tests/test_example.py
+ut-run-tests . --file syntax_test_example
+ut-run-tests . --file Example.sublime-syntax
 ```
 
+`--pattern` and `--tests-dir` try every enabled category. Use the
+`--no-*` options to avoid running unrelated categories when desired.
+
 ## Fast reruns
 
 The container entrypoint writes a marker in `/root/.cache/unittesting`.
 With `-v unittesting-home:/root`, bootstrap/install runs once and later runs
 only refresh your package files and execute tests.
 
-## Serialized runs
+## Concurrent runs and races
 
 The shared cache volume contains the Sublime data directory, including
-`Packages`, `Lib`, UnitTesting schedules and test output files. Concurrent
-runs against the same volume are serialized by default to avoid races while
+`Packages`, `Lib`, UnitTesting schedules and test output files. *Concurrent
+runs against the same volume are serialized by default* to avoid races while
 copying packages, writing schedules and syncing Package Control libraries.
+This is a speed-versus-space trade-off: tests are likely to run quickly,
+keeping wait times low, and a shared volume uses less disk space than
+multiple volumes.
 
 Use `--lock-timeout SECONDS` to control how long a runner waits for the cache
 volume lock. Use `--no-lock` only if you know the selected cache volume is not
 shared by another runner.
 
-## Concurrent runs
-
-You can control concurrency by choosing how many cache volumes you use. The
-default single volume serializes all runs. A stable volume per package allows
-different packages to run concurrently while still keeping warm caches:
+You can increase concurrency by choosing how many cache volumes you use. For
+example, a stable volume per package allows different packages to run
+concurrently while still keeping warm caches:
 
 ```sh
 ut-run-tests . --cache-volume unittesting-home-gitsavvy
 ```
 
-To maximize concurrency, use a stable volume per checkout directory. For
+To *maximize* concurrency, use a stable volume per checkout directory. For
 example, in a POSIX shell:
 
 ```sh
@@ -120,7 +131,21 @@ Use `--color` to control ANSI colors in test output:
 ut-run-tests . --color always
 ```
 
-## Run a single test file
+## Manual docker usage
+
+```sh
+# build from UnitTesting/docker
+docker build -t unittesting-local .
+
+# run from package root
+docker run --rm -it \
+  -e PACKAGE=$PACKAGE \
+  -v $PWD:/project \
+  -v unittesting-home:/root \
+  unittesting-local run_tests
+```
+
+Run a single test file
 
 ```sh
 docker run --rm -it \

docker/entrypoint.sh

@@ -99,7 +99,11 @@ fi
 if [ -d "$UNITTESTING_SOURCE/sbin" ]; then
     # Ensure UnitTesting comes from the local checkout running this script,
     # so first runs do not depend on tagged upstream releases.
-    (cd "$UNITTESTING_SOURCE" && PACKAGE=UnitTesting /docker.sh copy_tested_package overwrite)
+    (
+        cd "$UNITTESTING_SOURCE"
+        PACKAGE=UnitTesting UNITTESTING_IGNORE_MANIFEST= \
+            /docker.sh copy_tested_package overwrite
+    )
 
     # Normalize CRLF in shell scripts copied from Windows workspaces.
     if [ -d "$ST_PACKAGES_DIR/UnitTesting/sbin" ]; then