Refactoring Go API Unit Tests: Breaking Down the Testing Monolith

The Why

While a single-file approach works for small projects, it quickly becomes an anti-pattern due to two major pain points:

• Code Bloating: A single file containing setup, table-driven test cases, and verbose mock definitions quickly grows to thousands of lines, making it incredibly difficult to navigate and maintain.
• Circular Dependencies (Cyclic Imports): In Go, packages cannot import each other transitively. When mocks, domain logic, and HTTP transport layers are tightly coupled in tests, you risk hitting compilation errors because the boundaries between your database, service, and handler packages become blurred.

Separating these concerns ensures that your tests remain clean, compile quickly, and scale alongside your features.

The How

To resolve this, the monolithic test file was refactored into a modular structure by breaking it down into three distinct components: mock.go, *_service_test.go, and *_handler_test.go.

📂 package_test/ ├── 📄 mock.go # Shared mock definitions for service & repository layers ├── 📄 *_service_test.go # Pure business logic unit tests └── 📄 *_handler_test.go # HTTP, routing, and request/response validation tests 

// mock.go type MockAuthService struct { // } func (m *MockAuthService) GenerateToken(userID int64) (string, error) { return "", nil } func (m *MockAuthService) ParseToken(token string) (int64, error) { return 0, nil } func (m *MockAuthService) Login(ctx context.Context, req LoginRequest) (string, error) { return "", nil } func (m *MockAuthService) Register(ctx context.Context, req RegisterRequest) error { return nil } type MockAuthRepository struct { GetUsernameOrEmailFunc func(ctx context.Context, username string) (*models.Users, error) RegisterFunc func(ctx context.Context, user *models.Users) error } func (m *MockAuthRepository) Register(ctx context.Context, user *models.Users) error { if m.RegisterFunc != nil { return m.RegisterFunc(ctx, user) } return nil } func (m *MockAuthRepository) GetUsernameOrEmail(ctx context.Context, username string) (*models.Users, error) { if m.GetUsernameOrEmailFunc != nil { return m.GetUsernameOrEmailFunc(ctx, username) } return &models.Users{}, nil } 

// *_service_test.go var testAuthRepo = &auth.MockAuthRepository{} var testAuthSvc = NewTestAuth(testAuthRepo) func NewTestAuth(testAuthRepo *auth.MockAuthRepository) auth.AuthService { config := &config.Config{JWTSecretKey: "airconcure_jwt_key"} return auth.NewAuthService(testAuthRepo, config) } func TestAuthServiceLogin(t *testing.T) { t.Run("login credentials", func(t *testing.T) { testAuthRepo.GetUsernameOrEmailFunc = func(ctx context.Context, username string) (*models.Users, error) { passwordHash, _ := bcrypt.GenerateFromPassword([]byte("!Abc1234"), bcrypt.DefaultCost) user := &models.Users{ ID: 1, Username: "test_account", Email: "test_account@local.com", Password: string(passwordHash), } return user, nil } req := auth.LoginRequest{ Username: "rdev", Password: "!Abc1234", } _, err := testAuthSvc.Login(context.Background(), req) if err != nil { t.Errorf("Expected no error, got %v", err) } }) } 

// *_handler_test.go var testAuthHandler = auth.NewAuthHandler(&auth.MockAuthService{}) func TestAuthHandlerLogin(t *testing.T) { type loginRequest struct { Username string `json:"username"` Password string `json:"password"` } tests := []struct { name string url string requestBody any expectedStatus int }{ { name: "complete login credentials", url: "/login", requestBody: loginRequest{ Username: "rdev", Password: "!Abc1234", }, expectedStatus: http.StatusOK, }, { name: "login no password", url: "/login", requestBody: loginRequest{ Username: "rdev", Password: "", }, expectedStatus: http.StatusBadRequest, }, { name: "login password less than minimum required", url: "/login", requestBody: loginRequest{ Username: "rdev", Password: "1234", }, expectedStatus: http.StatusBadRequest, }, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { ctx, w := helpers.SetupJSONTestContext(t, http.MethodPost, tt.url, tt.requestBody) testAuthHandler.Login(ctx) if w.Code != tt.expectedStatus { t.Errorf("Login() status = %d, resp = %v, want %d", w.Code, w.Body, tt.expectedStatus) } }) } } 

1. Centralizing Mocks (mock.go)

Instead of rewriting or copy-pasting mock implementations across multiple test files, all repository and service mock structs are declared once inside a dedicated mock.go file within the package. This acts as a single source of truth for test doubles.

2. Testing the Business Logic (*_service_test.go)

This file focuses strictly on testing the “under-the-hood” domain logic. Because the database/repository layer is mocked out via mock.go, these tests run entirely in-memory and are incredibly fast. They validate:

• Data validation rules and edge cases.
• Handling of incorrect data types or malformed payloads.
• Domain-specific error handling and state transitions.

3. Testing the HTTP Transport Layer (*_handler_test.go)

This file is dedicated to verifying how the API interacts with the outside world. It uses Go’s net/http/httptest package to simulate client requests, utilizing the service mocks so it doesn’t trigger actual business logic. These tests validate:

• HTTP status codes (e.g., 200 OK, 400 Bad Request, 429 Too Many Requests).
• JSON serialization and deserialization.
• Query parameters, URL parameters, and headers.
• Middleware execution, such as rate limiters and authentication checks.

The Trade-offs

Like any architectural decision, moving to a multi-file testing structure comes with balancing factors:

Pros:

• High Scannability: Developers looking for a routing bug only need to open the handler test, while those fixing a calculation bug can go straight to the service test.
• Reduced Friction: Isolating the mocks prevents cyclic imports, keeping the Go compiler happy.
• Clear Boundaries: It enforces discipline, ensuring you don’t accidentally test HTTP mechanics inside a business logic test.

Cons:

• Boilerplate Overhead: Managing multiple files and orchestrating mocks requires slightly more upfront configuration and file management.
• Mock Maintenance: If a service interface changes, the central mock.go file must be manually updated (unless you adopt a code-generation tool like mockery).

In Layman’s Terms

Imagine you run a busy restaurant.

Originally, your test kitchen had one giant manual that crammed the cook’s recipes, the waiter’s serving rules, and cardboard cutouts of fake customers all onto the same page. It was crowded and confusing.

With this new approach, you split that manual into three neat folders:

1. The Prop Room (mock.go): This is where you keep all your cardboard cutouts (fake databases and fake chefs) so you can reuse them whenever you need to practice.
2. The Kitchen Manual (*_service_test.go): This is where you test the food itself. Does it taste right? Is it missing an ingredient? You don’t care how the waiter delivers it; you just care that the recipe works perfectly.
3. The Dining Room Manual (*_handler_test.go): This is where you test the customer experience. Did the waiter smile? Was the bill calculated correctly? Is the host stopping too many people from rushing the door at once (rate limiting)? You don’t care how the kitchen cooked the food here; you just care that the service at the table is seamless.

Conclusion

While software architecture preferences always vary depending on team conventions, decoupling your tests by responsibility is a proven strategy for Go applications. By isolating your HTTP logic from your business logic and centralizing your mocks, you eliminate code bloat, wipe out cyclic imports, and create a test suite that is easy to read, navigate, and maintain.