Tests in Go Subdirectories: Complete Guide for Beginners

Tests in Go Subdirectories: Solving the Problem Tutorials Don't Mention

Have you ever written tests in Go and found that they work perfectly in the project root, but as soon as you move them to a subdirectory — everything breaks? Sound familiar? If so — you're not alone. The question "Golang tests in sub-directory" on Stack Overflow has gathered thousands of views. And it's no surprise: Go's documentation is dry on this topic, and beginner developers often get lost.

In this article, we'll figure out how to properly organize Go testing using nested packages, why it's needed, and how to avoid common pitfalls. Let's go!

Why Are Tests in Subdirectories a Pain?

Imagine: you have a project with the following structure:

myapp/\n├── main.go\n├── go.mod\n└── utils/\n    ├── math.go\n    └── math_test.go

You run Go test from the root — and everything works. But when you try to run the tests from the utils folder, Go complains: "package myapp/utils is not in GOROOT". Sound familiar?

The problem is that Go works with packages, not folders. When you create a subdirectory, you are essentially creating a new package. And tests in it need to be run considering the project's module structure. But let's take it step by step.

Basics: How Go Sees Tests

In Go, tests are regular files with the _test.go suffix. They can be located:

\n
• In the same package (white-box tests) — have access to unexported functions.
\n
• In a separate package with the _test suffix (black-box tests) — test the package as an external user.
\n

When you place tests in a subdirectory, you create a new package. For example, the utils folder is the utils package. And the tests in it must belong to that package.

Example of a Correct Structure

myapp/\n├── go.mod\n├── main.go\n└── utils/\n    ├── math.go        // package utils\n    └── math_test.go   // package utils

In the file math.go:

package utils\n\nfunc Add(a, b int) int {\n    return a + b\n}

In the file math_test.go:

package utils\n\nimport "testing"\n\nfunc TestAdd(t *testing.T) {\n    result := Add(2, 3)\n    if result != 5 {\n        t.Errorf("Expected 5, got %d", result)\n    }\n}

Now run the tests from the project root:

go test ./utils/

Or from the utils folder:

cd utils\ngo test

Everything works! But what if you have a more complex structure?

Nested Subdirectories: Deeper Than It Seems

Let's say you have a project with this structure:

myapp/\n├── go.mod\n├── main.go\n└── services/\n    ├── user/\n    │   ├── user.go\n    │   └── user_test.go\n    └── order/\n        ├── order.go\n        └── order_test.go

Here, each subdirectory is a separate package. To run all tests recursively, use three dots:

go test ./...

This command will find all packages in the project and run their tests. Very convenient for CI/CD!

What If Tests Are in the Same Folder as the Code?

Sometimes developers put tests in the same folder as the main code. This is fine for small projects. But for large projects, it's better to place tests in separate subdirectories — it keeps the structure cleaner.

Common Mistakes and Their Solutions

Let's break down the most frequent problems beginners face when working with Golang tests in sub-directory.

Error 1: "package is not in GOROOT"

Cause: You are trying to run a test from a subdirectory without specifying the module. Go doesn't know which module the package belongs to.

Solution: Make sure you have a go.mod file in the root