Skip to content
Back to skills

Unit

ASecurity

Unit tests — hermetic, fast, handler-level tests using generated mocks.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
ai-agentsgobashtestingdebuggingdatabasefrontend

Works with

  • cli

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill unit --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Unit?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Unit
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-unit/badge)](https://www.skillsdirectory.com/skills/reliant-labs-unit)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: unit
description: "Unit tests — hermetic, fast, handler-level tests using generated mocks."
---

# Unit Tests

## Principles

Unit tests are **hermetic**: no network, no database, no filesystem. They test a single handler or function in complete isolation using generated mocks for all contract dependencies.

## Running

```bash
task test:short -- ./internal/handlers/<name>/...  # inner loop: after each edit
task test                  # all unit tests + frontends, race on: before you finish
task test -- ./internal/handlers/<name>/...      # full lane for one service
task test -- -v ./...                    # verbose output for debugging
```

Iterate on `task test:short`, scoped to what you touched: it is `-short`,
cached, and race-free, so an unchanged package costs nothing. Don't add
`-count=1` or `-race` to it — those belong to `task test` and CI.

## Test Naming Convention

Follow the pattern: `TestHandlerName_Scenario_ExpectedOutcome`

```go
func TestCreateUser_DuplicateEmail_ReturnsAlreadyExists(t *testing.T) { ... }
func TestGetOrder_NotFound_ReturnsNotFoundError(t *testing.T) { ... }
```

## Table-Driven Tests

Use table-driven tests for edge cases — this is idiomatic Go:

```go
tests := []struct {
    name    string
    input   *pb.Request
    wantErr connect.Code
}{
    {"empty name", &pb.Request{Name: ""}, connect.CodeInvalidArgument},
    {"valid",      &pb.Request{Name: "ok"}, 0},
}
for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) { ... })
}
```

## Using Generated Mocks

Dependencies are defined as interfaces in your handler contracts. Mock implementations are generated in `mock_gen.go` files — don't hand-write stubs when the contract mock already exists. Inject them during test setup, never construct real clients.

**Mock collaborators, never the subject.** Mock the handler's *dependencies*; the handler itself stays real. A unit test that stubs the thing it claims to test asserts only that your mock returned what you told it to.

For the table-driven scaffolding around these mocks (terse construction, RPC case tables, authed contexts), use the `pkg/tdd` + `pkg/testkit` helpers rather than wiring it by hand — see `testing/patterns`.

## Testing Error Paths

Always verify the correct Connect error code is returned, not just that an error occurred:

```go
_, err := handler.CreateUser(ctx, req)
require.Error(t, err)
assert.Equal(t, connect.CodeInvalidArgument, svcerr.Code(err))
```

Read the code with `svcerr.Code`, not `connect.CodeOf`. A test calls the handler directly, so the svcerr interceptor never runs: a handler returning a bare kind (`return nil, svcerr.PermissionDenied("admin only")`) hands the test no `*connect.Error`, and `connect.CodeOf` reads it as `Unknown`. `svcerr.Code` is the code the client is sent — it reads a `*connect.Error` exactly as `connect.CodeOf` does, and a bare kind as the interceptor will wrap it.

## Rules

- **Don't test generated code** in `gen/` — it's regenerated and not your logic
- **Don't `t.Skip()` failing tests** without linking an issue reference in the skip message
- **Don't over-mock** — if you're mocking 5+ dependencies, the unit is too big

## Common Pitfalls

- **Testing mocks instead of code** — asserting that your mock returned what you told it to
- **Over-mocking** — mocking things that are fast and deterministic; just use the real thing
- **Assertions that always pass** — e.g., checking `err != nil` when the mock can't fail

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.