Run the Linux starter canary under Xvfb

.github/workflows/starter-canary.yml

@@ -94,6 +94,14 @@ jobs:
           java-version: '17'
           distribution: 'temurin'
 
+      # The Maven CSS goal initializes Java AWT while compiling theme.css.
+      # GitHub's Linux runner has no display, so without Xvfb a healthy starter
+      # fails locally before it can submit its cloud build. Windows already has
+      # a desktop session and must not try to install or invoke xvfb-run.
+      - name: Install Xvfb for CSS compilation
+        if: runner.os == 'Linux'
+        run: bash scripts/ci/apt-get-install.sh xvfb
+
       - name: Run the canary
         id: canary
         continue-on-error: true
@@ -115,10 +123,14 @@ jobs:
         run: |
           set -u
           skip=""
+          command=(python)
+          if [ "$RUNNER_OS" = "Linux" ]; then
+            command=(xvfb-run -a python)
+          fi
           if [ "$CANARY_SKIP_BUILD" = "true" ]; then
             skip="--skip-build"
           fi
-          python scripts/ci/starter-canary/starter_canary.py \
+          "${command[@]}" scripts/ci/starter-canary/starter_canary.py \
             --target "$CANARY_TARGET" \
             $skip \
             --report "$CANARY_REPORT"

scripts/ci/starter-canary/test_starter_canary.py

@@ -387,6 +387,26 @@ def test_run_requires_an_explicit_timeout(self):
         self.assertIs(parameter.default, inspect.Parameter.empty)
 
 
+class WorkflowContract(unittest.TestCase):
+    """The live Linux leg needs a display even though the runner is headless."""
+
+    @classmethod
+    def workflow(cls):
+        root = Path(__file__).resolve().parents[3]
+        return (root / ".github/workflows/starter-canary.yml").read_text()
+
+    def test_linux_installs_xvfb(self):
+        workflow = self.workflow()
+        self.assertIn("if: runner.os == 'Linux'", workflow)
+        self.assertIn("bash scripts/ci/apt-get-install.sh xvfb", workflow)
+
+    def test_linux_runs_the_canary_inside_xvfb(self):
+        workflow = self.workflow()
+        self.assertIn('if [ "$RUNNER_OS" = "Linux" ]; then', workflow)
+        self.assertIn("command=(xvfb-run -a python)", workflow)
+        self.assertIn('"${command[@]}" scripts/ci/starter-canary/starter_canary.py', workflow)
+
+
 class PomProperties(unittest.TestCase):
     """The plugin version is its own property and must not be assumed equal."""