Document -Ptests syntax for Exec-based test tasks

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jbachorik

AGENTS.md

@@ -242,11 +242,16 @@ Release builds automatically extract debug symbols:
 ## Development Workflow
 
 ### Running Single Tests
-Use standard Gradle syntax:
+Use project properties to filter tests (config-specific test tasks use Exec, not Test):
 ```bash
-./gradlew :ddprof-test:test --tests "ClassName.methodName"
+./gradlew :ddprof-test:testdebug -Ptests=ClassName.methodName  # Single method
+./gradlew :ddprof-test:testdebug -Ptests=ClassName              # Entire class
 ```
 
+**Note**: Use `-Ptests` (not `--tests`) because config-specific test tasks (testdebug, testrelease)
+use Gradle's Exec task type to bypass toolchain issues on musl systems. The `--tests` flag only
+works with Gradle's Test task type.
+
 ### Working with Native Code
 Native compilation is automatic during build. C++ code changes require:
 1. Full rebuild: `/build-and-summarize clean build`
@@ -639,11 +644,11 @@ The CI caches JDKs via `.github/workflows/cache_java.yml`. When adding a new JDK
       ```
     - Instead of:
       ```bash
-      ./gradlew :prof-utils:test --tests "UpscaledMethodSampleEventSinkTest"
+      ./gradlew :ddprof-test:testdebug -Ptests=MuslDetectionTest
       ```
       use:
       ```bash
-      ./.claude/commands/build-and-summarize :prof-utils:test --tests "UpscaledMethodSampleEventSinkTest"
+      ./.claude/commands/build-and-summarize :ddprof-test:testdebug -Ptests=MuslDetectionTest
       ```
 
 - This ensures the full build log is captured to a file and only a summary is shown in the main session.

ddprof-stresstest/README.md

@@ -230,9 +230,11 @@ Use reduced iterations:
 ### Profiler fails to start
 Verify profiler library loads:
 ```bash
-./gradlew :ddprof-test:test --tests "JavaProfilerTest.testGetInstance"
+./gradlew :ddprof-test:testdebug -Ptests=JavaProfilerTest.testGetInstance
 ```
 
+**Note**: Use `-Ptests` (not `--tests`) with config-specific test tasks like `testdebug`.
+
 ### Out of memory errors
 - Reduce concurrent thread counts
 - Use smaller parameter values

doc/build/GradleTasks.md

@@ -62,9 +62,11 @@ testTsan                 # Java tests with TSAN library (Linux)
 **Examples:**
 ```bash
 ./gradlew :ddprof-test:testRelease
-./gradlew :ddprof-test:testDebug --tests "*.ProfilerTest"
+./gradlew :ddprof-test:testDebug -Ptests=ProfilerTest
 ```
 
+**Note**: Use `-Ptests` (not `--tests`) with config-specific test tasks. The `--tests` flag only works with Gradle's Test task type, but config-specific tasks (testDebug, testRelease) use Exec task type to bypass toolchain issues on musl systems.
+
 ### C++ Unit Tests (Google Test)
 
 ```
@@ -178,7 +180,7 @@ linkFuzz_{TargetName}    # Link fuzz target
 
 ### Quick Development Cycle
 ```bash
-./gradlew assembleDebug :ddprof-test:testDebug --tests "*.MyTest"
+./gradlew assembleDebug :ddprof-test:testDebug -Ptests=MyTest
 ```
 
 ### Pre-commit Checks

utils/run-docker-tests.sh

@@ -414,9 +414,10 @@ fi
 # ========== Run Tests ==========
 
 # Build gradle test command
+# Note: Use -Ptests (not --tests) because config-specific tasks use Exec, not Test
 GRADLE_CMD="./gradlew -PCI -PkeepJFRs :ddprof-test:test${CONFIG}"
 if [[ -n "$TESTS" ]]; then
-    GRADLE_CMD="$GRADLE_CMD --tests \"$TESTS\""
+    GRADLE_CMD="$GRADLE_CMD -Ptests=\"$TESTS\""
 fi
 if ! $GTEST_ENABLED; then
     GRADLE_CMD="$GRADLE_CMD -Pskip-gtest"