Testing concurrent Go code has always been a balancing act between speed and reliability. The testing/synctest package (experimental in Go 1.24, stable since Go 1.25) eliminates that trade-off. It wraps your test in an isolated bubble with a fake clock, deterministic goroutine scheduling, and instant time advancement. Two functions, zero flakiness.

Every snippet runs on Go 1.26 via Codapi sandboxes directly in your browser, no local toolchain required. Because synctest requires a real *testing.T, each snippet uses a thin testing.Main wrapper to run the test function.

The timing trap

Polling and hoping

The classic way to check whether a goroutine did something is to wait a little and then peek:

go1.26

interactive

package main
 
import (
	"fmt"
	"time"
)
 
func main() {
	delivered := make(chan bool, 1)
 
	// Simulate: a notification fires only after a trigger
	trigger := make(chan struct{})
	go func() {
		<-trigger
		delivered <- true
	}()
 
	// "Has it fired?"; wait and hope
	select {
	case <-delivered:
		fmt.Println("FAIL: fired before trigger")
	case <-time.After(50 * time.Millisecond):
		fmt.Println("OK: not fired yet (but we waited 50 ms to be sure)")
	}
 
	// Trigger and check again
	close(trigger)
	select {
	case <-delivered:
		fmt.Println("OK: fired after trigger")
	case <-time.After(50 * time.Millisecond):
		fmt.Println("FAIL: timed out waiting")
	}
}

Two problems: the test is slow (100 ms of real wall-clock time for two assertions) and fragile (an overloaded CI machine can make 50 ms feel like nothing). Multiply that by hundreds of tests and you're stuck choosing between a fast suite that sometimes lies and a slow suite that sometimes tells the truth.

Enter synctest

Two functions, that's it

The entire testing/synctest API is:

Function	Purpose
`synctest.Test(t, f)`	Run `f` in a new bubble; wait for all goroutines to exit before returning
`synctest.Wait()`	Block until every other goroutine in the bubble is durably blocked

A bubble is an isolated environment. Every goroutine started inside belongs to it. The runtime tracks when all of them are stuck (on a channel, a WaitGroup, or time.Sleep) and only then decides what to do next: return from Wait, advance the fake clock, or panic on deadlock.

Fake clock: time runs instantly

Inside the bubble, time.Now() starts at midnight UTC 2000-01-01 and advances only when every goroutine is blocked. A 24-hour sleep completes in microseconds:

go1.26

interactive

package main
 
import (
	"fmt"
	"testing"
	"testing/synctest"
	"time"
)
 
func TestFakeClock(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		start := time.Now()
		fmt.Println("Start:", start.Format(time.DateTime))
 
		time.Sleep(24 * time.Hour)
		fmt.Printf("After 24 h sleep: %v elapsed\n", time.Since(start))
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestFakeClock", F: TestFakeClock}},
		nil, nil,
	)
}

No mock clocks, no dependency injection, no interface wrappers; time.Sleep and time.Now just work.

Multiple goroutines sleeping different amounts are unblocked in order of their wakeup times:

go1.26

interactive

package main
 
import (
	"fmt"
	"sync"
	"testing"
	"testing/synctest"
	"time"
)
 
func TestTimeOrdering(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		events := []string{}
 
		var wg sync.WaitGroup
		wg.Add(3)
 
		go func() {
			defer wg.Done()
			time.Sleep(3 * time.Second)
			events = append(events, "C (3 s)")
		}()
		go func() {
			defer wg.Done()
			time.Sleep(1 * time.Second)
			events = append(events, "A (1 s)")
		}()
		go func() {
			defer wg.Done()
			time.Sleep(2 * time.Second)
			events = append(events, "B (2 s)")
		}()
 
		wg.Wait()
		fmt.Println(events) // always [A (1 s) B (2 s) C (3 s)]
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestTimeOrdering", F: TestTimeOrdering}},
		nil, nil,
	)
}

In a real program those goroutines might race. Inside the bubble the order is deterministic: the shortest sleep wakes first, then the next, and so on.

synctest.Wait: peeking at goroutine state

Wait blocks the calling goroutine until every other goroutine in the bubble is durably blocked. Once it returns, you know nothing else will happen until you take the next action. That turns "assert something hasn't happened" from a guess into a fact:

go1.26

interactive

package main
 
import (
	"fmt"
	"testing"
	"testing/synctest"
)
 
func TestWaitSemantics(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		log := []string{}
		ch := make(chan struct{})
 
		go func() {
			<-ch // blocks until ch is closed
			log = append(log, "unblocked")
		}()
 
		// After Wait returns, the goroutine above is confirmed blocked on <-ch.
		synctest.Wait()
		fmt.Println("Before close:", log) // []
 
		close(ch)
		synctest.Wait()
		fmt.Println("After close:", log) // [unblocked]
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestWaitSemantics", F: TestWaitSemantics}},
		nil, nil,
	)
}

