Authoritative Gradle Test Execution & Diagnostics

Executes tests with deep diagnostic tools to isolate and fix failures fast, ensuring maximum code quality and build reliability.

Constitution

• ALWAYS use the gradle tool instead of ./gradlew via shell.
• ALWAYS use the --tests flag for surgical test selection to minimize feedback loops.
• ALWAYS provide absolute paths for projectRoot.
• ALWAYS prefer foreground execution (default) unless the test suite is extremely long-running (>2 minutes) or you explicitly intend to perform independent research while it proceeds.
• ONLY use background: true for managed background orchestration when context isolation and non-blocking exploration are required.
• STRONGLY PREFERRED: Use inspect_build for all test diagnostics. It provides isolated output and full stack traces that are often truncated in the main console.
• ALWAYS use inspect_build with mode: "details" and testName="..." to access full test output and stack traces.
• NEVER use taskPath or captureTaskOutput to investigate specific test failures; these provide the overall task log which is often truncated and lacks per-test isolation.

Surgical Test Inspection with inspect_build

When tests fail, inspect_build is your most powerful diagnostic tool. It provides isolated output and full stack traces that are often truncated in the main console.

1. List All Failed Tests (Summary)

Use testOutcome="FAILED" to quickly see which tests failed without being overwhelmed by logs.

• Example: inspect_build(buildId="ID", testOutcome="FAILED")

2. Get Full Test Details (Details)

CRITICAL: ALWAYS use mode="details" and testName to see the complete stdout, stderr, and stack trace for a specific test.

• Unique Prefix Support: You can provide a unique prefix of the test name (e.g., testName="com.example.MyTest" instead of the full FQN). If the prefix is unique, the tool will automatically select the test. If ambiguous, it will return a list of matching names for refinement.
• Example: inspect_build(buildId="ID", mode="details", testName="com.example.MyTest.myMethod")

3. Filter by Name (Summary)

Use testName with the default mode="summary" to see all executions of a test (e.g., across different projects or iterations).

• Example: inspect_build(buildId="ID", testName="MyTest")

4. Progress Monitoring

Use timeout, waitFor, or waitForTask to block until a condition is met in a background test run.

• Example: inspect_build(buildId="ID", timeout=60, waitForTask=":app:test")
• Wait for completion: If timeout is set without a wait condition, the tool waits for the build to finish.

Directives

• ALWAYS use foreground for authoritative tests: If you intend to wait for results, ALWAYS use foreground execution. It provides superior progressive disclosure and simpler control flow than starting a background build only to immediately call inspect_build(timeout=...).
• Background ONLY for long test suites: Use background: true ONLY for test suites that take a long time to run and you explicitly intend to perform independent research while they proceed.
• Foreground tests are safe: Do not fear running high-output test suites in the foreground. The gradle tool uses progressive disclosure to provide concise summaries and structured results, keeping session history clean and efficient.
• Monitor with inspect_build: Use inspect_build to check the status of background test runs or to retrieve structured output and stack traces for failed tests.
• Check for environment failures: If a test run fails with a general error, use inspect_build(failures={}) to check for compilation or configuration issues.
• Investigate specifically: Use the testName option in inspect_build with mode="details" to isolate specific failure details. For detailed diagnostic workflows, see the test_diagnostics.md reference.

Authoritative Test Selection Patterns

The --tests flag supports powerful, high-precision filtering. Use these patterns to minimize execution time and context noise.

1. Simple Filters

• Exact Class: --tests com.example.MyTest
• Exact Method: --tests com.example.MyTest.myTestMethod
• Wildcard Method: --tests com.example.MyTest.test* (Runs all methods starting with 'test')

2. Wildcard Filters (* and ?)

• Package Filter: --tests com.example.service.* (Runs all tests in the 'service' package)
• Class Prefix: --tests *IntegrationTest (Runs all classes ending in 'IntegrationTest')
• Character Wildcard: --tests com.example.Test? (Matches Test1, TestA, etc.)

3. Syntax Rules

• No Class Path: Patterns match against the fully qualified name of the test class or method.
• Multi-Filter: You can provide multiple --tests flags to run a specific selection of tests.
  • gradle(commandLine=["test", "--tests", "ClassA", "--tests", "ClassB"])

Authoritative Task Path Syntax

Understanding how to target tests in a multi-project build is critical to avoid running more tests than necessary.

1. Task Selectors (Recursive)

Providing test without a leading colon executes the test task in every project (root and all subprojects) that has one.

• Example: gradle(commandLine=["test", "--tests", "MyTest"]) -> Searches for and runs 'MyTest' in all projects.

2. Absolute Task Paths (Targeted)

Providing a path with a leading colon targets a single specific project.

• Root Project Only: gradle(commandLine=[":test", "--tests", "MyTest"])
• Subproject Only: gradle(commandLine=[":app:test", "--tests", "MyTest"])

When to Use

• Targeted Test Execution: When you need to run specific tests or suites using precise filters (like --tests) to minimize feedback loops.
• Rapid Failure Isolation: When a build has failed and you need high-resolution diagnostics, including stdout/stderr and detailed stack traces.
• Large-Scale Suite Management: When running extensive test suites that benefit from managed background execution and real-time progress monitoring.

Workflows

Running Specific Tests

1. Identify the project path (e.g., :app) and the test filter (e.g., com.example.MyTestClass*).
2. Call gradle with commandLine including --tests.
3. If the tool reports failures, review the included console output.

Investigating Failures

1. Identify the BuildId from the result.
2. Use inspect_build(buildId=ID, testOutcome="FAILED") to list all failed tests.
3. CRITICAL: Use inspect_build(buildId=ID, mode="details", testName=TNAME) to see the full output and stack trace for a specific test.

• DO NOT use taskPath or captureTaskOutput for this.
• Per-test output is authoritative, isolated, and contains full stack traces that are often omitted from the task console.

Examples

Run a single test class in a specific subproject

{
  "commandLine": [":module-a:test", "--tests", "com.example.service.MyServiceTest"]
}
// Reasoning: Using an absolute task path and exact class filter for the fastest possible feedback loop.

List all failed tests in a build

{
  "buildId": "build_20240301_130000_def456",
  "testOutcome": "FAILED"
}

// Reasoning: Using inspect_build to isolate only the failures from a large test suite.

### Look up details for a specific failed test
```json
{
  "buildId": "build_20240301_130000_def456",
  "mode": "details",
  "testName": "com.example.a.MyTest.shouldFail"
}

// Reasoning: Retrieving the full stack trace and isolated stdout/stderr for a specific failure.

## Troubleshooting

- **Missing environment variables**: Set `invocationArguments: { envSource: "SHELL" }` if Gradle cannot find expected env vars (e.g., `JAVA_HOME`).

## Resources

- [Test Diagnostics](./references/test_diagnostics.md)