Comprehensive Guide for Golang Unit Test with Code Examples

Relia Software

Relia Software

Thuoc Nguyen

Relia Software


Unit test in software development is the process of testing the smallest parts of an application, like functions or methods, in isolation from other components.


Table of Contents

Unit testing is a key part of software development, focusing on testing individual functions or methods to ensure quality and reduce bugs. It aids in early error detection, supports safe code refactoring, and acts as practical documentation. Encouraging modular and maintainable code, it fits well with Agile and DevOps, particularly in continuous integration and delivery, ultimately enhancing the efficiency and quality of software development.

>> Read more:

What is Unit Test?

Unit test in software development is the process of testing the smallest parts of an application, like functions or methods, in isolation from other components. In Go, this practice is crucial for verifying that each unit performs as expected under various scenarios.

Unit tests ensure that each part of your codebase functions correctly, leading to reliable and maintainable software. These tests are typically automated and executed frequently, providing immediate feedback on the impact of changes to the code. The essence of a good unit test is its focus on a single functionality, ensuring clarity and ease of troubleshooting.

Fundamentals of Unit Testing in Golang

Go's Testing Package

Go provides a powerful built-in package named testing, specifically designed for writing automated unit tests. This package offers a straightforward and convenient way to write and execute tests. Key features include:

  • Test Functions: In Go, each test is written as a function with a name beginning with Test.
  • Testing.T: A critical component of the testing package is the T type, which provides methods for reporting test failures and logging additional information.
  • Running Tests: Tests are run using the go test command, which automatically identifies and executes all tests in a package.
  • Benchmarks and Examples: Besides tests, the testing package supports benchmarks (for performance testing) and example functions (which can also serve as documentation).

Writing Your First Golang Unit Test

To illustrate unit testing in Go, let's write a simple test for a function that adds two numbers. First, we define the function in a Go file, say math.go:

// math.go
package math