No race condition: the log slice is safe to read after Wait returns because every other goroutine is confirmed blocked. The race detector understands Wait calls; remove one and it'll rightfully complain.

What counts as "durably blocked"

Not every blocking call qualifies. The runtime only considers a goroutine durably blocked when nothing outside the bubble can unblock it:

Durably blocking	NOT durably blocking
Send/receive on a channel created inside the bubble	`sync.Mutex` / `sync.RWMutex` locking
`select` where every case uses a bubble channel	Network I/O (reads, writes, accepts)
`time.Sleep`	System calls
`sync.WaitGroup.Wait` (if `Add`/`Go` was called inside the bubble)	Channels created outside the bubble
`sync.Cond.Wait`

Mutexes are excluded deliberately; they're typically held briefly and may involve global state. Network I/O is excluded because a socket could be unblocked by a write from a completely different process.

The implication: network code needs a fake transport (like net.Pipe) to participate in the blocking model. More on that below.

Practical patterns

Testing a periodic health checker

Real systems are full of background loops. Here's a health checker that pings a service every 30 seconds, exactly the kind of code that's miserable to test with real time:

go1.26

interactive

package main
 
import (
	"context"
	"fmt"
	"sync"
	"testing"
	"testing/synctest"
	"time"
)
 
// RunHealthCheck calls check every interval until ctx is canceled.
func RunHealthCheck(ctx context.Context, interval time.Duration, check func() error, onResult func(ok bool)) {
	for {
		select {
		case <-ctx.Done():
			return
		case <-time.After(interval):
			if err := check(); err != nil {
				onResult(false)
			} else {
				onResult(true)
			}
		}
	}
}
 
func TestHealthCheck(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ctx, cancel := context.WithCancel(t.Context())
 
		callCount := 0
		results := []bool{}
 
		check := func() error {
			callCount++
			if callCount == 2 {
				return fmt.Errorf("service down")
			}
			return nil
		}
 
		var wg sync.WaitGroup
		wg.Go(func() {
			RunHealthCheck(ctx, 30*time.Second, check, func(ok bool) {
				results = append(results, ok)
			})
		})
 
		// Nothing happened yet
		synctest.Wait()
		fmt.Printf("t=0s   results=%v\n", results)
 
		// Advance past the first check
		time.Sleep(30*time.Second + time.Millisecond)
		synctest.Wait()
		fmt.Printf("t=30s  results=%v\n", results)
 
		// Second check: this one fails
		time.Sleep(30 * time.Second)
		synctest.Wait()
		fmt.Printf("t=60s  results=%v\n", results)
 
		// Third check: healthy again
		time.Sleep(30 * time.Second)
		synctest.Wait()
		fmt.Printf("t=90s  results=%v\n", results)
 
		cancel()
		wg.Wait()
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestHealthCheck", F: TestHealthCheck}},
		nil, nil,
	)
}

90 seconds of simulated time, zero seconds of real time. And because Wait confirms the loop has settled after each sleep, the results slice is always in the expected state, no flaky assertions.

Testing a debouncer

Debouncers collapse rapid calls into one delayed action. Without synctest, testing the timing is basically guesswork. With it, you get millisecond precision:

go1.26

interactive

package main
 
import (
	"fmt"
	"sync"
	"testing"
	"testing/synctest"
	"time"
)
 
// Debounce returns a function that delays calling action
// until delay has passed since the last invocation.
func Debounce(delay time.Duration, action func()) func() {
	var mu sync.Mutex
	var timer *time.Timer
	return func() {
		mu.Lock()
		defer mu.Unlock()
		if timer != nil {
			timer.Stop()
		}
		timer = time.AfterFunc(delay, action)
	}
}
 
func TestDebounce(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		calls := 0
		trigger := Debounce(500*time.Millisecond, func() {
			calls++
		})
 
		// Fire three times in quick succession
		trigger()
		time.Sleep(100 * time.Millisecond)
		trigger()
		time.Sleep(100 * time.Millisecond)
		trigger() // last call resets the timer
 
		// 400 ms after the last trigger; not enough
		time.Sleep(400 * time.Millisecond)
		synctest.Wait()
		fmt.Println("At 400 ms after last trigger:", calls) // 0
 
		// 100 ms more; debounce fires
		time.Sleep(100 * time.Millisecond)
		synctest.Wait()
		fmt.Println("At 500 ms after last trigger:", calls) // 1
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestDebounce", F: TestDebounce}},
		nil, nil,
	)
}

The action fires exactly once, exactly 500 ms after the last call. Try changing the delay or the trigger timing and re-run; the results always match.

Testing a producer–consumer pipeline

synctest shines when you need to verify ordering across multiple goroutines:

