feature: Add support for Testable Examples

[malte-brunst]

Did you check docs and existing issues?

• I have read the documentation.
• I have searched the existing issues.

Is your feature request related to a problem? Please describe.

When you define example functions (-> see 'Additional context' below if unfarmiliar with the feature) in your _test.go files, neotest-golang indicates that it runs them together with the normal test functions and indicates their status afterwards.
When you execute the whole file or start the watcher, neotest-golang indicates that a test example function passes, even though a wrong // Output: comment is provided.
Only when you run the example test function using the 'run nearest' or 'run all tests' functionality, does the function fail, as it is supposed to.

Example:

I implement a simple Add() function:

// Package add implements the Add function
package add

// Add takes two integers and returns their sum.
func Add(a, b int) int {
	return a + b
}

I create a add_test.go file that implements a normal test function and a testable example for Add() that declares a wrong Output: (0 instead of 8):

package add

import (
	"fmt"
	"testing"
)

func TestAdd(t *testing.T) {
	got := Add(2, 2)
	want := 4

	if got != want {
		t.Errorf("got %d, want %d", got, want)
	}
}

func ExampleAdd() {
	sum := Add(4, 4)
	fmt.Println(sum)
	// Output:
	// 0
}

I run go test on the add_test.go file which indicates a failure of the example:

❯ go test -json ./add/...
{"Time":"2025-11-20T17:02:23.279039581+01:00","Action":"start","Package":"github.com/malte-brunst/learn_go_with_tests/add"}
{"Time":"2025-11-20T17:02:23.284032736+01:00","Action":"run","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"TestAdd"}
{"Time":"2025-11-20T17:02:23.284187964+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"TestAdd","Output":"=== RUN   TestAdd\n"}
{"Time":"2025-11-20T17:02:23.284220462+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"TestAdd","Output":"--- PASS: TestAdd (0.00s)\n"}
{"Time":"2025-11-20T17:02:23.284238372+01:00","Action":"pass","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"TestAdd","Elapsed":0}
{"Time":"2025-11-20T17:02:23.284251224+01:00","Action":"run","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd"}
{"Time":"2025-11-20T17:02:23.284256282+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"=== RUN   ExampleAdd\n"}
{"Time":"2025-11-20T17:02:23.284263695+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"--- FAIL: ExampleAdd (0.00s)\n"}
{"Time":"2025-11-20T17:02:23.284269253+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"got:\n"}
{"Time":"2025-11-20T17:02:23.284275244+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"8\n"}
{"Time":"2025-11-20T17:02:23.284280281+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"want:\n"}
{"Time":"2025-11-20T17:02:23.284288791+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Output":"0\n"}
{"Time":"2025-11-20T17:02:23.284293794+01:00","Action":"fail","Package":"github.com/malte-brunst/learn_go_with_tests/add","Test":"ExampleAdd","Elapsed":0}
{"Time":"2025-11-20T17:02:23.284298364+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Output":"FAIL\n"}
{"Time":"2025-11-20T17:02:23.285317156+01:00","Action":"output","Package":"github.com/malte-brunst/learn_go_with_tests/add","Output":"FAIL\tgithub.com/malte-brunst/learn_go_with_tests/add\t0.005s\n"}
{"Time":"2025-11-20T17:02:23.285356221+01:00","Action":"fail","Package":"github.com/malte-brunst/learn_go_with_tests/add","Elapsed":0.006}

I use neotest-golang instead and use the run test (leader + t + t in LazyVim) command.
A green tik indicates the functions succeeded.
The same wrong status is reported when you use the watcher mode (leader + t + w in LazyVim).
However, neotest-golang reports the correct status (FAIL), when I use the run all tests (leader + t + T in LazyVim) or the run nearest test command (leader + t + r).

Describe the solution you'd like to see.

I would like neotest-golang to report the correct test status (pass/fail) for example functions in the _test.go files.
The correct status should be reported no matter which execution mode (watcher, run whole file, run all tests, run nearest test) is chosen.
The correct status is the one provided when using the standard go test command.

Describe alternatives you've considered.

There are no alternatives.

Additional context

As with typical tests, examples are functions that reside in a package’s _test.go files. Unlike normal test functions, though, example functions take no arguments and begin with the word Example instead of Test.
Example from the Go example repository:

package reverse_test

import (
    "fmt"

    "golang.org/x/example/hello/reverse"
)

func ExampleString() {
    fmt.Println(reverse.String("hello"))
    // Output: olleh
}

Running the package’s test suite, we can see the example function is executed with no further arrangement from us:

$ go test -v
=== RUN   TestString
--- PASS: TestString (0.00s)
=== RUN   ExampleString
--- PASS: ExampleString (0.00s)
PASS
ok      golang.org/x/example/hello/reverse  0.209s

As it executes the example, the testing framework captures data written to standard output and then compares the output against the example’s “Output:” comment. The test passes if the test’s output matches its output comment or failes otherwise.

Godoc uses a naming convention to associate an example function with a package-level identifier.

func ExampleFoo()     // documents the Foo function or type
func ExampleBar_Qux() // documents the Qux method of type Bar
func Example()        // documents the package as a whole

Following this convention, godoc displays the ExampleString example alongside the documentation for the String function.

Multiple examples can be provided for a given identifier by using a suffix beginning with an underscore followed by a lowercase letter. Each of these examples documents the String function:

func ExampleString()
func ExampleString_second()
func ExampleString_third()

[fredrikaverpil]

Hey @malte-brunst and thanks for the feature request. Would you mind trying out a branch where I believe I added support for this?

{
  "fredrikaverpil/neotest-golang",
  branch = "examples",
}

[malte-brunst]

Hi @fredrikaverpil,
thanks for the message and the implementation :)

In my local tests, the feature does not work as expected.
I have this test file, which specifies two tests (one normal and one example).
When I run the tests, a red x indicates a test failure for both of them, even though both tests pass when running go test directly. This is the case no matter how I run the tests from within neovim (run all tests, run nearest test, run file, and watch file).

package add

import (
	"fmt"
	"testing"
)

func TestAdd(t *testing.T) {
	got := Add(2, 2)
	want := 4

	if got != want {
		t.Errorf("got %d, want %d", got, want)
	}
}

func ExampleAdd() {
	sum := Add(4, 4)
	fmt.Println(sum)
	// Output:
	// 8
}

[fredrikaverpil]

@malte-brunst it doesn't sound like you are using the examples branch. Your tests look very much like the ones in my example_test.go file in this PR and I cannot reproduce what you are describing.

package examples

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

package examples

import (
	"fmt"
	"testing"
)

func TestAdd(t *testing.T) {
	got := Add(2, 2)
	want := 4

	if got != want {
		t.Errorf("got %d, want %d", got, want)
	}
}

func ExampleAdd() {
	sum := Add(4, 4)
	fmt.Println(sum)
	// Output:
	// 8
}

$ cd examples
$ go test -v ./...
=== RUN   TestAdd
--- PASS: TestAdd (0.00s)
=== RUN   ExampleAdd
--- PASS: ExampleAdd (0.00s)
PASS
ok      github.com/fredrikaverpil/neotest-golang/tests/go/internal/examples     0.586s

You can also see how all CI tests are passing with the tests/examples I added in https://github.com/fredrikaverpil/neotest-golang/blob/c5e3e2a0eccef7bb76a1dbdd7d164f7a3dad60f5/tests/go/internal/examples/examples_test.go (PR).

Can you please provide more details, like the file that contains the Add function, the exact errors you are seeing and your :checkhealth neotest-golang output?

[malte-brunst]

Hi @fredrikaverpil,
it is the first time I have to specify a specific branch for a neovim plugin, but as far as I can tell, I am on the "examples" branch.
I have added a neotest-golang.lua file to my .config/nvim/lua/plugins/ directory with the content:

return {
  "fredrikaverpil/neotest-golang",
  branch = "examples",
}

Afterwards, I ran :Lazy sync to install/upgrade all plugins.
Lazy tells me I am using the examples branch:

I added the add.go file that contains the Add function, and the add_test.go test file.
For some reason GitHub does not allow to upload .go files, so I uploaded them as .txt files instead...

add.txt
add_test.txt

Here is the output of :checkhealth neotest-golang:

==============================================================================
neotest-golang: 4 ⚠️ 1 ❌

System Information ~

• ✅ OK Operating System: WSL2 (Ubuntu 22.04.5 LTS)
• Kernel: 6.6.87.2-microsoft-standard-WSL2

Requirements ~

• ✅ OK Neovim version 0.11.5 is supported (>= 0.10.0)
• ✅ OK Binary 'go' found on PATH: /home/malte/.nix-profile/bin/go
• ✅ OK Go version: go version go1.25.3 linux/amd64
• ✅ OK Found go.mod file for /home/malte/Repositories/learn_go_with_tests/main/add/add_test.go in /home/malte/Repositories/learn_go_with_tests/main/go.mod
• ✅ OK Treesitter parser for go is installed
• ✅ OK neotest is available
• ✅ OK nio is available
• ✅ OK plenary is available
• ❌ ERROR CGO_ENABLED is disabled but -race is part of go_test_args.

nvim-treesitter (optional) ~

• ✅ OK nvim-treesitter is available
• ✅ OK nvim-treesitter appears to be on 'main' branch (recommended for neotest-golang v2+)

DAP (optional) ~

• ⚠️ WARNING Binary 'dlv' not found on PATH
• ⚠️ WARNING dap is not available
• ⚠️ WARNING dapui is not available
• ⚠️ WARNING dap-go is not available

Gotestsum (optional) ~

• ✅ OK Binary 'gotestsum' not found on PATH

Sanitization (optional) ~

• ✅ OK Sanitization is disabled

Configuration ~

• {
  colorize_test_output = true,
  dap_go_enabled = true,
  dap_go_opts = {},
  dap_manual_config = {},
  dap_mode = "dap-go",
  dev_notifications = false,
  env = {},
  filter_dirs = { ".git", "node_modules", ".venv", "venv" },
  go_list_args = {},
  go_test_args = { "-v", "-race", "-count=1" },
  gotestsum_args = { "--format=standard-verbose" },
  log_level = 3,
  performance_monitoring = false,
  runner = "go",
  sanitize_output = false,
  testify_enabled = false,
  testify_import_identifier = "^(suite)$",
  testify_operand = "^(s|suite)$",
  warn_test_name_dupes = true
  }

[fredrikaverpil]

I notice from the checkhealth output that you have -race in your test arguments but CGO is disabled. Can you please try to not use that argument?

require("neotest-golang").setup({
  go_test_args = { "-v", "-count=1" },  -- removed -race
})

You can read more about this here as it is a fairly common problem. The reason for why -race is part of the default arguments is that it's a really good production default.

Let me know if this solves your issue here.