Creating and Using a Go Test Run/Debug Configuration in GoLand

Desired outcome

You want to execute Go unit tests from within JetBrains GoLand, see a clear pass/fail summary, and optionally start a debugging session on a failing test without leaving the IDE.

Prerequisites

• GoLand version 2023.2 or later (the UI steps match this release).
• A valid Go SDK configured for the project (File → Settings → Go → Go SDK).
• The project uses Go modules or a proper GOPATH layout with source files under $GOPATH/src.
• At least one test file ending in _test.go containing a function that starts with Test.

Procedure

1. Open the Run/Debug Configurations dialog: Run → Edit Configurations….
2. Click the + button in the top‑left corner, choose Go Test from the list.
3. In the configuration form:
   • Name: give it a descriptive label, e.g., UnitTests‑math.
   • Kind: select Package to test all tests in a package, or File to test a single test file.
   • Package/path:
     • For Package: enter the module‑relative package path, e.g., example.com/math.
     • For File: click the folder icon and navigate to the _test.go file.
   • Test flags (optional): add any go test flags you need, such as -count=1 -v to disable caching and see verbose output.
   • Environment: leave blank unless you need specific variables.
4. Click Apply, then OK to close the dialog.
5. Select the newly created configuration from the toolbar dropdown (next to the Run/Debug buttons).
6. To run the tests, click the green Run button. To start a debugging session, click the bug icon Debug.

Expected checks

• After execution, the Test Runner tool window appears at the bottom.
  • A green bar indicates all tests passed.
  • A red bar shows at least one failure; each failed test is listed with its name.
• Clicking a failed test in the Test Runner opens the source file and highlights the line where the failure occurred (e.g., a call to t.Error or t.Fail).
• The Run tool window (if visible) displays the exact go test command that GoLand executed, including any flags you added.
• If you enabled coverage (via the configuration’s Enable coverage checkbox), a coverage report appears in the same window.

Recovery options

• Configuration fails to start:
  • Verify the Go SDK path in Settings → Go → Go SDK; an outdated SDK (pre‑1.16) can produce "cannot find main module" errors.
  • Ensure the package name matches the directory structure; for module projects, the path should match go.mod.
  • If the project lies outside GOPATH without module support, GoLand cannot resolve imports. Convert the project to modules or move it under $GOPATH/src.
  • Use File → Invalidate Caches / Restart to clear stale indexes, then recreate the configuration.
• Tests do not appear in the Test Runner:
  • Confirm that the selected Kind and Package/path point to a directory that contains _test.go files.
  • Check that the build tags (if any) match the file; mismatched tags cause the test file to be excluded.
• Need to adjust flags or environment:
  • Re‑open Run → Edit Configurations, select the configuration, modify the Test flags or Environment fields, then apply.

Concrete example

Suppose you have a module example.com/math with a file add_test.go containing:

package math

import "testing"

func TestAdd(t *testing.T) {
    if add(2, 3) != 5 {
        t.Error("expected 5")
    }
}

func add(a, b int) int { return a + b }

To test this package:

1. Open Run → Edit Configurations.
2. Add a new Go Test configuration.
3. Set Kind to Package.
4. Enter Package/path: example.com/math.
5. Add Test flags: -count=1 -v (optional).
6. Apply and OK.
7. Select the configuration and click Run.

The Test Runner will show a green bar if the add function works, or a red bar with the line t.Error("expected 5") highlighted if you change the expected value to provoke a failure. Clicking the failure jumps directly to that line in add_test.go.