go-tdd-patterns
Use this for the Go-specific realization of the SKELETON→RED→GREEN→REFACTOR TDD cycle — interface skeletons returning `errNotImplemented` stubs, table-driven failing tests with `*testing.T` + `t.Run`
SKILL.mdskills/go-tdd-patterns/SKILL.md
GitHubgo-tdd-patterns (v1.0.0)
Scope
Realizes the cycle defined in shared-core tdd-patterns for Go targets. The agent coordination (which agent writes the skeleton, which writes the RED test, etc.) is language-neutral and lives there. Everything below is Go syntax.
SKELETON — compilable stubs that tests can import
// internal/ports/repository.go
package ports
import "context"
// Repository defines persistence operations for an entity.
type Repository[T any] interface {
Create(ctx context.Context, entity *T) (*T, error)
GetByID(ctx context.Context, id string) (*T, error)
}
// internal/application/service.go
package application
import (
"context"
"errors"
)
var errNotImplemented = errors.New("not implemented")
type Service struct {
repo ports.Repository[domain.Entity]
}
func NewService(repo ports.Repository[domain.Entity]) *Service {
return &Service{repo: repo}
}
// CreateEntity creates an entity. STUB — returns not-implemented error.
func (s *Service) CreateEntity(ctx context.Context, cmd CreateEntityCommand) (*domain.Entity, error) {
return nil, errNotImplemented
}
Skeleton rules:
- All exported interfaces fully defined (every method signature)
- All structs have correct fields and tags
- Constructors return real instances
- Method stubs return
nil, errNotImplementedor zero values - Compile-time interface assertion:
var _ ports.Repository[domain.Entity] = (*Impl)(nil)somewhere in the impl package — catches missing methods at build time
RED — assertion-first failing tests
func TestCreateEntity_ValidInput_ReturnsEntityWithID(t *testing.T) {
ctrl := gomock.NewController(t)
defer ctrl.Finish()
mockRepo := mocks.NewMockRepository(ctrl)
mockRepo.EXPECT().
Create(gomock.Any(), gomock.Any()).
DoAndReturn(func(ctx context.Context, e *domain.Entity) (*domain.Entity, error) {
assert.NotEmpty(t, e.ID, "ID should be generated before persistence")
return e, nil
})
svc := application.NewService(mockRepo)
entity, err := svc.CreateEntity(context.Background(), application.CreateEntityCommand{
Name: "test",
})
require.NoError(t, err)
require.NotNil(t, entity)
assert.NotEmpty(t, entity.ID)
}
Conventions:
- Start with what you want to assert; work backward to setup.
requireshort-circuits the test on failure;assertcontinues. Userequirefor preconditions,assertfor behavior verification.gomockcontroller per test;defer ctrl.Finish()(ort.Cleanup(ctrl.Finish)).- Use
gomock.Any()for arguments you don't care about;DoAndReturnto verify shape and return.
RED — table-driven tests
func TestCreateEntity_Validation(t *testing.T) {
tests := []struct {
name string
cmd application.CreateEntityCommand
wantErr bool
errType error // sentinel for errors.Is match
}{
{"empty name", application.CreateEntityCommand{Name: ""}, true, domain.ErrInvalidName},
{"valid", application.CreateEntityCommand{Name: "x"}, false, nil},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
ctrl := gomock.NewController(t)
mockRepo := mocks.NewMockRepository(ctrl)
if !tt.wantErr {
mockRepo.EXPECT().Create(gomock.Any(), gomock.Any()).
Return(&domain.Entity{ID: "e1"}, nil)
}
svc := application.NewService(mockRepo)
_, err := svc.CreateEntity(context.Background(), tt.cmd)
if tt.wantErr {
require.Error(t, err)
if tt.errType != nil {
assert.True(t, errors.Is(err, tt.errType),
"expected %v, got %v", tt.errType, err)
}
} else {
require.NoError(t, err)
}
})
}
}
t.Parallel() inside a subtest opts the subtest into parallel execution. Race-detector friendly when each subtest owns its own gomock.Controller. Don't share state across subtests.
GREEN — implementation rules
After tests are RED, code-generator reads ALL test files and writes the minimum impl to make them pass:
- Read every
*_test.goin the package first - If a test expects a specific sentinel via
errors.Is, return that exact sentinel (or wrap it withfmt.Errorf("...: %w", sentinel)) - If a test asserts a generated UUID is non-empty, generate one (don't return zero-value)
- Run
go test ./... -race -count=1after each significant change - Don't add behavior that isn't tested
Anti-patterns
1. Weak assertions that pass on stubs. func TestX(t *testing.T) { svc.Do(); } — no assertion, passes immediately. Always assert at least one observable outcome.
2. Testing implementation details. mockRepo.EXPECT().Create(gomock.Eq(specificStruct)) — brittle to refactor. Use DoAndReturn to assert behavioral properties of the argument, not exact equality.
3. Skipping error-path tests. Every error path the impl has must have a test that exercises it. If you can't write the test, you don't know the behavior.
Cross-references
- shared-core
tdd-patterns— agent cycle and orchestration (what this skill realizes) go-table-driven-tests— deeper conventions on table layout,t.Cleanup,t.Parallelgo-mock-patterns— gomock vs fake vs stub decision treego-error-handling-patterns— sentinel definition +errors.Isdisciplinego-testing-patterns— broader Go testing toolkit