Skip to content

Commit dd2f9c9

Browse files
kastekaste
committed
Improve local Docker test workflow
Document and harden the local containerized test path used by run_tests.py and docker entrypoints. This updates the docker/sbin workflow to better support repeated local runs with cache reuse, package refresh, and per-run test selection options. It also clarifies that sbin scripts remain relevant for local container automation even though GitHub CI prefers actions/*.
1 parent d4a880f commit dd2f9c9

11 files changed

Lines changed: 518 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,46 @@ so that <kbd>ctrl</kbd>+<kbd>b</kbd> would invoke the testing action.
112112
```
113113

114114

115+
### Headless container runner
116+
117+
To run tests without affecting your interactive Sublime Text session,
118+
use the bundled `docker/run_tests.py` script.
119+
120+
```sh
121+
# run all tests from current package root
122+
uv run docker/run_tests.py .
123+
124+
# run just one test file (faster)
125+
uv run docker/run_tests.py . --file tests/test_example.py
126+
```
127+
128+
This script runs tests in a Docker container (headless), streams output to
129+
stdout/stderr and keeps a cache volume so repeated runs are fast.
130+
131+
By default it:
132+
133+
- builds `unittesting-local` image from `./docker` if missing
134+
- mounts your repo as `/project`
135+
- runs UnitTesting through the same CI shell entrypoints
136+
- stores Sublime install/cache in docker volume `unittesting-home`
137+
- synchronizes only changed files into `Packages/<Package>` using `rsync`
138+
139+
Useful options:
140+
141+
- `--file tests/test_foo.py`
142+
- `--pattern test_foo.py --tests-dir tests/subdir`
143+
- `--coverage`
144+
- `--failfast`
145+
- `--docker-image <name>`
146+
- `--no-cache-volume`
147+
- `--scheduler-delay-ms 300` (lower can be faster)
148+
149+
> [!TIP]
150+
>
151+
> This is useful for editor build systems and for AI agents,
152+
> because test runs no longer commandeer your active editor window.
153+
154+
115155
## GitHub Actions
116156

117157
Unittesting provides the following GitHub Actions, which can be combined

‎docker/Dockerfile‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ FROM ubuntu:latest
33
USER root
44
RUN apt-get update
55
RUN apt-get install --no-install-recommends sudo apt-utils -y
6-
RUN apt-get install --no-install-recommends python software-properties-common -y
7-
RUN apt-get install --no-install-recommends git curl xvfb -y
6+
RUN apt-get install --no-install-recommends python3 python-is-python3 software-properties-common -y
7+
RUN apt-get install --no-install-recommends git curl xvfb rsync -y
88
RUN apt-get install --no-install-recommends libglib2.0-0 libgtk-3-0 -y
99
RUN apt-get install --no-install-recommends psmisc -y
1010
RUN apt-get install --no-install-recommends locales locales-all -y
@@ -15,17 +15,15 @@ RUN if [ "$arch" = "i386" ]; then apt-get update; fi
1515
RUN if [ "$arch" = "i386" ]; then apt-get install --no-install-recommends libc6:i386 libncurses5:i386 libstdc++6:i386 -y; fi
1616
RUN if [ "$arch" = "i386" ]; then apt-get install --no-install-recommends libglib2.0-0:i386 libgtk-3-0:i386 libx11-6:i386 -y; fi
1717

18-
ENV LANG en_US.UTF-8
19-
ENV LANGUAGE en_US.UTF-8
18+
ENV LANG=en_US.UTF-8
19+
ENV LANGUAGE=en_US.UTF-8
2020

2121
ENV DISPLAY=:1
2222
COPY xvfb /etc/init.d/xvfb
23-
RUN chmod +x /etc/init.d/xvfb
2423
COPY docker.sh /docker.sh
25-
RUN chmod +x /docker.sh
2624
COPY entrypoint.sh /entrypoint.sh
27-
RUN chmod 666 /entrypoint.sh
28-
RUN chmod +x /entrypoint.sh
25+
RUN sed -i 's/\r$//' /etc/init.d/xvfb /docker.sh /entrypoint.sh
26+
RUN chmod +x /etc/init.d/xvfb /docker.sh /entrypoint.sh
2927

3028
WORKDIR /project
3129
ENTRYPOINT ["/entrypoint.sh"]

‎docker/README.md‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,43 @@
11
# Docker image for Sublime Text UnitTesting
22

3+
## Recommended usage
4+
5+
Use the docker wrapper script:
6+
7+
```sh
8+
uv run docker/run_tests.py /path/to/package
9+
uv run docker/run_tests.py /path/to/package --file tests/test_example.py
10+
```
11+
12+
It builds/uses a local image, mounts the package at `/project`, runs tests
13+
headlessly, and keeps a cache volume for fast reruns.
14+
15+
## Manual docker usage
316

4-
## From Docker Hub
517
```sh
6-
# cd to package
7-
docker run --rm -it -e PACKAGE=$PACKAGE -v $PWD:/project sublimetext/unittesting
18+
# build from UnitTesting/docker
19+
docker build -t unittesting-local .
20+
21+
# run from package root
22+
docker run --rm -it \
23+
-e PACKAGE=$PACKAGE \
24+
-v $PWD:/project \
25+
-v unittesting-home:/root \
26+
unittesting-local run_tests
827
```
928

10-
## Build image from scratch
29+
## Fast reruns
30+
31+
The container entrypoint writes a marker in `/root/.cache/unittesting`.
32+
With `-v unittesting-home:/root`, bootstrap/install runs once and later runs
33+
only refresh your package files and execute tests.
34+
35+
## Run a single test file
36+
1137
```sh
12-
# cd to UnitTesting/docker
13-
docker build -t unittesting .
14-
# cd to package
15-
docker run --rm -it -e PACKAGE=$PACKAGE -v $PWD:/project unittesting
38+
docker run --rm -it \
39+
-e PACKAGE=$PACKAGE \
40+
-v $PWD:/project \
41+
-v unittesting-home:/root \
42+
unittesting-local run_tests --tests-dir tests --pattern test_example.py
1643
```

‎docker/docker.sh‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,13 @@ set -e
44

55
BASEDIR=`dirname $0`
66

7-
CISH="/tmp/ci.sh"
7+
UNITTESTING_SOURCE=${UNITTESTING_SOURCE:-/unittesting}
8+
CISH="$UNITTESTING_SOURCE/sbin/ci.sh"
89
if [ ! -f "$CISH" ]; then
9-
curl -s -L https://raw.githubusercontent.com/SublimeText/UnitTesting/master/sbin/ci.sh -o "$CISH"
10+
CISH="/tmp/ci.sh"
11+
if [ ! -f "$CISH" ]; then
12+
curl -s -L https://raw.githubusercontent.com/SublimeText/UnitTesting/master/sbin/ci.sh -o "$CISH"
13+
fi
1014
fi
1115

1216
if [ -z "$PACKAGE" ]; then

‎docker/entrypoint.sh‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,31 @@ echo PACKAGE = $PACKAGE
55
set -e
66

77
PATH="$HOME/.local/bin:$PATH"
8+
BOOTSTRAP_MARKER="$HOME/.cache/unittesting/bootstrap.done"
9+
810
sudo sh -e /etc/init.d/xvfb start
9-
/docker.sh bootstrap
10-
/docker.sh install_package_control
11-
/docker.sh run_tests --coverage
11+
12+
UNITTESTING_SOURCE=${UNITTESTING_SOURCE:-/unittesting}
13+
if [ -d "$UNITTESTING_SOURCE/sbin" ]; then
14+
# Ensure UnitTesting comes from the local checkout running this script,
15+
# so first runs do not depend on tagged upstream releases.
16+
(cd "$UNITTESTING_SOURCE" && PACKAGE=UnitTesting /docker.sh copy_tested_package overwrite)
17+
fi
18+
19+
if [ ! -f "$BOOTSTRAP_MARKER" ]; then
20+
# Bootstrap from a neutral cwd to avoid Windows worktree .git indirection
21+
# paths breaking git commands inside the Linux container.
22+
(cd /tmp && /docker.sh bootstrap skip_package_copy)
23+
/docker.sh install_package_control
24+
mkdir -p "$(dirname "$BOOTSTRAP_MARKER")"
25+
touch "$BOOTSTRAP_MARKER"
26+
fi
27+
28+
# Always refresh checked-out package into Packages/<PACKAGE>
29+
/docker.sh copy_tested_package overwrite
30+
31+
if [ "$#" -gt 0 ]; then
32+
/docker.sh "$@"
33+
else
34+
/docker.sh run_tests --coverage
35+
fi

0 commit comments

Comments
 (0)