henriqueatila/golang-gin-best-practices / skills/golang-gin-testing
golang-gin-testing
VerifiedTest Go Gin APIs with httptest, table-driven tests, testcontainers. Use when writing tests for Gin handlers, services, middleware, or setting up integration and e2e tests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.7 KB |
| metadata.json | config | 495 B |
| references/e2e-cicd-config-and-cleanup.md | markdown | 5.1 KB |
| references/e2e-structure-and-critical-flow.md | markdown | 6.9 KB |
| references/integration-tests-api-migrations-and-fixtures.md | markdown | 3.6 KB |
| references/integration-tests-cleanup-and-repository.md | markdown | 5.8 KB |
| references/integration-tests-setup-and-testmain.md | markdown | 4.3 KB |
| references/load-testing-benchmarks-and-vegeta.md | markdown | 2.1 KB |
| references/load-testing-k6-and-ci-regression.md | markdown | 3.1 KB |
| references/test-patterns-helpers-and-handler-tests.md | markdown | 4.8 KB |
| references/test-patterns-service-tests-and-running.md | markdown | 2.8 KB |
| references/unit-tests-benchmarks-fuzz-and-golden.md | markdown | 5.1 KB |
| references/unit-tests-fixtures-helpers-and-middleware.md | markdown | 4.7 KB |
| references/unit-tests-handler-and-json.md | markdown | 5.8 KB |
| references/unit-tests-service-mocks-and-table-driven.md | markdown | 5.6 KB |
references/unit-tests-benchmarks-fuzz-and-golden.md
View on GitHub# Unit Tests — Benchmarks, Fuzz Tests, Golden Files, Organization, and Testify
## Benchmark Tests
Use `Benchmark*` with `httptest` to measure handler throughput. Run with `go test -bench=. -benchmem ./...`.
```go
func BenchmarkUserHandler_GetByID(b *testing.B) {
svc := &mockUserService{getByIDFn: func(_ context.Context, id string) (*domain.User, error) {
return &domain.User{ID: id, Name: "Alice", Email: "alice@example.com", Role: "user"}, nil
}}
router := setupUserRouter(svc)
b.ReportAllocs(); b.ResetTimer()
for b.Loop() {
w := httptest.NewRecorder()
req, _ := http.NewRequest(http.MethodGet, "/users/user-123", nil)
router.ServeHTTP(w, req)
if w.Code != http.StatusOK { b.Fatalf("unexpected status %d", w.Code) }
}
}
func BenchmarkUserHandler_GetByID_Parallel(b *testing.B) {
// same setup...
b.ReportAllocs(); b.ResetTimer()
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
w := httptest.NewRecorder()
req, _ := http.NewRequest(http.MethodGet, "/users/user-123", nil)
router.ServeHTTP(w, req)
}
})
}
```
```bash
go test -bench=BenchmarkUserHandler_GetByID -benchtime=5s -benchmem ./internal/handler/...
go test -bench=. -benchmem -count=5 ./... > before.txt && benchstat before.txt after.txt
```
---
## Fuzz Tests
Go 1.18+ native fuzzing finds edge cases in input parsing that table-driven tests miss.
```go
// go test -fuzz=FuzzUserHandler_Create ./internal/handler/... (local fuzzing)
// go test ./internal/handler/... (seed corpus only, CI-safe)
func FuzzUserHandler_Create(f *testing.F) {
f.Add(`{"name":"Alice","email":"alice@example.com","password":"secret123"}`)
f.Add(`{"name":"","email":"bad-email","password":"x"}`)
f.Add(`{}`); f.Add(`not-json`); f.Add(`{"name":null,"email":null}`)
svc := &mockUserService{createFn: func(_ context.Context, req domain.CreateUserRequest) (*domain.User, error) {
return &domain.User{ID: "fuzz-id", Name: req.Name, Email: req.Email, Role: "user"}, nil
}}
router := setupUserRouter(svc)
f.Fuzz(func(t *testing.T, body string) {
req := httptest.NewRequest(http.MethodPost, "/users", strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
w := httptest.NewRecorder()
router.ServeHTTP(w, req)
if w.Code == http.StatusInternalServerError {
t.Errorf("handler returned 500 for input %q; body: %s", body, w.Body)
}
})
}
```
Rules: seed corpus must include valid + edge-case inputs; no non-determinism (no random, no time); found crash inputs auto-saved to `testdata/fuzz/FuzzX/`.
---
## Golden File / Snapshot Testing
Captures expected output as a file. On subsequent runs, output is compared to the stored file.
```go
var update = flag.Bool("update", false, "update golden files")
func TestUserResponse_Golden(t *testing.T) {
user := domain.User{ID: "test-id", Email: "test@example.com", Name: "Test User"}
body, err := json.MarshalIndent(user, "", " ")
require.NoError(t, err)
golden := filepath.Join("testdata", t.Name()+".golden")
if *update { os.MkdirAll("testdata", 0o755); os.WriteFile(golden, body, 0o644) }
expected, err := os.ReadFile(golden)
require.NoError(t, err)
assert.JSONEq(t, string(expected), string(body))
}
```
First run: `go test ./... -update` writes the golden file. Commit it — diffs surface unintended response changes. Re-run with `-update` when the shape intentionally changes.
---
## Test Organization
**Same-package** (`package service`) — white-box: access unexported identifiers, verify internal state.
**External-package** (`package handler_test`) — black-box: only exported API visible; prevents coupling to internals. Use for handlers, middleware, repositories.
**Build tags:**
```go
//go:build integration // top of file, before package declaration
// Excluded from: go test ./...
// Included in: go test -tags=integration ./...
```
Use `//go:build integration` for Docker/network tests; `//go:build e2e` for full E2E. Keeps `go test ./...` fast.
---
## Testify as an Alternative
```go
// Standard library
if got.Email != "alice@example.com" { t.Errorf("want email 'alice@example.com', got %q", got.Email) }
if err != nil { t.Fatalf("unexpected error: %v", err) }
// testify/assert — non-fatal, test continues
assert.Equal(t, "alice@example.com", got.Email); assert.NoError(t, err)
// testify/require — fatal, stops immediately (equivalent to t.Fatalf)
require.NoError(t, err); require.Equal(t, "alice@example.com", got.Email)
```
| Package | Behavior | Use when |
|---------|----------|----------|
| `assert` | non-fatal | checking multiple independent fields |
| `require` | fatal | precondition must hold for rest of test |
`require.NoError(t, err)` before accessing the result is the most common pattern.
> For handler testing: see [unit-tests-handler-and-json.md](unit-tests-handler-and-json.md).
> For service mocks and table-driven tests: see [unit-tests-service-mocks-and-table-driven.md](unit-tests-service-mocks-and-table-driven.md).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |