test(dart): skip the Flutter desktop cases where no desktop can run; harden the Flutter e2e helpers (#790)

The first `flutter-host` run on ubuntu passed both widget-test cases and
ran both desktop cases: `flutter devices` lists the host desktop whenever
the platform feature flag is on (linux_workflow.dart `canListDevices`),
display or toolchain or not, and `flutter run -d linux` died on the
headless runner. From the scoped review of #881:

- `flutterDesktopDeviceId()` answers null on Linux without a
  DISPLAY/WAYLAND_DISPLAY and anywhere with MCP_SKIP_FLUTTER_DESKTOP=1; the
  lane sets the variable and also filters the run to `-t 'widget test'`,
  so its name is true by construction.
- `flutterDeviceIds()` parses the tool's stdout only (its warnings follow
  the JSON on stderr and used to turn the list into [] silently).
- `which flutter` is realpath'd before deriving the root (Homebrew, asdf
  and fvm put symlinks on PATH); the tool-snapshot requirement applies on
  Windows only, where the adapter spawns the snapshot itself.
- The example's docs and analysis options no longer assume Windows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: cynarlab

.github/workflows/ci.yml

@@ -506,8 +506,12 @@ jobs:
     - name: Build project
       run: pnpm build
     - name: Run Flutter host smoke (widget tests)
+      # `flutter devices` lists `linux` on this headless runner too; the desktop cases need a
+      # display and the GTK toolchain, so they are skipped explicitly (first run: both failed).
+      env:
+        MCP_SKIP_FLUTTER_DESKTOP: '1'
       run: |
-        pnpm exec vitest run --project e2e tests/e2e/mcp-server-smoke-flutter.test.ts --reporter=default --reporter=json --outputFile=artifacts/flutter/host-tests.json
+        pnpm exec vitest run --project e2e tests/e2e/mcp-server-smoke-flutter.test.ts -t 'widget test' --reporter=default --reporter=json --outputFile=artifacts/flutter/host-tests.json
         node scripts/check-flutter-e2e-report.mjs artifacts/flutter/host-tests.json
     - name: Upload Flutter validation evidence
       if: always()

examples/dart/README.md

@@ -10,9 +10,9 @@ adapter (`dart debug_adapter`), which ships with every Dart and Flutter install.
   (Windows: `winget install Google.DartSDK`; macOS: `brew install dart`; Linux: the `dart` apt package).
 - For `dart_probe/`, resolve its one dev dependency once: `cd dart_probe && dart pub get`.
 - For `flutter_probe/`, a Flutter SDK with a warm tool cache (`flutter --version` once), then
-  `cd flutter_probe && flutter create --platforms=windows,web . && flutter pub get` (the e2e helper
-  does this itself); `flutter run` on the desktop also needs that platform's toolchain
-  (`flutter doctor`).
+  `cd flutter_probe && flutter create --platforms=<windows|macos|linux>,web . && flutter pub get`
+  (the e2e helper does this itself for the host's desktop); `flutter run` on the desktop also needs
+  that platform's toolchain (`flutter doctor`).
 
 Do not run `dart test` from a project under `%LOCALAPPDATA%\Temp` with the winget SDK: package:test
 spawns the frontend server by a relative path that does not resolve from there.

examples/dart/flutter_probe/.gitignore

@@ -1,4 +1,4 @@
-# Generated by `flutter create --platforms=windows,web .` (the e2e helper runs it) and by builds.
+# Generated by `flutter create --platforms=<desktop>,web .` (the e2e helper runs it) and by builds.
 .dart_tool/
 .flutter-plugins-dependencies
 .metadata

examples/dart/flutter_probe/README.md

@@ -4,14 +4,16 @@ The Flutter example the adapter's tests and docs use: a counter app (`lib/main.d
 test (`test/widget_test.dart`) and an integration test (`integration_test/app_test.dart`).
 
 Only the Dart sources and `pubspec.yaml` are committed. The platform folders the Flutter tool needs
-to run the app are generated, once, with:
+to run the app are generated, once, for your desktop (`windows`, `macos` or `linux`) and the web:
 
 ```bash
-flutter create --platforms=windows,web .
+flutter create --platforms=windows,web .    # or macos,web / linux,web
 flutter pub get
 ```
 
-The e2e helper (`tests/e2e/dart-example-utils.ts`, `prepareFlutterProbe`) runs exactly that.
+The e2e helper (`tests/e2e/dart-example-utils.ts`, `prepareFlutterProbe`) runs exactly that for
+the host's desktop. `flutter create .` leaves the committed files alone (it never overwrites
+without `--overwrite`).
 
 | File | Breakpoint markers |
 |---|---|
