Testing the Go SDK

Overview

Relevant for Developers maintaining or extending the SDK

The Go 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 Go 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

gofmt -l . && go vet ./... && go test ./...                          # format, vet, conformance
ALERTOPS_DOTENV=path/to/.env go test -tags live -run TestLive -v    # live smoke and semantic blueprint

Suite	File	What it proves
Requests	requests_test.go	Every op (802 public + 30 internal, 2036 vectors) sends Python's exact method, URL, query, auth header and body.
Core	core_test.go	Error parsing, status → error class, retry decisions, every paginator's page sequence, envelopes and .env parsing.
Flows	flows_test.go	All 247 helper traces: the same requests in the same order, then the same result or error.
Functions	functions_test.go	109 pure helpers and the Python semantics they rely on (str(), json.dumps, quote, title case …).
Semantic	semantic_test.go	58 planner vectors and 35 executor traces.
Drift	drift_test.go	The generated code, the vendored spec and its lock hash agree, internal ops and the embedded semantic spec match the bundle, and no helper is a stub.
Live	live_test.go, live_semantic_test.go	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 go (it regenerates generated_*.go and docs/REFERENCE.md).
Run go test ./.... A failing vector means the Go core or a helper no longer matches Python. Fix it until the suite is green.

Never edit the generated files
generated_ops.go, generated_resources.go, generated_semantic_spec.go and docs/REFERENCE.md are produced from the spec and carry a DO NOT EDIT header with the spec hash. The drift test fails if they 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-go…, users are @example.com, and everything is deleted in reverse order, even when a step fails.
Each live test records its HTTP exchanges as {"id", "status"} lines in .live-events/<test>.jsonl.
Leftovers can be listed and removed with alertops-python's python tools/sweep.py --prefix sdktest-go.

Live coverage

Relevant for Anyone checking how much was verified against the tenant

alertops-python's tools/sdk_coverage.py go classifies every op. Its inputs are .live-events/*.jsonl and the go-results.json of a cross-language replay session (go run ./cmd/replay):

live: the Go SDK got a 2xx, from its own live tests or from replaying every safe GET the Python suite made.
parity: Python got a 2xx live, and Go sends the identical request.
exempt: no live 2xx is possible, for a documented reason.

There must be no gaps.

Troubleshooting

Relevant for Anyone whose suite fails

TestVendoredSpecMatchesLock fails

The sdk-spec/ copy was edited or has CRLF line endings. Re-run sync_spec.py. The repo pins LF in .gitattributes.

A flow vector fails with "made more requests than Python"

The Go helper calls an extra endpoint, or misses an early return. Compare it line by line with the Python flow named in the vector.

Need help?

Email support@alertops.com or contact your AlertOps representative.