Use the launcher script:

# from UnitTesting repo root
./docker/ut-run-tests /path/to/package
./docker/ut-run-tests /path/to/package --file tests/test_example.py

Or call it via absolute path from any package directory:

/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 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

A category with no matching resources is reported and succeeds. Disable categories that are not needed with:

ut-run-tests . --no-unit-tests
ut-run-tests . --no-syntax-tests
ut-run-tests . --no-syntax-compatibility-checks

--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:

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.

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. Each run removes the session that Sublime Text saved in the previous run, so that no views from earlier runs are open when the tests start.

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 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.

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:

ut-run-tests . --cache-volume unittesting-home-gitsavvy

To maximize concurrency, use a stable volume per checkout directory. For example, in a POSIX shell:

volume="unittesting-home-$(pwd -P | sha256sum | cut -c1-12)"
ut-run-tests . --cache-volume "$volume"

Runs that choose different volumes do not wait on each other. Runs that choose the same volume remain serialized.

Use launcher flags instead of calling docker manually:

• --refresh-cache: recreate unittesting-home cache volume (forces fresh bootstrap, including Sublime Text/Package Control install path)
• --refresh-image: rebuild local image (for Dockerfile/entrypoint changes)
• --refresh: both --refresh-cache and --refresh-image

Examples:

ut-run-tests . --refresh-image
ut-run-tests . --refresh-cache
ut-run-tests . --refresh

Use --dry-run to print runner metadata (including detected Sublime Text and Package Control versions) plus the generated schedule.

ut-run-tests . --dry-run

Use --color to control ANSI colors in test output:

• --color auto (default): color only when stdout is a TTY
• --color always: force color
• --color never: disable color

ut-run-tests . --color always

# 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

docker run --rm -it \
  -e PACKAGE=$PACKAGE \
  -v $PWD:/project \
  -v unittesting-home:/root \
  unittesting-local run_tests --tests-dir tests --pattern test_example.py

On an ARM host, the launcher builds and runs a native arm64 image. The container installs the arm64 build of Sublime Text 4.

Runs under amd64 emulation (for example DOCKER_DEFAULT_PLATFORM=linux/amd64) are not supported.