// Add returns the sum of two integers
func Add(a, b int) int {
    return a + b

Now, we'll write a test for this function in a file named math_test.go:

// math_test.go
package math

import "testing"

// TestAdd tests the Add function
func TestAdd(t *testing.T) {
    got := Add(2, 3)
    want := 5
    if got != want {
        t.Errorf("Add(2, 3) = %d; want %d", got, want)

Running go test in the terminal within the same directory will execute this test, giving immediate feedback on the correctness of the Add function. This example demonstrates the simplicity and effectiveness of unit testing in Go, paving the way for developing more complex and robust applications.

Advanced Concepts of Golang Unit Test 

In advanced unit testing in Golang, mocking, table-driven tests, and benchmarking play vital roles in enhancing test quality and efficiency.

Mocking and Interfaces

In Go, mocking and interfaces are pivotal for creating effective unit tests, especially when dealing with external dependencies like databases or APIs.

Mocking is the process of creating simulated versions of these external dependencies, enabling developers to isolate and test individual units of code in a controlled environment. This isolation is crucial as it ensures that tests are not affected by external factors, making them more reliable and faster to execute.

Interfaces in Go play a key role in this process. By defining an interface for an external dependency, Go allows developers to create mock implementations of these interfaces. Tools like gomock or mockery can automatically generate these mock implementations based on the interface, significantly simplifying the process. This automatic generation of mock code not only saves time but also enhances the maintainability and consistency of the tests.

For example, if you have a function that interacts with a user database, you can define a UserRepository interface and then generate a mock UserRepository. In your tests, you use this mock to simulate various scenarios, such as retrieving a user or handling database errors, without the need to interact with a real database. This approach allows for thorough testing of the function's logic under different conditions, ensuring robustness and reliability in your Go applications.

  • Defining the Interface

First, we define an interface for the database interactions. This interface will be used by our service to interact with the database.

// UserRepository is an interface for interacting with the user database
type UserRepository interface {
    FindUserByID(userID string) (*User, error)
  • Implementing the Service

Next, we implement a service that uses this interface. The service will have a method to retrieve a user by their ID.

// UserService interacts with the UserRepository to manage users
type UserService struct {
    repo UserRepository

// NewUserService creates a new instance of UserService
func NewUserService(repo UserRepository) *UserService {
    return &UserService{repo: repo}

// GetUserByID retrieves a user by their ID
func (s *UserService) GetUserByID(userID string) (*User, error) {
    return s.repo.FindUserByID(userID)
  • Creating Mocks Using a Tool

We use a mocking tool like mockery to automatically generate a mock implementation of the UserRepository interface. The generated mock will have methods that correspond to the interface but are designed to simulate database behavior.

For example, after running mockery, you get a mock like this:

// MockUserRepository is a mock type for the UserRepository interface
type MockUserRepository struct {

// FindUserByID is a mock method that simulates retrieving a user by ID
func (m *MockUserRepository) FindUserByID(userID string) (*User, error) {
    args := m.Called(userID)
    return args.Get(0).(*User), args.Error(1)
  • Writing the Test

Now, let's write a unit test for the GetUserByID method of the UserService, using the mock UserRepository.

func TestUserService_GetUserByID(t *testing.T) {
    // Create a mock instance of UserRepository
    mockRepo := new(MockUserRepository)
    userService := NewUserService(mockRepo)

    // Setup expectations
    mockUser := &User{ID: "123", Name: "John Doe"}
    mockRepo.On("FindUserByID", "123").Return(mockUser, nil)

    // Call the method
    user, err := userService.GetUserByID("123")

    // Assertions
    assert.NoError(t, err)
    assert.Equal(t, mockUser, user)

    // Assert that the expectations were met

Table-Driven Tests

Table-driven testing in Go is a method where tests are written in a concise and structured manner, allowing multiple scenarios to be tested efficiently. This approach involves defining a table (a slice of structs) where each struct represents a test case, including the input and the expected output. Table-driven tests are particularly advantageous for their readability and the ease with which new test cases can be added.

First, the function definition in math.go:

// math.go
package math

// Multiply returns the product of two integers
func Multiply(a, b int) int {
    return a * b

Next, the test file math_test.go:

// math_test.go
package math

import "testing"

// TestMultiply is a table-driven test for the Multiply function
func TestMultiply(t *testing.T) {
    tests := []struct {
        name   string
        a, b   int
        want   int
        {"2 times 3", 2, 3, 6},
        {"-1 times 5", -1, 5, -5},
        {"0 times 10", 0, 10, 0},
        // Add more test cases as needed

    for _, tt := range tests {
        t.Run(, func(t *testing.T) {
            if got := Multiply(tt.a, tt.b); got != tt.want {
                t.Errorf("Multiply(%d, %d) = %d; want %d", tt.a, tt.b, got, tt.want)

In this example, each test case in the tests slice defines the inputs a and b, and the expected output want. The t.Run function is used to execute each test case, which is particularly useful for identifying which test fails when running multiple cases. This structure makes it easy to add or modify test cases, enhancing the test's comprehensiveness and maintainability.

Coverage and Benchmarking

In Go, ensuring the effectiveness of unit tests is enhanced by leveraging tools for test coverage and benchmarking, each serving a crucial role in maintaining code quality and performance.

Coverage tools in Go, invoked using go test -cover, provide insights into the percentage of code exercised by unit tests, highlighting areas that may lack sufficient testing. For example, when testing a function like CalculateAverage, executing go test -cover would reveal the proportion of this function's code covered by tests. This data is invaluable in identifying untested paths in your code.

Additionally, Go's benchmarking tools, accessed with go test -bench, are essential for assessing the performance of code under test. Developers can write benchmark tests to measure the execution time of functions, crucial for identifying performance inefficiencies. For instance, a benchmark for CalculateAverage would run the function repeatedly under controlled conditions, measuring and reporting the time it takes, thus ensuring the function is not only correct but also performs efficiently.

// calculate.go
package math

// CalculateAverage computes the average of a slice of numbers
func CalculateAverage(numbers []int) float64 {
    var sum int
    for _, num := range numbers {
        sum += num
    return float64(sum) / float64(len(numbers))

// calculate_test.go
package math

import "testing"

func TestCalculateAverage(t *testing.T) {
    numbers := []int{2, 4, 6, 8}
    got := CalculateAverage(numbers)
    want := 5.0

    if got != want {
        t.Errorf("CalculateAverage() = %f; want %f", got, want)

// Run test with coverage
// go test -cover

func BenchmarkCalculateAverage(b *testing.B) {
    numbers := []int{2, 4, 6, 8}
    for i := 0; i < b.N; i++ {

// Run benchmark test
// go test -bench=.

The coverage test ensures that CalculateAverage behaves as expected across various scenarios, while the benchmark assesses its performance, combining to provide a holistic view of the function's reliability and efficiency.

Best Practices for Unit Testing in Golang

Use Table-Driven Tests

Table-driven tests allow you to run the same test logic with different input and expected values. This is great for thorough and organized testing.

func TestSumTableDriven(t *testing.T) {
    var tests = []struct {
        a, b int
        want int
        {2, 3, 5},
        {4, 5, 9},
        {0, 0, 0},

    for _, tt := range tests {
        testname := fmt.Sprintf("%d+%d", tt.a, tt.b)
        t.Run(testname, func(t *testing.T) {
            ans := Sum(tt.a, tt.b)
            if ans != tt.want {
                t.Errorf("got %d, want %d", ans, tt.want)

Mock External Dependencies

In Golang unit testing, the goal is to test individual units of code in isolation. However, units often interact with external systems or dependencies. Mocking these dependencies allows you to simulate their behavior without relying on their actual implementations.

  • Define Interfaces for Dependencies:
type UserRepository interface {
    GetUser(id int) (*User, error)
    CreateUser(user *User) error

type UserService struct {
    repo UserRepository

func (s *UserService) GetUser(id int) (*User, error) {
    return s.repo.GetUser(id)
  • Create Mock Implementations:
// MockUserRepository is a mock of UserRepository interface
type MockUserRepository struct {

func (mock *MockUserRepository) GetUser(id int) (*User, error) {
    args := mock.Called(id)
    return args.Get(0).(*User), args.Error(1)

func (mock *MockUserRepository) CreateUser(user *User) error {
    args := mock.Called(user)
    return args.Error(0)
  • Writing Tests Using Mocks
func TestUserService_GetUser(t *testing.T) {
    // Initialize the mock repository
    mockRepo := new(MockUserRepository)
    userService := UserService{repo: mockRepo}

    // Define the expected behavior
    mockUser := &User{ID: 1, Name: "John Doe"}
    mockRepo.On("GetUser", 1).Return(mockUser, nil)

    // Call the method
    user, err := userService.GetUser(1)

    // Assert expectations
    assert.Nil(t, err)
    assert.NotNil(t, user)
    assert.Equal(t, "John Doe", user.Name)
    mockRepo.AssertExpectations(t) // Verify that GetUser was called

In this example:

  • The MockUserRepository implements the UserRepository interface with methods that use the mocking framework to define behavior.
  • In the test TestUserService_GetUser, we set up the mock to return a specific user when GetUser is called with a specific ID.
  • We then call the GetUser method of UserService and check whether it behaves as expected given the mocked response.

Test Edge Case

Include tests for edge cases, such as empty inputs, invalid inputs, maximum and minimum values.

func TestSumEdgeCases(t *testing.T) {
    if Sum(0, 0) != 0 {
        t.Errorf("Expected 0, got %d", Sum(0, 0))
    // Add more edge cases as needed

Parallelize Tests When Appropriate

You can run tests in parallel to speed up the test suite. Use this when tests are independent of each other.

func TestSumParallel(t *testing.T) {
    // Test logic here

Clean Up After Tests

If your test creates any resources (like files or database entries), make sure to clean them up.

func TestResourceCreation(t *testing.T) {
    // Create resource
    defer cleanUpResource() // cleanUpResource is a function to clean up
    // Test logic here

Use Subtests for Grouping and Clarity

Subtests allow you to group related tests and provide more descriptive names for test cases.

func TestSumSubtests(t *testing.T) {
    t.Run("PositiveNumbers", func(t *testing.T) {
        assertEqual(t, Sum(2, 3), 5)
    t.Run("ZeroValues", func(t *testing.T) {
        assertEqual(t, Sum(0, 0), 0)

>> Read more: Comprehensive Breakdown for Software Testing Outsourcing


Unit testing has always been my thing, almost like a hobby. There was a time when I was obsessed with it, and I made sure that most of my projects had at least 80% unit test coverage. You can probably imagine how much time it can take to make such a significant change in the codebase. However, the result was worth it because I rarely encountered bugs related to business logic.

Adding new business rules was a breeze because there were already tests in place to cover all the cases from before. The key was to ensure that these tests remained successful in the end. Sometimes, I didn’t even need to check the entire running service; having the new and old unit tests pass was sufficient.

Actively apply the principles and techniques discussed in your daily coding routines. Start by integrating unit tests into your existing projects or practice by writing tests for simple Go functions. As you become more comfortable with writing tests, experiment with more complex scenarios and explore different Golang testing frameworks.

So, keep coding, keep testing, and let the journey of mastering unit testing in Golang lead you to become a better software craftsman.

>>> Follow and Contact Relia Software for more information!

  • golang
  • testing
  • coding