Writing integration tests with databases is crucial for web application development, as it boosts confidence in our code and ensures our application works as expected. However, preparing mock data for these tests can be challenging, especially in Go, which lacks a built-in approach or standard library for this task. This article introduces the gofacto library, which simplifies the process of building mock data and inserting it into databases for Go integration tests.

What is gofacto?

gofacto is a Go library that simplifies the creation and insertion of mock data into databases. It provides an intuitive approach for defining data schemas and efficiently handling database insertions. With gofacto, developers can quickly prepare test data without the burden of writing extensive boilerplate code, allowing them to focus on writing meaningful tests.

Before using gofacto

Let's see what we normally do when writing integration tests with databases in Go. Suppose we have a table named users in the database, and it has the following schema:

CREATE TABLE users (
    id INT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL
);

Suppose we want to test a function named getUserByID that retrieves a user by its ID from the users table. In order to test this function, we need to prepare some mock data in the database before testing this function. Here's how we normally do it:

type User struct {
    ID      int
    Gender  string
    Name    string
    Email   string
}

// build and insert mock user
mockUser := User{
    ID:     1,
    Gender: "male",
    Name:   "Alice",
    Email:  "aaa@gmail.com",
}
err := insertToDB(mockUser)

// action
result, err := getUserByID(mockUser.ID)

// assertion
// ...

insertToDB is a function that inserts mock data into the database. It might be a lot complex if we're using raw sql queries.

This approach seems manageable because the schema is simple, and we only deal with one table.

Let's see the case when we deal with two tables, users and posts. Each user can have multiple posts, and the relationship between the tables is established by the user_id field in the posts table.

CREATE TABLE posts (
    id INT PRIMARY KEY,
    user_id INT NOT NULL,
    title VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users(id)
);

Suppose we want to test a function named getPostsByUserID that retrieves all posts by a user's ID from the posts table.

type Post struct {
  ID      int
  UserID  int
  Title   string
  Content string
}

// build and insert mock user
mockUser := User{
    ID:     1,
    Gender: "male",
    Name:   "Alice",
    Email:  "aaa@gmail.com",
}
err := insertToDB(mockUser)

// build and insert mock post
mockPost1 := Post{
  ID:      1,
  UserID:  mockUser.ID, // manually set the foreign key
  Title:   "Post 1",
  Content: "Content 1",
}
err = insertToDB(mockPost1)

// build and insert mock post
mockPost2 := Post{
  ID:      2,
  UserID:  mockUser.ID, // manually set the foreign key
  Title:   "Post 2",
  Content: "Content 2",
}
err = insertToDB(mockPost2)

// action
result, err := getPostsByUserID(mockUser.ID)

// assertion
// ...

We first create a user and then create two posts for that user. Compared to the previous example, it becomes more complex since we deal with two tables and establish the relationship between them.

What if we want to create multiple posts with different users?
We need to create a user for each post, and it requires more code.

// build and insert mock user
mockUser1 := User{
  ID:    1,
  Gender: "male",
  Name:  "Alice",
  Email: "aaa@gmail.com",
}
err := insertToDB(mockUser1)

// build and insert mock user
mockUser2 := User{
  ID:  2,
  Gender: "female",
  Name:  "Bob",
  Email: "bbb@gmail.com",
}
err = insertToDB(mockUser2)

// build and insert mock post
mockPost1 := Post{
  ID:      1,
  UserID:  mockUser1.ID, // manually set the foreign key
  Title:   "Post 1",
  Content: "Content 1",
}
err = insertToDB(mockPost1)

// build and insert mock post
mockPost2 := Post{
  ID:      2,
  UserID:  mockUser2.ID, // manually set the foreign key
  Title:   "Post 2",
  Content: "Content 2",
}
err = insertToDB(mockPost2)

// action
result, err := getPostsByUserID(mockUser1.ID)

// assertion
// ...

It's getting more complex and error-prone when we need to create multiple mock data with different users and posts.

Also note that we only use simple schema for the demonstration purpose, the code will be more complex in the real-world applications.

What are the problems?

In the above examples, there are some problems:

• Write a lot of boilerplate code to prepare mock data in the database
  • Sometimes, we don't care what's the value of the fields, we just need to make sure there's a correct value in each field.
• Hardcode the value of ID in the mock data
  • It's not a good practice to hardcode the value of ID in the mock data because the ID is normally auto-incremented in the database.
• Manually establishing relationships between tables
  • This makes the testing code cumbersome and error-prone, especially when creating mock data with multiple related tables.

Using gofacto

Now, let's see how gofacto library can help us solve the above problems, and make the whole process easier.

Let's see the first example with the users table.

// initialize a factory with User struct (also use `WithDB` to pass the database connection)
f := gofacto.New(User{}).WithDB(db)

// build and insert mock user
mockUser, err := f.Build(ctx).Insert()

// action
result, err := getUserByID(mockUser.ID)

// assertion
// ...

In order to use gofacto, we first use New function to initialize a new factory with User. Because we need to insert data into database, using WithDB to pass the database connection to the factory.
Then, we use Build function to build the mock data. The Insert function inserts the mock data into the database and returns the mock data that has been inserted into the database with the auto-incremented ID.

Note that all the field of the mock data is randomly generated by default. It's okay in this case because we don't care about the value of the fields.

In case we want to specify the value of the fields, we can use Overwrite function to set the value of the fields.

mockUser, err := f.Build(ctx).
                   Overwrite(User{Gender: "male"}).
                   Insert()
// mockUser.Gender == "male"

When using Overwrite function, we only need to specify the fields that we want to overwrite. The other fields will be randomly generated as usual.

Let's see the case where we want to create multiple posts with one user.
In order to make gofacto know the relationship between the tables, we need to define the correct tags in the struct.

type Post struct {
    ID      int
    UserID  int       `gofacto:"foreignKey,struct:User"`
    Title   string
    Content string
}

The tag tells gofacto that the UserID field is a foreign key that references the ID field of the User struct.

Now, we can create multiple posts with one user easily.

mockUser := User{}
mockPosts, err := f.BuildList(ctx, 2).
                    WithOne(&mockUser). // must pass pointer to the struct to `WithOne`
                    Insert()
// mockPosts[0].UserID == mockUser.ID
// mockPosts[1].UserID == mockUser.ID

// action
result, err := getPostsByUserID(mockUser.ID)

// assertion
// ...

In order to create multiple posts, we use BuildList function with the number of posts that we want to create. Then, we use WithOne function to specify that all the posts belong to one user. The Insert function returns a list of posts that have been inserted into the database with the auto-incremented ID.

gofacto library makes sure all the fields are correctly set randomly, and the relationship between the tables is correctly established.

Let's see the case where we want to create multiple posts with different users.

mockUser1 := User{}
mockUser2 := User{}
mockPosts, err := f.BuildList(ctx, 2).
                    WithMany([]interface{}{&mockUser1, &mockUser2}).
                    Insert()
// mockPosts[0].UserID == mockUser1.ID
// mockPosts[1].UserID == mockUser2.ID

// action
result, err := getPostsByUserID(mockUser1.ID)

// assertion
// ...

We use WithMany function to specify that each post is associated with a different user.

Multi-Level Associations

In the previous examples, we explored creating mock data with single-level associations. However, real-world applications often involve deeply nested associations. gofacto provides a powerful way to create mock data with multi-level associations.

Let's consider a more complex example:

type Expense struct {
    ID         int
    UserID     int `gofacto:"foreignKey,struct:User"`
    CategoryID int `gofacto:"foreignKey,struct:Category,table:categories"`
}

type Category struct {
    ID     int
    UserID int `gofacto:"foreignKey,struct:User"`
}

type User struct {
    ID int
}

In this scenario, an Expense belongs to both a User and a Category. Additionally, a Category belongs to a User, creating a two-level association hierarchy.

To create an expense with its associated user and category, we can leverage the WithOne method:

mockUser := User{}
mockCategory := Category{}
mockExpense, err := f.Build(ctx).
                      WithOne(&mockUser).
                      WithOne(&mockCategory).
                      Insert()
// mockExpense.UserID == mockUser.ID
// mockExpense.CategoryID == mockCategory.ID
// mockCategory.UserID == mockUser.ID

gofacto automatically handles the multi-level associations for us, simplifying the process significantly.

For a more concise approach, you can pass multiple structs to a single WithOne call:

mockExpense, err := f.Build(ctx).
                      WithOne(&mockUser, &mockCategory).
                      Insert()

What if we need to create multiple expenses with different categories but the same user?
We can combine WithMany and WithOne to achieve this:

mockUser := User{}
mockCategory1 := Category{}
mockCategory2 := Category{}
mockExpenses, err := f.BuildList(ctx, 2).
                       WithMany([]interface{}{&mockCategory1, &mockCategory2}).
                       WithOne(&mockUser).
                       Insert()
// mockExpenses[0].UserID == mockUser.ID
// mockExpenses[1].UserID == mockUser.ID
// mockExpenses[0].CategoryID == mockCategory1.ID
// mockExpenses[1].CategoryID == mockCategory2.ID
// mockCategory1.UserID == mockUser.ID
// mockCategory2.UserID == mockUser.ID

This showcases one of gofacto's most powerful features: the ability to easily build structs with complex association relationships. As long as you define the correct tags in your structs, gofacto handles the complex setup for you. Attempting to build these association relationships without gofacto would require significantly more setup code and complexity.

Summary

We've seen how gofacto simplifies writing integration tests with databases in Go. It reduces boilerplate code and makes it easier to prepare mock data with multiple tables and establish relationships between them. Most importantly, gofacto abstracts away the complexity of preparing mock data, allowing developers to focus on writing meaningful tests. To start using gofacto in your Go projects, visit the GitHub repository for installation instructions and more detailed documentation.

Feedback and Further Development

As a new library developer, I'd love to hear your thoughts on gofacto! Any feedback, advice or criticism is appreciated. If you use it in your Go projects, please share your experience. Found a bug or have an idea? Open an issue on the gofacto GitHub repo. Want to contribute code? Pull requests are welcome! Your feedback and contributions will help improve gofacto and benefit the Go community. Thanks for checking it out!