| name | advanced-verification |
| description | Build the APIHub backend, start it locally with local_config, author or extend a Postman/Newman E2E collection under tests/api covering the change, run it, and analyze and fix failures. Use after implementing a non-trivial backend change, before finishing the task, to verify it end-to-end against a real running instance. |
Advanced Verification
Verifies a backend change end-to-end against a real local instance: build, run, hit real HTTP
endpoints via a Postman/Newman collection stored in tests/api, and iterate on failures.
Complements, does not replace, postman-e2e-followup — that skill only reminds about follow-up
in the external qubership-apihub-postman-collections repo. This skill runs in-repo
verification only. For commands, config recipes, and a full collection example, see
reference.md.
When to use
Only for changes with an HTTP-observable effect: new/changed endpoint, altered response/status
codes, changed validation, or a migration that affects API behavior. Skip for pure refactors
with no behavior change.
Workflow
-
Author or extend the Postman collection in tests/api/<slug>.postman_collection.json,
following the structure (collection
description with purpose/endpoints/auth, variable[] block with baseUrl/apiKey
defaulting to the local zero-day token, numbered folders, pm.test assertions,
Date.now()-suffixed throwaway IDs for isolation). Extend an existing collection instead of
creating a duplicate when one already targets the same feature area.
-
Check Postgres is reachable at localhost:5432 (matches
qubership-apihub-service/local_config/config.yaml). If unreachable, stop and ask the
user whether to start it via the local docker-compose DB stack or point to another
instance — do not start containers unprompted.
-
Build: go build . from qubership-apihub-service/ (do not force
GOOS=linux/GOARCH=amd64 — that's only for the container build script).
-
Start locally with local_config: set APIHUB_CONFIG_FOLDER to
qubership-apihub-service/local_config and run the built binary from
qubership-apihub-service/. Default listen address is :8090. There is no env-var override
for config values in this codebase — if the port is occupied, do not edit the committed
local_config/config.yaml; copy it to a scratch directory, edit
technicalParameters.listenAddress in the copy, and point APIHUB_CONFIG_FOLDER at the copy
for that run only. The zeroDayConfiguration.accessToken in local_config/config.yaml is
auto-provisioned as a sysadm api-key at startup — no login flow needed.
-
Run the collection with Newman against the running instance.
-
Analyze failures, map them back to the relevant Go source, and fix root causes per
AGENTS.md error-handling rules — no swallowing or masking. Rebuild, restart, and rerun.
Iterate until the collection passes.
-
Stop the local service when done; keep any temporary config copy out of git.
-
Note in the completion summary that postman-e2e-followup is a separate, external-repo
concern — running this skill does not replace that reminder.