@@ -22,6 +24,6 @@ The e2e helper (`tests/e2e/dart-example-utils.ts`, `prepareFlutterProbe`) runs e
 ```bash
 flutter test                                  # the widget tests
 flutter test --name increments                # one of them
-flutter run -d windows                        # the app on the desktop
+flutter run -d windows                        # the app on the desktop (-d macos / -d linux)
 flutter test integration_test -d windows      # the integration test on the desktop
 ```

examples/dart/flutter_probe/analysis_options.yaml

@@ -4,5 +4,8 @@ analyzer:
   exclude:
     - build/**
     - android/**
+    - ios/**
+    - linux/**
+    - macos/**
     - web/**
     - windows/**

tests/e2e/README.md

@@ -80,8 +80,9 @@ This directory contains end-to-end smoke tests that verify the MCP debugger serv
 - `mcp-server-smoke-flutter.test.ts` covers the Flutter runners against `examples/dart/flutter_probe`
   (`flutter debug-adapter --test` for the widget test, with and without `stopOnEntry`; `flutter run`
   and an `integration_test` on the desktop device `flutter devices` lists). It self-skips without a
-  Flutter SDK with a warm tool cache, and the desktop cases skip without a desktop device (CI's
-  `flutter-host` lane runs the widget-test cases only; `scripts/check-flutter-e2e-report.mjs`
+  Flutter SDK with a warm tool cache, and the desktop cases skip without a desktop device — on
+  Linux also without a `DISPLAY`, and anywhere with `MCP_SKIP_FLUTTER_DESKTOP=1` (CI's
+  `flutter-host` lane sets it and runs the widget-test cases only; `scripts/check-flutter-e2e-report.mjs`
   requires them). The helper generates the probe's platform folders with `flutter create` on
   first use
 

tests/e2e/dart-example-utils.ts

@@ -4,7 +4,7 @@
  * and locate `// BP-NAME` marker lines so moving a line never breaks an assertion.
  */
 import { spawnSync } from 'child_process';
