The Concept
When building backend APIs in Go, testing isn't just about code coverage, it's about long-term maintainability. As an application grows, a naive approach to unit testing can lead to "testing monoliths" where test setup, mocking, HTTP routing, and core business logic verification are jammed into a single, massive file.
To keep a codebase agile, your testing architecture must mirror the separation of concerns found in your production code. This means isolating the code that handles incoming network requests from the code that executes your core domain logic.
The What
Initially, the testing structure for the API lived entirely within a single, monolithic *_test.go file. Inside this file, everything was dumped together: Only service-layer assertions no HTTP request simulation, and handwritten mock structs for both the repository and service layers.
const UUID = "12345678-1234-5678-1234-567890123456"
type StockMovementTest struct {
GetStockMovementsFunc func(ctx context.Context, filters dto.BaseFilters) ([]models.StockMovement, int, error)
}
func (m *StockMovementTest) GetStockMovements(ctx context.Context, q dto.BaseFilters) ([]models.StockMovement, int, error) {
if m.GetStockMovementsFunc != nil {
return m.GetStockMovementsFunc(ctx, q)
}
return nil, 0, nil
}
func NewTestStockMovement(testStockMovementRepo *StockMovementTest) stock_movements.StockMovementService {
emailSvc := mocks.NewTestEmailService()
_, auditLogSvc := mocks.NewTestAuditService()
awsSvc := mocks.NewTestAWSService()
return stock_movements.NewStockMovementService(testStockMovementRepo, emailSvc, nil, auditLogSvc, awsSvc)
}
func TestGetStockMovements(t *testing.T) {
testStockMovementRepo := &StockMovementTest{}
testStockMovementSvc := NewTestStockMovement(testStockMovementRepo)
t.Run("Get StockMovements", func(t *testing.T) {
testStockMovementRepo.GetStockMovementsFunc = func(ctx context.Context, q dto.BaseFilters) ([]models.StockMovement, int, error) {
CheckStockMovementQuery(t, q)
return []models.StockMovement{{ProductID: 1}}, 1, nil
}
query := dto.Query{Search: "test", Limit: 10, Offset: 2, Sort: "change_amount ASC"}
_, _, err := testStockMovementSvc.GetStockMovements(context.Background(), query)
if err != nil {
t.Errorf("Expected no error, got %v", err)
}
})
}
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.gofile must be manually updated (unless you adopt a code-generation tool likemockery).
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:
-
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. -
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. -
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.