Testing the Java SDK
Run ./mvnw test for the strict compile and the conformance suites that replay the Python reference's recorded behaviour; run the live suites only against a test tenant.
Overview
Relevant for Developers maintaining or extending the SDK
The Java SDK isn't trusted on its own word. The Python reference SDK is verified live against a real tenant and exports conformance vectors: the exact request it sends for every op, its core decisions, and recorded traces of every helper and semantic flow. The Java suites replay all of them and must match byte for byte. A live suite then checks transport, auth and TLS against the tenant.
Run the suites
Relevant for Developers before every commit
./mvnw -B test # -Xlint:all -Werror, doclint, every conformance suite
./mvnw -B javadoc:javadoc # Javadoc with doclint=all
ALERTOPS_DOTENV=path/to/.env ./mvnw -B -Plive test # live smoke and semantic blueprint
| Suite | Class | What it proves |
| Requests | RequestsConformanceTest | Every op (802 public + 30 internal) sends Python's exact method, URL, query, auth header and body. |
| Core | CoreConformanceTest | Error parsing, status → error class, retry decisions, every paginator's page sequence, envelopes and .env parsing. |
| Flows | FlowsConformanceTest | All 247 helper traces: the same requests in the same order, then the same result or error. |
| Functions | FunctionsConformanceTest | 109 pure helpers and the Python semantics they rely on (str(), json.dumps, quote, title case …). |
| Semantic | SemanticConformanceTest | 58 planner vectors and 35 executor traces. |
| Drift | DriftTest | The generated code, the vendored spec and its lock hash agree, and no helper is a stub. |
| Live | LiveSmokeTest, LiveSemanticTest | Real tenant: auth, error mapping, pagination, ingest-to-close, blueprint apply, verify and rollback. |
Update after a reference change
Relevant for Developers syncing with the Python reference
- In alertops-python, run python tools/export_spec.py (it re-derives sdk-spec/ from the Python SDK).
- Run python tools/sync_spec.py (it copies the bundle into every language repo).
- Run python tools/codegen/run.py java (it regenerates src/main/java/com/alertops/sdk/generated/ and docs/REFERENCE.md).
- Run ./mvnw -B test. A failing vector means the Java core or a helper no longer matches Python. Fix it until the suite is green.
Never edit the generated package
Those files are produced from the spec and from the helper signatures, and carry a DO NOT EDIT header with the spec hash. Regenerate after you change a helper's signature. The drift test fails if the files are edited or stale.
Live testing rules
Relevant for Anyone running the live suites
- Run them only against a test tenant.
- Every object is named sdktest-java…, users are @example.com, and everything is deleted in reverse order, even when a step fails.
- Leftovers can be listed and removed with alertops-python's python tools/sweep.py --prefix sdktest-java.
Live coverage
Relevant for Anyone checking how much was verified against the tenant
The live tests record every HTTP exchange as {"id": op id, "status": …} lines in target/live-events/*.jsonl. Separately, the cross-language replay repeats every safe GET the Python live suite made through the generated Java methods. It writes java-results.json next to the replay file:
ALERTOPS_REPLAY_FILE=<dir>/replay.json ALERTOPS_DOTENV=path/to/.env ./mvnw -q -B -Preplay test-compile exec:exec
Both feed the cross-language coverage report (alertops-python's tools/sdk_coverage.py). The report classifies every op:
- live: the Java SDK got a 2xx.
- parity: Python got a 2xx live, and Java sends the identical request.
- exempt: no live 2xx is possible, for a documented reason.
Troubleshooting
Relevant for Anyone whose suite fails
DriftTest.vendoredSpecMatchesItsLock fails
- The sdk-spec/ copy was edited or has CRLF line endings. Copy the bundle again. The repo pins LF in .gitattributes.
A flow vector fails with "made more requests than Python"
- The Java helper calls an extra endpoint, or misses an early return. Compare it line by line with the Python flow named in the vector.
Live tests fail with "Unable to establish loopback connection"
- The JDK's HttpClient could not bind its AF_UNIX socket in the temp directory. The Maven test and replay runs set -Djdk.net.unixdomain.tmpdir=target. Do the same in your own JVM.
Related Articles
- Getting Started with the AlertOps Java SDK
- Calling the API from Java
- Helpers and the Semantic Layer in Java
Need help?
Email support@alertops.com or contact your AlertOps representative.