From def3b9faa858a62304faaf9718eb11bef76afb3c Mon Sep 17 00:00:00 2001
From: Alan Everett <thatcomputerguy0101@gmail.com>
Date: Thu, 6 Nov 2025 14:38:07 -0500
Subject: [PATCH] Only show images during tests when requested via project
 property (#2177)

## Description

Revision of #2164. Instead of only running headless tests during a
build, now only the images are disabled. To reenable showing images, the
`enableTestUi` project property needs to be passed to gradle.

```bash
./gradlew test -PenableTestUi
```

## Meta

Merge checklist:
- [X] Pull Request title is [short, imperative
summary](https://cbea.ms/git-commit/) of proposed changes
- [X] The description documents the _what_ and _why_
- [X] This PR has been
[linted](https://docs.photonvision.org/en/latest/docs/contributing/linting.html).
- [x] If this PR changes behavior or adds a feature, user documentation
is updated
- [ ] If this PR touches photon-serde, all messages have been
regenerated and hashes have not changed unexpectedly
- [ ] If this PR touches configuration, this is backwards compatible
with settings back to v2025.3.2
- [ ] If this PR touches pipeline settings or anything related to data
exchange, the frontend typing is updated
- [ ] If this PR addresses a bug, a regression test for it is added
---
 .github/workflows/build.yml                   |  6 ++---
 .../docs/contributing/building-photon.md      | 23 +++++++++++++++++++
 shared/common.gradle                          | 23 +++----------------
 3 files changed, 28 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 497bac00b..07179431a 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -88,10 +88,8 @@ jobs:
         run: sudo apt-get update && sudo apt-get install -y libcholmod3 liblapack3 libsuitesparseconfig5
       - name: Gradle Build
         run: ./gradlew photon-targeting:build photon-core:build photon-server:build -x check
-      - name: Gradle Tests
-        run: ./gradlew testHeadless --stacktrace
-      - name: Gradle Coverage
-        run: ./gradlew jacocoTestReport
+      - name: Gradle Tests and Coverage
+        run: ./gradlew test jacocoTestReport --stacktrace
   build-offline-docs:
     name: "Build Offline Docs"
     runs-on: ubuntu-22.04
diff --git a/docs/source/docs/contributing/building-photon.md b/docs/source/docs/contributing/building-photon.md
index 7947a919f..2c0a65c3d 100644
--- a/docs/source/docs/contributing/building-photon.md
+++ b/docs/source/docs/contributing/building-photon.md
@@ -177,6 +177,29 @@ With the VSCode [Extension Pack for Java](https://marketplace.visualstudio.com/i
 
 To correctly run PhotonVision tests this way, you must [delegate the tests to Gradle](https://code.visualstudio.com/docs/java/java-build#_delegate-tests-to-gradle). Debugging tests like this will [**not** currently](https://github.com/microsoft/build-server-for-gradle/issues/119) collect outputs.
 
+### Running Tests With UI
+
+By default, tests are run with UI disabled so they are not obtrusive during a build. All tests should be useful when the UI is disabled. However, if a particular test would benefit from having UI access (i.e. for debugging info), the UI can be enabled by passing the `enableTestUi` project property to Gradle. This will run all tests by default, but the Gradle `--tests` option can be used to [filter for specific tests](https://docs.gradle.org/current/userguide/java_testing.html#test_filtering).
+
+```{eval-rst}
+.. tab-set::
+
+   .. tab-item:: Linux
+      :sync: linux
+
+      ``./gradlew test -PenableTestUi``
+
+   .. tab-item:: macOS
+      :sync: macos
+
+      ``./gradlew test -PenableTestUi``
+
+   .. tab-item:: Windows (cmd)
+      :sync: windows
+
+      ``gradlew test -PenableTestUi``
+```
+
 ### Debugging PhotonVision Running Locally
 
 Unit tests can instead be debugged through the ``test`` Gradle task for a specific subproject in VSCode, found in the Gradle tab:
diff --git a/shared/common.gradle b/shared/common.gradle
index 5ed2f857a..d6e2c2e33 100644
--- a/shared/common.gradle
+++ b/shared/common.gradle
@@ -54,24 +54,14 @@ dependencies {
 
 test {
     useJUnitPlatform()
-    testLogging {
-        events "passed", "skipped", "failed", "standardOut", "standardError"
-    }
-    workingDir = new File("${rootDir}")
-    finalizedBy jacocoTestReport
-}
-
-tasks.register('testHeadless', Test) {
-    group = "verification"
-    systemProperty("java.awt.headless", "true")
-    useJUnitPlatform()
+    systemProperty("java.awt.headless", !project.hasProperty("enableTestUi"))
     testLogging {
         events "passed", "skipped", "failed", "standardOut", "standardError"
         exceptionFormat = "full"
         showStandardStreams = true
     }
-    exclude '**/*BenchmarkTest*'
     workingDir = new File("${rootDir}")
+    finalizedBy jacocoTestReport
 }
 
 jacoco {
@@ -80,7 +70,7 @@ jacoco {
 }
 
 jacocoTestReport {
-    dependsOn testHeadless
+    dependsOn test
 
     reports {
         xml.required = true
@@ -96,10 +86,3 @@ jacocoTestReport {
         }))
     }
 }
-
-// Only run headless tests from the build task
-gradle.taskGraph.whenReady { graph ->
-    if (graph.hasTask(build)) {
-        test.enabled = false
-    }
-}