Faster Development Checks

Faster desktop development checks

Use this workflow with CONTRIBUTING and AGENTS.md. It shortens feedback between edits while retaining the full verification gate for a final runtime candidate.

1. Run the owning host fixtures while editing

For Start selection, paging and destination changes:

python scripts/verify-host.py --suite start --download-deps
python scripts/verify-host.py --suite start

Requires Python 3 and JDK 17 or newer; select a JDK with JAVA_HOME or --java-home PATH. No Android SDK, NDK or Gradle configuration is needed. The first command explicitly permits downloading two pinned, SHA-256-checked JUnit/Hamcrest JARs into ignored build/host-tests/dependencies. Subsequent runs work offline. Existing Gradle dependency caches can also supply those JARs; explicit paths are accepted with --junit-jar and --hamcrest-jar.

The runner compiles fresh classes in temporary storage, extracts the existing production-body fixtures and propagates compilation/test failures. It does not reuse stale test classes. The Start suite includes selection, navigation, destination and application-catalog tests: 24 tests in 2.64 seconds on a Windows/JDK 17 test environment, or 3.26 seconds including initial JAR downloads. A new paging regression failed before the production fix and passed after it. These are observed timings, not performance guarantees.

Two additional suites keep input and state parsing feedback independent from Android builds:

python scripts/verify-host.py --suite input
python scripts/verify-host.py --suite parsers

The input suite covers event-committed focus and routing leases (16 tests). The parsers suite covers SystemUI desktop/transition state, task-local insets and task-stack parsing (27 tests). In the latest Windows/JDK 17 sequential run, each finished in 1.20 seconds and compiled fresh production and test classes. Together with Start, all three suites ran 67 tests in about 5.1 seconds. These timings are a local measurement, not a guarantee. The suites cover only their listed boundaries and do not replace the final repository verification gate.

For desktop-surface file selection, run the dedicated fresh-compile suite:

python scripts/verify-host.py --suite selection

It exercises the production selection model and desktop marquee policy: Ctrl toggling and range anchors, inclusive Shift ranges, Ctrl+A, clipboard ordering, stale-item removal, rectangle normalization/intersection/clipping, gesture slop and cancellation, modifier-based marquee selection, and source checks for the Android integration seams. PR #52 defines 24 tests across those cases; the focused checks passed in GitHub Actions. The combined focused job for Start, input, parsers, selection and taskbar checks took 17 seconds. This is an observed workflow duration including setup, not an isolated selection-suite timing. Physical pointer behavior still needs device verification.

The desktop host checks workflow runs the focused Start, input, parser and selection suites on relevant pull requests, plus the taskbar pin fixtures. Android CI continues to run Start, input and parser suites immediately after Java setup, before native/Android work. Other changes need their own owning fixtures; passing one focused suite says nothing about unrelated task, graphics or framework behavior. With an Android toolchain, use filtered Gradle unit tests for boundaries not covered by this runner.

2. Reproduce on an identified device and build

Establish a complete current-main compatibility baseline and exact reproduction as required by AGENTS.md. Retain its private evidence. Within the same unchanged build/device/firmware/adapter/privilege environment, reuse that evidence instead of repeating wireless pairing, authorization, discovery and setup after every small edit. Refresh the baseline when any of those identities changes.

The semantic Start paging smoke check uses the existing MCP client and credentials:

python scripts/verify-start-device.py --endpoint http://127.0.0.1:8765/mcp \
  --token-file /private/path/connection.txt --expected-build EXACT_BUILD_ID \
  --display-id 0
python scripts/verify-start-device.py --endpoint http://127.0.0.1:8765/mcp \
  --token-file /private/path/connection.txt --expected-build EXACT_BUILD_ID \
  --virtual

These commands expect the unchanged baseline (Page Down does not move selection). Add --expect-paging for the changed build. On PowerShell use one line or its native continuation syntax. An authorized forwarded local endpoint is supported; do not enable network MCP merely to use this check. --query must match more results than the viewport. Device/authorization setup is a prerequisite, not something the script silently creates.

The script rejects the wrong build or a locked/unready phone before test actions. It opens independent Start, checks selection identity, fully visible row geometry and retained search focus, sends Page Down/Up, and verifies Escape via global task_absent. It creates only its own optional 1280x720/160-dpi virtual display, then removes that exact display and releases its exact awake lease, including on test failure. It does not start Desktop, change HOME, claim input or restart Shizuku. JSON evidence contains application/UI data and belongs in ignored private storage (build/reports/start-device by default), never a public PR attachment.

The script passed baseline and changed-build checks on phone and owned virtual displays, including cleanup. Changed-build checks took about 4s and 14s respectively, including owned resources. Intentional expectation failure also confirms cleanup. Cold launches await selected results after asynchronous application enumeration. Device timing varies with Android transitions; retain event/state waits rather than replacing them with arbitrary sleeps. A stable snapshot may need bounded fresh reads as UI events advance. selected propagates to child views: identify the actionable result row, rather than counting every selected node. Unknown/absent UI windows are not proof of task closure; use the exact task identity and global observation.

3. Build and verify one final runtime candidate

Run verifyDevelopment plus the boundary-specific checks required by AGENTS.md. If the local Android/native toolchain is unavailable, use full repository CI. Check whether CI already exists for the exact commit before dispatching another run. Do not rebuild the APK for every documentation edit or rerun a successful full pipeline without a new runtime change, failure or unresolved concern. Record the tested runtime commit separately from later documentation commits.

Standard Gradle build caching is enabled, and CI retains its existing dependency cache. Task outputs are eligible for reuse only through Gradle's input keys; do not claim every native Exec task is cacheable or bypass verification. See Gradle's build-cache contract. The full-build speedup has not yet been measured. Full checks remain necessary; the measured improvement is quick feedback before spending time on them.

On the merged H2 runtime candidate, the Android CI build job took 7m34; its Windows smoke job was still running at the last observation. This is one run, not a guarantee. The focused host job finished in 17 seconds, making it the appropriate edit loop; reserve the full cross-platform gate for a runtime candidate.

Close an active Desktop through production cleanup before installing. Verify APK integrity and signature. Reuse the same development signing certificate and update in place to preserve settings, grants and MCP credentials. Do not repeat uninstall/data reset as routine setup; a signature mismatch needs explicit approval. Reconnect and verify the installed build ID before changed-build checks.

Independent Start checks cover its shared widget on phone and virtual displays. They do not establish managed Desktop, physical PC input, wired monitor, OEM HOME ownership, or gaming coverage. Mark unavailable targets pending. Follow the UX acceptance matrix for changes to those boundaries; never reduce assertions to make unavailable hardware look verified.