go1.26

interactive

package main
 
import (
	"context"
	"fmt"
	"testing"
	"testing/synctest"
	"time"
)
 
// Pipeline starts a producer that emits a counter every interval
// and a consumer that collects the values.
func Pipeline(ctx context.Context, interval time.Duration) (produced, consumed *[]int) {
	p := &[]int{}
	c := &[]int{}
	ch := make(chan int, 1)
 
	go func() {
		n := 0
		defer close(ch)
		for {
			select {
			case <-ctx.Done():
				return
			case <-time.After(interval):
				n++
				*p = append(*p, n)
				ch <- n
			}
		}
	}()
 
	go func() {
		for v := range ch {
			*c = append(*c, v)
		}
	}()
 
	return p, c
}
 
func TestPipeline(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		ctx, cancel := context.WithCancel(t.Context())
 
		produced, consumed := Pipeline(ctx, 1*time.Second)
 
		// After 3 ticks
		time.Sleep(3*time.Second + time.Millisecond)
		synctest.Wait()
 
		fmt.Println("Produced:", *produced)
		fmt.Println("Consumed:", *consumed)
 
		cancel()
		time.Sleep(time.Millisecond)
		synctest.Wait()
 
		fmt.Println("Final produced:", *produced)
		fmt.Println("Final consumed:", *consumed)
	})
}
 
func main() {
	testing.Main(
		func(_, _ string) (bool, error) { return true, nil },
		[]testing.InternalTest{{Name: "TestPipeline", F: TestPipeline}},
		nil, nil,
	)
}

Three seconds of simulated pipeline, deterministic results. The producer emits exactly three values and the consumer has received all of them by the time Wait returns.

Networking: use net.Pipe

I/O operations are not durably blocking; the runtime can't know whether a network read will be resolved by something outside the bubble. To test network code with synctest, replace real connections with net.Pipe:

func TestEchoServer(t *testing.T) {
	synctest.Test(t, func(t *testing.T) {
		client, server := net.Pipe() // in-memory, fully synchronous
		defer client.Close()
		defer server.Close()
 
		// Start echo handler
		go func() {
			buf := make([]byte, 256)
			for {
				n, err := server.Read(buf)
				if err != nil {
					return
				}
				server.Write(buf[:n])
			}
		}()
 
		// Send and receive
		go func() {
			client.Write([]byte("ping"))
		}()
 
		resp := make([]byte, 4)
		client.Read(resp)
		if string(resp) != "ping" {
			t.Fatalf("got %q, want %q", resp, "ping")
		}
	})
}

net.Pipe creates a synchronous, in-memory connection pair. Reads and writes on piped connections behave like channel operations, so synctest.Wait correctly identifies when goroutines are idle.

This is the pattern for testing HTTP clients, WebSocket handlers, gRPC streams, or any code that touches the network.

Isolation rules

Channels, timers, and tickers created inside a bubble belong to it. Using a bubbled channel from outside panics at runtime. This keeps the isolation water-tight:

A sync.WaitGroup becomes linked to a bubble on the first Add or Go call.
sync.Cond.Wait is durably blocking; waking it from outside the bubble is a fatal error.
Cleanup functions and finalizers registered with runtime.AddCleanup or runtime.SetFinalizer run outside any bubble.
synctest.Test waits for all bubble goroutines to exit before returning. If they deadlock, the test panics, no silent hangs.

A practical consequence: if your code under test uses package-level channels or WaitGroups initialized at startup, you may need to restructure so those primitives are created inside the test.

Quick reference

Concept	Details
API	`synctest.Test(t, f)` + `synctest.Wait()`: two functions, full package
Fake clock	Starts at 2000-01-01 00:00:00 UTC; advances only when all goroutines block
Durably blocking	Channel ops (bubble channels), `time.Sleep`, `sync.WaitGroup.Wait`, `sync.Cond.Wait`
Not blocking	Mutexes, network I/O, syscalls, channels created outside the bubble
Networking	Use `net.Pipe` for in-memory connections that work with `Wait`
Isolation	Bubble channels/timers panic if used from outside; `WaitGroup` binds on first `Add`/`Go`
History	Experimental in Go 1.24 (`GOEXPERIMENT=synctest`); stable since Go 1.25
Cleanup	`synctest.Test` waits for all bubble goroutines; deadlocks cause a panic

For full documentation, see the testing/synctest package docs and the official Go blog post.

Go's testing/synctest: Hands-On

The timing trap

Polling and hoping

Enter synctest

Two functions, that's it

Fake clock: time runs instantly

synctest.Wait: peeking at goroutine state

What counts as "durably blocked"

Practical patterns

Testing a periodic health checker

Testing a debouncer

Testing a producer–consumer pipeline

Networking: use net.Pipe

Isolation rules

Quick reference

Comments