go.uber.org/goleak v1.3.0: VerifyTestMain

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify go.uber.org/goleak.VerifyTestMain in pkg:golang/go.uber.org/goleak@v1.3.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/go.uber.org/goleak@v1.3.0
Demonstrate these symbols/APIs:
  - go.uber.org/goleak.VerifyTestMain

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:0adfb1639f3db6e3aa0d705b7f3e74165f57fb40bca01048f41659fe6bf95b38","contract":["VerifyTestMain executes the test runner and exits with code 0 on clean completion without goroutine leaks","VerifyTestMain detects leaking goroutines on successful test runs and changes the exit code to 1","VerifyTestMain ignores designated leaking goroutines when goleak.IgnoreTopFunction option is configured","VerifyTestMain preserves non-zero exit codes from failed test runs without reporting goroutine leaks","VerifyTestMain executes the custom goleak.Cleanup callback passing the resolved exit code"],"goal":"verify go.uber.org/goleak.VerifyTestMain in pkg:golang/go.uber.org/goleak@v1.3.0","kind":"HOW","packages":["pkg:golang/go.uber.org/goleak@v1.3.0"],"schemaVersion":1,"symbols":["go.uber.org/goleak.VerifyTestMain"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/go.uber.org/goleak@v1.3.0"],"schemaVersion":1,"subject":"pkg:golang/go.uber.org/goleak@v1.3.0","symbols":["go.uber.org/goleak.VerifyTestMain"],"verifierAdapter":"golang@1"}

module example.com/goleak-sample

go 1.26.6

require go.uber.org/goleak v1.3.0

github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"go.uber.org/goleak"
)

// Runner wraps a test runner implementing goleak.TestingM.
type Runner struct {
	m goleak.TestingM
}

// NewRunner creates a new Runner wrapping the given TestingM implementation.
func NewRunner(m goleak.TestingM) *Runner {
	return &Runner{m: m}
}

// Run executes VerifyTestMain using the configured TestingM and optional leak detection options.
func (r *Runner) Run(opts ...goleak.Option) {
	goleak.VerifyTestMain(r.m, opts...)
}

// CustomTestingM is an adapter allowing a function to satisfy goleak.TestingM.
type CustomTestingM struct {
	RunFunc func() int
}

// Run calls RunFunc if non-nil, or returns 0.
func (c CustomTestingM) Run() int {
	if c.RunFunc != nil {
		return c.RunFunc()
	}
	return 0
}

// BackgroundWorker is a helper function that can be spawned to simulate
// background work, useful for testing IgnoreTopFunction filtering.
func BackgroundWorker(stop <-chan struct{}) {
	<-stop
}

{
  "schemaVersion": 1,
  "goal": "verify go.uber.org/goleak.VerifyTestMain in pkg:golang/go.uber.org/goleak@v1.3.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/go.uber.org/goleak@v1.3.0"
  ],
  "symbols": [
    "go.uber.org/goleak.VerifyTestMain"
  ]
}

package main

import (
	"fmt"
	"os"

	sample "example.com/goleak-sample"
	"go.uber.org/goleak"
)

func main() {
	// Assertion 1: Clean test run without goroutine leaks exits with code 0
	var exitCode1 int
	cleanRunner := sample.NewRunner(sample.CustomTestingM{
		RunFunc: func() int { return 0 },
	})
	cleanRunner.Run(goleak.Cleanup(func(code int) {
		exitCode1 = code
	}))
	if exitCode1 != 0 {
		fmt.Fprintf(os.Stderr, "FAIL: expected exit code 0 for clean run, got %d\n", exitCode1)
		os.Exit(1)
	}

	// Assertion 2: Leaking goroutine on successful test run changes exit code to 1
	stopChan2 := make(chan struct{})
	go func() {
		<-stopChan2
	}()
	var exitCode2 int
	leakRunner := sample.NewRunner(sample.CustomTestingM{
		RunFunc: func() int { return 0 },
	})
	leakRunner.Run(goleak.Cleanup(func(code int) {
		exitCode2 = code
	}))
	close(stopChan2) // unblock to clean up
	if exitCode2 != 1 {
		fmt.Fprintf(os.Stderr, "FAIL: expected exit code 1 for leaked goroutine, got %d\n", exitCode2)
		os.Exit(1)
	}

	// Assertion 3: Leaking goroutine matching IgnoreTopFunction is ignored and exits with code 0
	stopChan3 := make(chan struct{})
	go sample.BackgroundWorker(stopChan3)
	var exitCode3 int
	ignoredRunner := sample.NewRunner(sample.CustomTestingM{
		RunFunc: func() int { return 0 },
	})
	ignoredRunner.Run(
		goleak.IgnoreTopFunction("example.com/goleak-sample.BackgroundWorker"),
		goleak.Cleanup(func(code int) {
			exitCode3 = code
		}),
	)
	close(stopChan3) // unblock
	if exitCode3 != 0 {
		fmt.Fprintf(os.Stderr, "FAIL: expected exit code 0 with IgnoreTopFunction, got %d\n", exitCode3)
		os.Exit(1)
	}

	// Assertion 4: Failed test run preserves original exit code without checking leaks
	stopChan4 := make(chan struct{})
	go func() {
		<-stopChan4
	}()
	var exitCode4 int
	failedRunner := sample.NewRunner(sample.CustomTestingM{
		RunFunc: func() int { return 42 },
	})
	failedRunner.Run(goleak.Cleanup(func(code int) {
		exitCode4 = code
	}))
	close(stopChan4) // unblock
	if exitCode4 != 42 {
		fmt.Fprintf(os.Stderr, "FAIL: expected exit code 42 preserved from failed test, got %d\n", exitCode4)
		os.Exit(1)
	}

	// Assertion 5: Custom Cleanup callback receives the resolved exit code
	cleanupInvoked := false
	var exitCode5 int
	goleak.VerifyTestMain(
		sample.CustomTestingM{RunFunc: func() int { return 0 }},
		goleak.Cleanup(func(code int) {
			cleanupInvoked = true
			exitCode5 = code
		}),
	)
	if !cleanupInvoked || exitCode5 != 0 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Cleanup to be called with code 0, invoked=%v code=%d\n", cleanupInvoked, exitCode5)
		os.Exit(1)
	}

	fmt.Println("PASS: go.uber.org/goleak.VerifyTestMain contract passed")
}