Testing
Two kinds of tests
| Unit | Integration | |
|---|---|---|
| Lives | next to the code (package product) |
the module’s external package (package product_test) or internal/app |
| Uses | fakes for repositories and collaborators | a real Postgres schema, the real router |
| Needs | nothing | DATABASE_TEST_DSN — skipped without it |
| Run | make test / go test ./... |
make test-integration |
export DATABASE_TEST_DSN="postgres://postgres:postgres@127.0.0.1:5432/ims_go_api_test?sslmode=disable"go test -count=1 ./... # everythinggo test -count=1 -race -p 2 ./... # race detector (needs cgo; -p 2 keeps memory down)go test -count=1 -run TestProducts -v ./internal/modules/product/A skipped test is not a passing test
Without DATABASE_TEST_DSN integration tests skip and report ok. Run with -v to confirm
a new test actually ran.
Integration tests with testkit
internal/testkit gives you the fully wired application on a fresh, migrated, seeded schema —
like a Laravel feature test:
func TestBranchCreate(t *testing.T) { app := testkit.New(t) // clean schema, seeded, router built admin := app.User(t) // Admin of the seeded tenant, signed in
app.As(admin).Post("/api/v1/branch", `{"name":"Dhaka"}`).Status(t, http.StatusCreated)
viewer := app.User(t, testkit.Role(app.Role(t, "Viewer", "branch.view.all"))) app.As(viewer).Post("/api/v1/branch", `{"name":"Sylhet"}`).Status(t, http.StatusForbidden)}| Helper | Gives you |
|---|---|
testkit.New(t, opts...) |
the app; empties every table first (WithLogger to see logs) |
app.User(t, opts...) |
a signed-in user — Admin of the seeded tenant by default |
testkit.Role(name), testkit.InTenant(id), testkit.Email(e), testkit.Name(n) |
user options |
app.Role(t, name, perms...) |
a tenant role with exactly those permissions |
app.Tenant(t, name) |
another tenant (with a default branch, on an unlimited plan) |
app.SuperAdmin(t) |
the seeded super admin |
app.DefaultBranch(t, tenantID) |
a tenant’s default branch id |
app.As(u) / app.Guest() |
a request client |
.InTenant(tenantID, branchID) |
acting headers, for platform accounts |
.Header(k, v) |
any header |
.Get/Post/Patch/Put/Delete(path, body) |
body is a string or any value (JSON-encoded) |
.Status(t, code) |
asserts the status (prints the body on failure) |
.Data(t, &v) / .JSON(t, &v) |
decodes data / the whole body |
app.Deps, app.Pool, app.Config |
everything else |
Testkit tenants sit on an unlimited plan so quotas never get in the way. To test a limit,
create a package and assign it — see internal/app/quota_concurrency_integration_test.go.
Every module needs an isolation test
other := app.User(t, testkit.InTenant(app.Tenant(t, "Tenant B")))path := fmt.Sprintf("/api/v1/product/%d", id)app.As(other).Get(path).Status(t, http.StatusNotFound)app.As(other).Patch(path, `{"name":"x"}`).Status(t, http.StatusNotFound)app.As(other).Delete(path).Status(t, http.StatusNotFound)How test databases work
dbtest gives every test package its own Postgres schema (named after the package directory)
with the goose and River migrations applied once. Packages run in parallel against one database
without stepping on each other. Inside a package, testkit.New truncates the application tables,
so tests within one package must not use t.Parallel().
For repository-level tests without the whole app: dbtest.Queries(t) and
dbtest.Clean(t, pool, "table", ...).
Unit tests with fakes
Services take interfaces, so unit tests swap in fakes:
type fakeRepo struct{ created []product.CreateInput }
func (f *fakeRepo) Create(_ context.Context, in product.CreateInput) (*product.Product, error) { f.created = append(f.created, in) return &product.Product{ID: 1, TenantID: in.TenantID}, nil}Optional collaborators are nil-safe (activity.Recorder, notifiers), so a unit test only
provides what it exercises.
Safety nets that run in CI
| Test | Guards |
|---|---|
route_permissions_integration_test.go |
every protected route refuses a permissionless token |
tenancy_isolation_integration_test.go |
cross-tenant reads and writes answer 404 |
platform_wiring_test.go |
every shared service is wired (no surprise 503s) |
quota_concurrency_integration_test.go |
plan limits hold — and nothing deadlocks — under concurrent creates |
cachetest contract suite |
every cache driver behaves the same |
openapi-check |
the spec matches the router |
gen-check |
sqlc, OpenAPI and docs output is committed and current |
Before you push
make check # gofmt + vet + golangci-lint + unit testsmake test-integration # with DATABASE_TEST_DSNmake gen-check # generated code is currentmake openapi-check # contract matches the router