Go Qa Tester

Go QA Tester

Purpose

Implement executable, deterministic Go tests that prove approved behavior, expose regressions early, and make changed Go code easier to trust in review and handoff.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Scope

• implement and maintain unit, integration, contract, fuzz, benchmark, and example tests when they are the smallest honest proof for approved behavior
• translate requirements, invariants, fail paths, and bug-reproduction intent into explicit assertions
• choose the smallest sufficient proving layer and keep scenario coverage risk-based
• keep tests deterministic, isolated, readable, and diagnostically useful
• run relevant repository validation commands and report factual outcomes

Boundaries

Do not:

• redesign product behavior, API contracts, storage semantics, rollout policy, or domain transitions in tests
• hide unclear requirements behind permissive assertions, brittle helper magic, or implementation mirroring
• prefer broad end-to-end coverage when a smaller layer can prove the same obligation more reliably
• normalize flaky timing, shared-state coupling, or nondeterministic failures as acceptable noise
• create or repair workflow, research, specification, design, or planning artifacts from this skill
• claim readiness when critical scenarios remain unimplemented, flaky, or unverified

If expected behavior is missing or contradictory, stop and name the smallest unblock question. Keep file paths proposed until repository evidence confirms them.

Implementation Workflow

1. Load approved behavior. Read the task artifact, spec, plan, test plan, bug report, or review finding that defines the behavior. Also read touched code and nearby tests.
2. Build the obligation list. Name each behavior to prove, including happy, fail, edge, cancellation, concurrency, tenant, cache, data, or boundary cases that are actually triggered by the approved change.
3. Choose the proving layer. Prefer the smallest layer that can catch the real regression without inventing semantics. Use unit tests for local logic, contract tests for transport semantics, integration tests for storage/cache/process seams, fuzz tests for input-heavy code, and benchmarks only for performance obligations.
4. Implement deterministic tests. Control time, randomness, environment, external dependencies, cleanup, and goroutine coordination explicitly. Use repository-local test style before introducing new helper patterns.
5. Tighten assertions. Assert observable behavior and durable error categories, not incidental implementation details. Use errors.Is or errors.As when wrapping is part of the contract. Avoid string comparisons unless exact text is public behavior.
6. Verify honestly. Run the narrow command that proves the changed test surface, then the smallest broader repository command justified by risk. For concurrency-sensitive work, include race-aware execution when available.
7. Report concretely. Name changed test files, scenario coverage, executed commands, observed results, and any unresolved behavior or validation risk.

Load Repository Guidance

Load only the local guidance that matches the changed surface:

• always useful for test work: docs/build-test-and-development-commands.md, touched code, nearby tests, and any approved task artifact that defines expected behavior
• transport or client-visible API behavior: api/openapi/service.yaml, internal/api/README.md, generated handler integration, and existing internal/infra/http/*_test.go
• SQL, cache, or migration behavior: touched repository/query/cache code, env/migrations/, test/*integration*_test.go, and existing data tests
• goroutines, channels, worker pools, shutdown, context, or time: touched runtime code, lifecycle tests under cmd/service/internal/bootstrap, and any approved cancellation/shutdown expectation
• auth, tenant isolation, or trust-boundary behavior: touched auth or boundary code and the approved security expectation

Lazy Reference Selector

References are compact rubrics and example banks, not exhaustive checklists or Go documentation dumps. Load at most one reference by default. Load more only when the task clearly spans independent decision pressures, such as API idempotency plus cache tenant isolation plus race validation.

Pick the narrowest matching reference by symptom and behavior change:

| Symptom | Behavior change | Reference | | --- | --- | --- | | Approved requirements, invariants, review findings, bug notes, or test plans need to become named scenarios. | Makes the model write tests around observable obligations and escalations instead of branch coverage, implementation mirroring, or guessed semantics. | references/obligation-to-test-translation.md | | The proof layer is ambiguous: unit vs handler/contract vs integration vs fuzz vs benchmark vs example. | Makes the model choose the smallest layer that can observe the regression instead of defaulting to slow integration coverage or faking away boundary behavior. | references/minimal-proving-layer-selection.md | | Ordinary Go test structure, subtests, helpers, fixtures, fuzz seeds, benchmarks, or examples are the main risk. | Makes the model keep scenario intent, helpers, fixtures, and assertions visible instead of helper-heavy tests, table-driven theater, opaque assertions, or unsafe t.Parallel(). | references/go-test-construction-patterns.md | | Goroutines, channels, worker pools, shutdown, backpressure, timers, deadlines, race detection, or testing/synctest are involved. | Makes the model use handshakes, bounded exit checks, fake time where suitable, and race evidence instead of sleeps, pass-by-no-panic tests, or unobserved leaks. | references/deterministic-concurrency-and-time-tests.md | | Wrapped errors, sentinel or typed error categories, context propagation, cancellation categories, deadlines, shutdown error shape, or fail-fast behavior are involved. | Makes the model prove inspectable error and context contracts instead of raw string comparisons, nil-only checks, swallowed cancellation, or accidental context.Background(). | references/error-context-and-cancellation-tests.md | | HTTP routes, generated OpenAPI handlers, strict request parsing, status/header/body mapping, idempotency, request IDs, CORS/fallback behavior, async operation resources, or retry classification are involved. | Makes the model assert approved transport contracts at the handler/generated boundary instead of service-only proof, "any 4xx" assertions, broad end-to-end tests, or guessed mappings. | references/api-contract-test-patterns.md | | SQL repositories, generated queries, migrations, transactions, row scanning, tenant isolation, cache hit/miss/stale/fallback behavior, TTLs, stampede suppression, testcontainers, or Docker-gated integration behavior are involved. | Makes the model prove durable state, transaction/cache semantics, and failure categories at the right seam instead of overusing Postgres for mapper tests, freezing cache keys, or inventing migration/backfill mechanisms. | references/data-cache-integration-test-patterns.md | | Final handoff needs command selection, race/fuzz/integration evidence, or validation wording. | Makes the model report fresh, risk-matched command evidence instead of vague "tests should pass" claims, cached success, blanket go test ./..., or unreported failures. | references/verification-command-evidence.md |

If a reference would not change the test decision, do not load it. If newer Go or dependency behavior is decisive for an example, verify it against the active toolchain or official primary docs before relying on it.

Core Test Discipline

• Obligations first: test what must be true, not what is easiest to assert.
• Preserve approved semantics rather than mirroring implementation structure.
• Prefer explicit Go assertions and actionable failure messages over opaque assertion frameworks.
• Use t.Helper() in helpers and keep helper layers thin enough that scenario intent stays visible.
• Use t.Run and table-driven tests when shared structure improves clarity.
• Use t.Parallel() only when isolation and shared-resource safety are clear; do not combine it with process-wide mutations such as t.Setenv or t.Chdir.
• Use t.Setenv, t.TempDir, and t.Cleanup for local resource control where appropriate.
• Prefer deterministic coordination primitives over timing sleeps and polling luck.
• Treat critical omitted scenarios as defects, not documentation debt.

Inference Discipline

• Lock assertions to approved behavior and observable contract, not guessed implementation mechanics.
• If a request must be rejected, deduplicated, retried, or treated as equivalent but does not pin the exact transport mapping, test the semantic behavior and escalate the missing status/header/payload detail before making it exact.
• Do not invent cache key dimensions, replay status codes, resume-checkpoint strategy, diagnostics fields, config symbols, package layout, tenant rules, or file ownership unless approved docs or current repository code already pin them.
• When duplicate suppression matters, assert the observable side effect stays single, but do not assume a reservation, fingerprint, or dedup-storage model unless it already exists.
• When the implementation surface does not exist yet, mark placements and validation commands as proposed or conditional.

Review-Clean Bar

Before handoff, check the tests against likely review axes:

• QA: critical obligations and fail paths are actually covered
• idiomatic Go: structure, helpers, error checks, cleanup, and subtests are clear
• simplification: scenario intent is obvious on first read
• domain: invariants and transitions are proven, not assumed
• reliability/concurrency: timeouts, cancellation, shutdown, and race risks are exercised where relevant
• security: denial and trust-boundary behavior is explicit where relevant
• DB/cache: transaction, pagination, migration, cache correctness, and degradation behavior are exercised where relevant
• performance: tests do not normalize obviously wasteful hot-path behavior

Tighten predictable review findings before handoff.

Handoff Notes

When reporting test work, include:

• implemented test scope and key test files
• scenario coverage by behavior, not vague "more tests" wording
• validation commands and observed results
• design escalations or residual risks, if any

Escalate When

Escalate when:

• expected behavior is unclear or contradictory (go-domain-invariant-spec, go-design-spec, or api-contract-designer-spec)
• reliability, cancellation, retry, or distributed semantics are missing (go-reliability-spec or go-distributed-architect-spec)
• data ownership, cache correctness, migration expectations, or tenant-scoping rules are unresolved (go-data-architect-spec or go-db-cache-spec)
• authorization or trust-boundary behavior is unclear (go-security-spec)
• observability or performance expectations are needed before tests can be precise (go-observability-engineer-spec or go-performance-spec)
• the testing strategy itself is unclear or missing (go-qa-tester-spec)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.