mirror of
https://github.com/KRTirtho/spotube.git
synced 2026-08-05 19:59:51 +00:00
381 lines
9.8 KiB
Markdown
381 lines
9.8 KiB
Markdown
# query_build Diagnostics Reference
|
|
|
|
Comprehensive guide to inspecting build results, diagnosing failures, and monitoring progress with `query_build` and `wait_build`.
|
|
|
|
## Quick Reference
|
|
|
|
| Goal | Tool Call |
|
|
|--------------------------|--------------------------------------------------------------------------------|
|
|
| See recent/active builds | `query_build()` |
|
|
| Build-level summary | `query_build(buildId="ID")` |
|
|
| Specific failure | `query_build(buildId="ID", kind="FAILURES", query="F0")` |
|
|
| Specific problem | `query_build(buildId="ID", kind="PROBLEMS", query="P1")` |
|
|
| Task output | `query_build(buildId="ID", kind="TASKS", query=":app:compileJava")` |
|
|
| List failed tests | `query_build(buildId="ID", kind="TESTS", outcome="FAILED")` |
|
|
| Per-test stack trace | `query_build(buildId="ID", kind="TESTS", query="com.example.MyTest.myMethod")` |
|
|
| Console logs (regex) | `query_build(buildId="ID", kind="CONSOLE", query="ERROR")` |
|
|
| Full export to file | `query_build(buildId="ID", kind="CONSOLE", outputFile="path/to/logs.txt")` |
|
|
| Wait for log pattern | `wait_build(buildId="ID", timeout=60, waitFor="Started")` |
|
|
| Wait for task | `wait_build(buildId="ID", timeout=120, waitForTask=":app:assemble")` |
|
|
| Wait for finish | `wait_build(buildId="ID", timeout=600)` |
|
|
|
|
---
|
|
|
|
## 1. Build Dashboard (`query_build()`)
|
|
|
|
Call `query_build()` with no arguments to see the **Build Dashboard** — a list of active background builds and recently completed builds with `BuildId`, status, and failure counts. Use this to discover valid `BuildId`s and ensure no
|
|
orphaned background builds are consuming resources.
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Build Summary (`query_build(buildId="ID")`)
|
|
|
|
Provide a `buildId` to get a structured summary of that specific build, including:
|
|
|
|
- Overall build status (SUCCESS, FAILED, etc.)
|
|
- Failure IDs and descriptions
|
|
- Problem IDs and descriptions
|
|
- Test result counts (passed, failed, skipped, etc.)
|
|
|
|
The summary includes a guide on how to inspect specific details using the appropriate `kind`.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Failure Inspection (`kind="FAILURES"`)
|
|
|
|
Inspect a specific build failure to see the full error message and stack trace. Find failure IDs (`F0`, `F1`, etc.) in the build summary. If you provide a unique prefix instead of the exact ID, the tool auto-resolves it.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "FAILURES",
|
|
"query": "F0"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Problem Inspection (`kind="PROBLEMS"`)
|
|
|
|
Inspect a specific compilation or configuration problem. Find problem IDs (`P0`, `P1`, etc.) in the build summary. Provides file locations, error messages, and suggestions where available.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "PROBLEMS",
|
|
"query": "P1"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Task Output Inspection (`kind="TASKS"`)
|
|
|
|
If the failure is task-related, check the isolated output of a specific task. Supports prefix matching on the task path.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "TASKS",
|
|
"query": ":app:compileJava"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Test Inspection (`kind="TESTS"`)
|
|
|
|
### Listing Failed Tests (Summary Mode)
|
|
|
|
Quickly see which tests failed without being overwhelmed by logs:
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "TESTS",
|
|
"outcome": "FAILED"
|
|
}
|
|
```
|
|
|
|
### Getting Detailed Test Output (Details Mode)
|
|
|
|
**CRITICAL**: Always use `kind="TESTS"` and `query` to see the complete stdout, stderr, and stack trace for a specific test. Supports unique prefix matching on the test name.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "TESTS",
|
|
"query": "com.example.MyTest.testMethod"
|
|
}
|
|
```
|
|
|
|
### Individual Test Case vs. Task Output
|
|
|
|
**DO NOT** use `taskPath` or `captureTaskOutput` for investigating specific test failures:
|
|
|
|
- **Task output** is the aggregated log of the entire test process. It is often truncated, interleaved, and lacks the full stack traces and per-test isolation needed for debugging.
|
|
- **Individual test output** (retrieved via `query`) is authoritative, includes full stdout/stderr for just that test case, and provides the complete stack trace for any failure.
|
|
|
|
### Filtering by Name
|
|
|
|
Use `query` with summary mode to see all executions of a test across different projects or iterations:
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "TESTS",
|
|
"query": "MyTest"
|
|
}
|
|
```
|
|
|
|
### Monitoring Test Progress
|
|
|
|
While a build is running, progress notifications provide real-time counts of passed, failed, and skipped tests. Call `query_build(buildId="ID")` repeatedly to see updated test counts: `(5 passed, 1 failed)`.
|
|
|
|
### Pagination for Large Test Suites
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "TESTS",
|
|
"pagination": {
|
|
"limit": 50,
|
|
"offset": 0
|
|
},
|
|
"query": "com.example.service"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Console Log Inspection (`kind="CONSOLE"`)
|
|
|
|
If structured reports are insufficient, examine the raw console output. Use `query` as a regex filter.
|
|
|
|
### Head (first N lines)
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "CONSOLE",
|
|
"pagination": {
|
|
"limit": 100,
|
|
"offset": 0
|
|
}
|
|
}
|
|
```
|
|
|
|
### Tail (last N lines)
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "CONSOLE",
|
|
"pagination": {
|
|
"limit": 100
|
|
}
|
|
}
|
|
```
|
|
|
|
### Filtered by Regex
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "CONSOLE",
|
|
"query": "ERROR|FAILURE"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Progress Monitoring (`wait_build`)
|
|
|
|
Use `wait_build` with `timeout`, `waitFor`, or `waitForTask` to block until a condition is met in a background build.
|
|
|
|
### Waiting for a Log Message
|
|
|
|
The most common pattern for background builds (dev servers) is waiting for a specific readiness message:
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"timeout": 60,
|
|
"waitFor": "Started Application"
|
|
}
|
|
```
|
|
|
|
### Waiting for Task Completion
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"timeout": 120,
|
|
"waitForTask": ":app:assemble"
|
|
}
|
|
```
|
|
|
|
### Waiting for Build Completion
|
|
|
|
If `timeout` is set without a wait condition, the tool waits for the build to finish:
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"timeout": 600
|
|
}
|
|
```
|
|
|
|
### Handling Timeouts
|
|
|
|
If a build takes longer than the `timeout` value, `wait_build` returns the current status. You can call it again with a new timeout.
|
|
|
|
### Continuous Builds
|
|
|
|
For continuous builds, wait for the "Waiting for changes" message after the first build completes:
|
|
|
|
```json
|
|
// Start
|
|
{ "commandLine": ["build", "--continuous"], "background": true }
|
|
|
|
// Wait
|
|
{ "buildId": "BUILD_ID", "timeout": 120, "waitFor": "Waiting for changes" }
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Full Export (`outputFile`)
|
|
|
|
Use `outputFile="path/to/file.txt"` to write the entire result to a file. This bypasses pagination limits and reduces token usage. Works with all `kind` values.
|
|
|
|
```json
|
|
{
|
|
"buildId": "BUILD_ID",
|
|
"kind": "CONSOLE",
|
|
"outputFile": "C:/temp/build_output.txt"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Diagnostic Workflow
|
|
|
|
When a build fails, follow this structured approach:
|
|
|
|
### Step 1: Get the Build Summary
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID" }
|
|
```
|
|
|
|
Provides the high-level overview: failures, problems, and failed tests.
|
|
|
|
### Step 2: Inspect Failures
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "FAILURES", "query": "F0" }
|
|
```
|
|
|
|
### Step 3: Inspect Problems
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "PROBLEMS", "query": "P1" }
|
|
```
|
|
|
|
### Step 4: Check Task Outputs
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "TASKS", "query": ":app:compileJava" }
|
|
```
|
|
|
|
### Step 5: Check Test Failures
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "TESTS", "outcome": "FAILED" }
|
|
```
|
|
|
|
Then drill into each failed test:
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "TESTS", "query": "com.example.MyTest.shouldWork" }
|
|
```
|
|
|
|
### Step 6: Fall Back to Console Logs
|
|
|
|
```json
|
|
{ "buildId": "BUILD_ID", "kind": "CONSOLE", "pagination": { "limit": 100 } }
|
|
```
|
|
|
|
---
|
|
|
|
## 11. Build Failures vs. Test Failures
|
|
|
|
Sometimes a test run fails because the build itself failed (compilation error, configuration error, task dependency failure), not because a test failed.
|
|
|
|
1. Check the build summary: `query_build(buildId="ID")`.
|
|
2. If failures or problems are listed, inspect them directly via `kind="FAILURES"` or `kind="PROBLEMS"`.
|
|
3. If the build failed but no tests are reported, focus on build-level failures and problems.
|
|
|
|
---
|
|
|
|
## 12. Common Failure Scenarios
|
|
|
|
### Compilation Errors
|
|
|
|
- Look for problems with the specific `severity: ERROR` in the build summary.
|
|
- Check `kind="PROBLEMS"` for file location and error details.
|
|
|
|
### Dependency Resolution Issues
|
|
|
|
- Check `kind="FAILURES"` for messages like "Could not resolve all dependencies".
|
|
- Use `inspect_dependencies` to investigate the dependency graph.
|
|
|
|
### Task Execution Failures
|
|
|
|
- Check `kind="TASKS"` to see which task failed and its output.
|
|
|
|
### Build Script Errors
|
|
|
|
- Usually appear in the `kind="FAILURES"` section with a stack trace and line reference.
|
|
|
|
### Assertion Failures
|
|
|
|
- Check `kind="TESTS"` with the specific test `query` for expected vs. actual values.
|
|
|
|
### Timeouts
|
|
|
|
- Tests that time out may be marked as ERROR or FAILED. Check console output for "Timeout" messages.
|
|
|
|
### Infrastructure Issues
|
|
|
|
- If many tests fail with similar errors (`NoClassDefFoundError`, `DatabaseConnectionException`), check build-level failures and problems.
|
|
|
|
---
|
|
|
|
## 13. Stopping Background Builds
|
|
|
|
Always stop background builds when they are no longer needed:
|
|
|
|
```json
|
|
{
|
|
"stopBuildId": "BUILD_ID"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 14. Foreground vs. Background Identity
|
|
|
|
Monitoring a background build using `query_build` or `wait_build` provides exactly the same rich diagnostic data as a foreground build, including progressive disclosure. The difference is control flow: background allows non-blocking work
|
|
while the build proceeds; foreground blocks until completion.
|