Mocking with Interfaces for Unit Testing

Your Goal for Today

Learning Outcome: Use interfaces to create mock implementations for isolated unit testing.

We will cover:

1. A "smarter" manual mocking technique for large interfaces.
2. Using mocking libraries like testify/mock to structure our mocks.
3. Automatically generating mock implementations using a tool called mockery.
4. How to use these generated mocks to define behavior and make assertions in your tests.
5. Best practices for ensuring your tests remain clean, isolated, and effective design tools.

1. From Manual Mocks to "Smarter" Mocks

In the previous lesson, our mockRepo was simple because the Repository interface had only one method. What if the interface was much larger, like the io.ReadCloser from the standard library, or a complex database repository with a dozen methods? Manually implementing all of them, even with empty bodies, is inefficient.

A clever, pure-Go technique to handle this is to embed the interface within your mock struct. This gives your mock all the methods of the interface "for free" (they will have a nil implementation and panic if called), allowing you to override only the ones you care about for a specific test.

This video demonstrates this exact technique.

This embedding technique is a great tool for your pure-Go toolbox. However, for a more structured and feature-rich approach, the Go ecosystem heavily relies on dedicated mocking libraries.

2. Automating Mock Creation with testify/mock and mockery

The testify suite is the de-facto standard for testing utilities in Go, and its mock package provides a foundation for creating powerful mocks. While you can use it to build mocks manually, its real power is realized when combined with a code generation tool like mockery.

mockery automatically generates a complete, type-safe mock implementation for any given interface. This saves you from writing boilerplate code and lets you focus on the test logic itself.

The following video will walk you through this entire workflow: from the pain of manual implementation, to generating a mock with mockery, to using it in a test.

This generate -> configure -> execute workflow is central to modern Go testing. The interface provides the contract, mockery provides the implementation, and your test provides the specific behavior for each scenario.

3. Best Practices for Robust Mock-Based Tests

Using generated mocks makes testing easier, but a few best practices are essential to prevent tests from becoming brittle or interfering with one another.

Test Isolation

A cardinal rule of unit testing is that tests must be isolated; the outcome of one test should never affect another. When using mocks, this means creating a fresh mock instance for each test case.

If you reuse a mock, the expectations you set for one test (mock.On(...).Return(...)) can leak into the next, causing unexpected failures. Test suites in testify provide a SetupTest function that runs before each test, making it the perfect place to initialize a fresh mock.

Asserting Interactions

So far, we've used mocks as stubs to provide return values. But they can also be used as spies to verify how your code interacted with its dependencies.

• Was a method called the expected number of times?
• Was a method not called, as expected in an error path?

The testify/mock package provides assertion functions to check these interactions.

Asserting interactions is a powerful way to gain confidence that your logic is behaving exactly as intended, especially for code paths that don't have an explicit return value (e.g., a call to a notification service).

Mocks as a Design Compass

As an experienced engineer interested in system design, you should view your tests—especially your mocks—as a design tool. If you find that testing a piece of code is difficult, it's often a "code smell" pointing to a design issue.

If a test requires you to set up five different mocks, it's a strong signal that the unit under test is doing too much and likely violating the Single Responsibility Principle. Pain in testing often precedes pain in maintenance.

4. Hands-On Application

Let's refactor the test from our previous lesson to use a generated mock.

1. Install mockery

If you haven't already, install mockery. It's a command-line tool.

go install github.com/vektra/mockery/v2@latest

2. Define the Interface

Ensure your repository interface is defined. We'll use the same one from the last lesson.

internal/user/user.go

package user

import (
	"context"
)

// Repository defines the storage interface for user operations.
type Repository interface {
	Create(ctx context.Context, email string) error
}

// ... rest of the service code

3. Generate the Mock

Navigate to your project's root directory and run mockery. The --name flag specifies the interface to mock.

mockery --name=Repository --dir=internal/user --output=internal/user/mocks --outpkg=mocks

• --name=Repository: The interface we want to mock.
• --dir=internal/user: Where to find the interface definition.
• --output=...: Where to save the generated mock file.
• --outpkg=...: The package name for the generated file.

This will create a internal/user/mocks/Repository.go file containing the mock struct.

4. Update the Test to Use the Mock

Now, rewrite internal/user/user_test.go to use this shiny new mock.

internal/user/user_test.go

package user

import (
	"context"
	"errors"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/mock"

	"your_module_path/internal/user/mocks" // Import the generated mock package
)

func TestService_Create(t *testing.T) {
	tests := []struct {
		name          string
		inputEmail    string
		setupMock     func(m *mocks.Repository) // Function to set up mock expectations
		wantErr       bool
		wantErrMsg    string
	}{
		{
			name:       "should create user successfully",
			inputEmail: "test@example.com",
			setupMock: func(m *mocks.Repository) {
				m.On("Create", mock.Anything, "test@example.com").Return(nil)
			},
			wantErr:    false,
		},
		{
			name:       "should return error for invalid email format",
			inputEmail: "invalid-email",
			setupMock: func(m *mocks.Repository) {
				// No call to the repository is expected, so we don't set any expectation.
			},
			wantErr:    true,
			wantErrMsg: "invalid email format",
		},
		{
			name:       "should return error when repository reports user exists",
			inputEmail: "exists@example.com",
			setupMock: func(m *mocks.Repository) {
				m.On("Create", mock.Anything, "exists@example.com").
					Return(errors.New("user already exists"))
			},
			wantErr:    true,
			wantErrMsg: "user already exists",
		},
	}

	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			// Arrange: Create a fresh mock for each test.
			mockRepo := new(mocks.Repository)
			
			// Set up the expectations for this specific test case.
			tc.setupMock(mockRepo)

			service := NewService(mockRepo)

			// Act
			err := service.Create(context.Background(), tc.inputEmail)

			// Assert
			if tc.wantErr {
				assert.Error(t, err)
				assert.Equal(t, tc.wantErrMsg, err.Error())
			} else {
				assert.NoError(t, err)
			}
			
			// Assert that all expectations set on the mock were met.
			mockRepo.AssertExpectations(t)
		})
	}
}

Notice the improvements over the manual mock:

• Declarative Expectations: The On(...).Return(...) syntax clearly declares the expected behavior for each test.
• No Boilerplate: We didn't have to write the mock Create method ourselves.
• Interaction Testing: mockRepo.AssertExpectations(t) automatically verifies that the mock was called as configured. For the "invalid email" case, it implicitly asserts that Create was not called, because no expectation was set.

Conclusion

You've now evolved your testing skills from basic manual mocks to the standard, automated workflow used in professional Go development. This approach not only speeds up test writing but also makes your tests more expressive and robust.

Key Takeaways:

• Interfaces are the key that unlocks testability by creating a "seam" in your application.
• Auto-generation tools like mockery eliminate boilerplate and let you focus on test logic.
• The mock.On(...).Return(...) pattern provides a declarative way to define mock behavior for each test case.
• Mocks can act as stubs (providing data) and spies (verifying interactions) via assertion methods like AssertCalled and AssertExpectations.
• Difficulty in mocking is often a sign of a design flaw in the code being tested.

Next Up

We have now thoroughly covered testing our code in isolation. Unit tests are fast and reliable, but they can't verify that your code correctly integrates with external services, like a real database.

In the next lesson, we will bridge this gap by writing integration tests against a real PostgreSQL instance using testcontainers-go. You'll learn how to programmatically spin up a database in a Docker container for your tests, allowing you to validate your SQL queries and repository logic against the real thing without a complex local setup.