-import { existsSync, readFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import which from 'which';
@@ -91,7 +91,12 @@ function flutterRootCandidates(): string[] {
   const env = process.env;
   for (const key of ['FLUTTER_ROOT', 'FLUTTER_PATH']) if (env[key]) out.push(env[key]!);
   const onPath = which.sync('flutter', { nothrow: true });
-  if (onPath) out.push(path.resolve(path.dirname(onPath), '..'));
+  if (onPath) {
+    // Package managers (Homebrew, asdf, fvm) put a symlink on PATH; the checkout is where it points.
+    let real = onPath;
+    try { real = realpathSync(onPath); } catch { /* keep the symlink path */ }
+    out.push(path.resolve(path.dirname(real), '..'));
+  }
   if (process.platform === 'win32') {
     out.push('C:\\src\\flutter', 'C:\\flutter', path.join(env.LOCALAPPDATA ?? '', 'flutter'));
   } else {
@@ -102,11 +107,15 @@ function flutterRootCandidates(): string[] {
 
 let cachedFlutterRoot: string | null | undefined;
 
-/** A Flutter checkout with a warm tool cache (the snapshot the adapter spawns on Windows); null when none. */
+/**
+ * A Flutter checkout; on Windows one with a warm tool cache (the adapter spawns the tool snapshot
+ * there instead of flutter.bat), elsewhere bin/flutter builds the cache itself. Null when none.
+ */
 export function findFlutterRootSync(): string | null {
   if (cachedFlutterRoot !== undefined) return cachedFlutterRoot;
   cachedFlutterRoot = flutterRootCandidates().find((root) =>
-    root && existsSync(path.join(root, 'bin', FLUTTER_LAUNCHER)) && existsSync(path.join(root, 'bin', 'cache', 'flutter_tools.snapshot'))
+    root && existsSync(path.join(root, 'bin', FLUTTER_LAUNCHER))
+      && (process.platform !== 'win32' || existsSync(path.join(root, 'bin', 'cache', 'flutter_tools.snapshot')))
   ) ?? null;
   return cachedFlutterRoot;
 }
@@ -129,10 +138,11 @@ export function flutterToolArgv(root: string, args: string[]): { command: string
   };
 }
 
-function runFlutter(root: string, args: string[], cwd: string, timeoutMs = 300_000): { status: number | null; out: string } {
+function runFlutter(root: string, args: string[], cwd: string, timeoutMs = 300_000): { status: number | null; stdout: string; out: string } {
   const argv = flutterToolArgv(root, args);
   const r = spawnSync(argv.command, argv.args, { cwd, encoding: 'utf8', env: argv.env, windowsHide: true, timeout: timeoutMs });
-  return { status: r.status, out: `${r.stdout ?? ''}${r.stderr ?? ''}` };
+  const stdout = r.stdout ?? '';
+  return { status: r.status, stdout, out: `${stdout}${r.stderr ?? ''}` };
 }
 
 let flutterProbePrepared = false;
@@ -167,17 +177,26 @@ export function flutterDeviceIds(): string[] {
   if (!root) return (cachedDevices = []);
   const r = runFlutter(root, ['devices', '--machine'], DART_EXAMPLES_DIR, 120_000);
   try {
-    const start = r.out.indexOf('[');
-    const list = JSON.parse(r.out.slice(start)) as Array<{ id?: string }>;
+    // stdout only: the tool's warnings (`[!] adb …`, startup-lock notices) go to stderr and would
+    // follow the array.
+    const start = r.stdout.indexOf('[');
+    const list = JSON.parse(r.stdout.slice(start)) as Array<{ id?: string }>;
     cachedDevices = list.map((d) => d.id).filter((id): id is string => typeof id === 'string');
   } catch {
     cachedDevices = [];
   }
   return cachedDevices;
 }
 
-/** The desktop device id for this OS, when `flutter devices` lists it. */
+/**
+ * The desktop device id for this OS, when `flutter devices` lists it and it can actually run an
+ * app: `flutter devices` lists `linux` on a headless runner too, where `flutter run -d linux`
+ * dies for want of a display and the GTK toolchain (measured on CI's ubuntu lane), so Linux needs
+ * a DISPLAY/WAYLAND_DISPLAY; `MCP_SKIP_FLUTTER_DESKTOP=1` skips the desktop cases anywhere.
+ */
 export function flutterDesktopDeviceId(): string | null {
+  if (process.env.MCP_SKIP_FLUTTER_DESKTOP === '1') return null;
+  if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return null;
   const want = process.platform === 'win32' ? 'windows' : process.platform === 'darwin' ? 'macos' : 'linux';
   return flutterDeviceIds().includes(want) ? want : null;
 }

tests/e2e/mcp-server-smoke-flutter.test.ts

@@ -5,7 +5,11 @@
  * desktop `build()` breakpoint each take ~30 s from a cold example (kernel compile, runner build)
  * and a few seconds warm; a `flutter test` session ends with `terminated` only, so the session is
  * `stopped` without an exit code. Self-skips without a Flutter SDK; the desktop cases also skip
- * when `flutter devices` lists no desktop target (CI's ubuntu lane runs the widget tests only).
+ * when `flutter devices` lists no desktop target, on Linux without a display, and anywhere with
+ * `MCP_SKIP_FLUTTER_DESKTOP=1` (CI's ubuntu lane sets it and runs the widget tests only). The
+ * tool lists the host desktop whenever the platform feature flag is on, so a Windows box with
+ * Flutter but no Visual Studio still reaches the runner build and fails there: install the
+ * toolchain `flutter doctor` names, or set the variable.
  */
 import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
 import path from 'path';