SyntaxPilot
Courses/Go Programming/Lesson 41
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 41 of 89

Testing in depth

black-box tests (package foo_test)white-box teststest doubles (fakes, stubs, mocks)interfaces for testabilitygomock and testify (third-party, concept)testdata directorygolden filesExample tests with output commentsTestMaint.Parallelt.Context (Go 1.24)build tags for integration tests-short-count=1 and test caching

These are the notes for Go episode 41. Raju's PlaceOrder texts every customer through a real SMS gateway, so testing it either fails ("connection refused") or sends real messages to real people and costs real money. So you invent test doubles: an interface as a seam, then a fake, a stub and a mock in place of the gateway, and you meet gomock and testify. Then black-box and white-box tests, golden files in testdata, Example tests that check your documentation, TestMain and t.Context, running tests with t.Parallel, skipping slow tests with -short, choosing files with build tags, and how test caching and -count=1 work.

All outputs and errors here are from real runs (Go 1.24.7, linux/amd64). Timings change on every run. In the SyntaxPilot compiler, a program whose first lines are // $ go test ... is run as a package: each // ---- name ---- line starts a new file (a go.mod for module shop is added), and the commands run in order (episode 40 explains this). On your computer: go mod init shop, create the files, run the commands.

Facts and sources

  • go doc testing (Go 1.24.7): "The test file can be in the same package as the one being tested, or in a corresponding package with the suffix "_test"." … "If the test file is in a separate "_test" package, the package being tested must be imported explicitly and only its exported identifiers may be used. This is known as "black box" testing."
  • go doc testing on examples: "Example functions may include a concluding line comment that begins with "Output:" and is compared with the standard output of the function when the tests are run." and "Example functions without output comments are compiled but not executed."
  • go doc testing on TestMain: "If a test file contains a function func TestMain(m *testing.M) then the generated test will call TestMain(m) instead of running the tests or benchmarks directly." and "If TestMain returns, the test wrapper will pass the result of m.Run to os.Exit itself."
  • go doc testing.T.Context: "Context returns a context that is canceled just before Cleanup-registered functions are called." (added in Go 1.24)
  • go doc testing.T.Parallel: "Parallel signals that this test is to be run in parallel with (and only with) other parallel tests."
  • go help testflag: -parallel n "The value of this flag is the maximum number of tests to run simultaneously." "By default, -parallel is set to the value of GOMAXPROCS." -short "Tell long-running tests to shorten their run time."
  • go help test: "In package list mode only, go test caches successful package test results to avoid unnecessary repeated running of tests." "When this happens, go test prints '(cached)' in place of the elapsed time in the summary line." "The idiomatic way to disable test caching explicitly is to use -count=1."
  • go help buildconstraint: "A build constraint, also known as a build tag, is a condition under which a file should be included in the package." and -tags in go help build.
  • Go 1.15 release notes (go1.15.html): "A TestMain function is no longer required to call os.Exit."
  • go help packages: "Directory and file names that begin with "." or "_" are ignored by the go tool, as are directories named "testdata"."
  • gomock README (pkg.go.dev/go.uber.org/mock): "gomock is a mocking framework for the Go programming language." "This project originates from Google's golang/mock repo. Unfortunately, Google no longer maintains this project, and given the heavy usage of gomock in large Go projects at Uber, we've decided to fork and maintain this going forward at Uber." Install the generator with go install go.uber.org/mock/mockgen@latest.
  • testify docs (pkg.go.dev/github.com/stretchr/testify): packages assert (assertion functions), require ("provides same global functions as the assert package, but instead of returning a boolean result they terminate current test"), mock (mock objects) and suite (structs as test suites).

The problem: a test that sends real SMS

shop.go:

package shop

import (
    "fmt"
    "net/http"
    "net/url"
)

// PlaceOrder saves the order and texts the customer.
func PlaceOrder(phone, item string) error {
    msg := fmt.Sprintf("Your %s is on the way!", item)
    // the real SMS gateway: every call costs money
    _, err := http.PostForm("http://127.0.0.1:9/send",
        url.Values{"to": {phone}, "msg": {msg}})
    return err
}

shop_test.go:

package shop

import "testing"

func TestPlaceOrder(t *testing.T) {
    if err := PlaceOrder("9876543210", "chai"); err != nil {
        t.Fatal(err)
    }
}

Run in the package folder:

go test

Output (real run):

$ go test
--- FAIL: TestPlaceOrder (0.00s)
    shop_test.go:7: Post "http://127.0.0.1:9/send": dial tcp 127.0.0.1:9: connect: connection refused
FAIL
exit status 1
FAIL    shop    0.003s

An SMS gateway is a company's service that delivers text messages for a fee. Here the test fails because no gateway is running on the test machine. Where one is reachable, every go test would text a real customer, cost money, and fail whenever the network is slow (a flaky test: one that passes or fails for reasons outside the code).

Why: PlaceOrder is welded to one gateway; the test can't say "use something else for now". We need a seam: a place where the real part can be swapped out. In Go the seam is an interface (episode 21).

Test doubles: fakes, stubs and mocks (the stunt double)

On a film set In a Go test
A stunt double stands in for the star a test double: anything that satisfies the interface
A trainee who writes every message in a notebook instead of sending it a fake: a simple working version that records
A recorded announcement: the same answer every time a stub: returns a canned (pre-set) answer
A driving examiner: knows each step you must do, fails you on a missing or extra one a mock: knows the expected calls and checks them

Interfaces for testability, and a fake

Shop depends on the Notifier interface, not on the gateway. The real program passes the real gateway; the test passes FakeSMS. Dependency injection is the name for this: passing a part in from outside instead of creating it inside.

shop.go:

package shop

import "fmt"

type Notifier interface{ Send(phone, msg string) error }

type Shop struct{ N Notifier } // the real app passes the SMS gateway

func (s Shop) PlaceOrder(phone, item string) error {
    if err := s.N.Send(phone, "Your "+item+" is on the way!"); err != nil {
        return fmt.Errorf("order placed, SMS failed: %w", err)
    }
    return nil
}

shop_test.go:

package shop

import "testing"

// FakeSMS works like a gateway but only records the messages.
type FakeSMS struct{ Sent []string }

func (f *FakeSMS) Send(phone, msg string) error {
    f.Sent = append(f.Sent, phone+": "+msg)
    return nil
}

func TestPlaceOrderSendsSMS(t *testing.T) {
    fake := &FakeSMS{}
    Shop{N: fake}.PlaceOrder("9876543210", "chai")
    t.Log(fake.Sent)
    if len(fake.Sent) != 1 {
        t.Fatalf("sent %d SMS, want 1", len(fake.Sent))
    }
}

Run in the package folder:

go test -v

Output (real run):

$ go test -v
=== RUN   TestPlaceOrderSendsSMS
    shop_test.go:16: [9876543210: Your chai is on the way!]
--- PASS: TestPlaceOrderSendsSMS (0.00s)
PASS
ok      shop    0.002s

No network, no cost, milliseconds.

A stub for the failure path

shop.go:

package shop

import "fmt"

type Notifier interface{ Send(phone, msg string) error }

type Shop struct{ N Notifier } // the real app passes the SMS gateway

func (s Shop) PlaceOrder(phone, item string) error {
    if err := s.N.Send(phone, "Your "+item+" is on the way!"); err != nil {
        return fmt.Errorf("order placed, SMS failed: %w", err)
    }
    return nil
}

shop_test.go:

package shop

import (
    "errors"
    "testing"
)

// StubSMS gives the same canned answer to every call.
type StubSMS struct{ Err error }

func (s StubSMS) Send(phone, msg string) error { return s.Err }

func TestPlaceOrderGatewayDown(t *testing.T) {
    stub := StubSMS{Err: errors.New("gateway down")}
    err := Shop{N: stub}.PlaceOrder("9876543210", "chai")
    t.Log(err)
    if !errors.Is(err, stub.Err) {
        t.Fatalf("err = %v, want gateway down", err)
    }
}

Run in the package folder:

go test -v

Output (real run):

$ go test -v
=== RUN   TestPlaceOrderGatewayDown
    shop_test.go:16: order placed, SMS failed: gateway down
--- PASS: TestPlaceOrderGatewayDown (0.00s)
PASS
ok      shop    0.002s

errors.Is (episode 25) checks the stub's error is wrapped inside. Stubs make rare failures (gateway down, card declined, disk full) easy to test.

A mock that checks the calls

shop.go:

package shop

type Notifier interface{ Send(phone, msg string) error }

type Shop struct{ N Notifier }

func (s Shop) PlaceOrder(phone, item string) {
    s.N.Send(phone, "Your "+item+" is on the way!")
    s.N.Send(phone, "Your "+item+" is on the way!") // bug: twice
}

shop_test.go:

package shop

import "testing"

// MockSMS is told which calls to expect, and checks them.
type MockSMS struct {
    t     *testing.T
    want  []string
    calls int
}

func (m *MockSMS) Send(phone, msg string) error {
    if m.calls >= len(m.want) || m.want[m.calls] != msg {
        m.t.Errorf("unexpected Send(%q, %q)", phone, msg)
    }
    m.calls++
    return nil
}

func TestPlaceOrder(t *testing.T) {
    mock := &MockSMS{t: t, want: []string{"Your chai is on the way!"}}
    Shop{N: mock}.PlaceOrder("9876543210", "chai")
    if mock.calls != len(mock.want) {
        t.Errorf("Send called %d times, want %d", mock.calls, len(mock.want))
    }
}

Run in the package folder:

go test

Output (real run):

$ go test
--- FAIL: TestPlaceOrder (0.00s)
    shop_test.go:14: unexpected Send("9876543210", "Your chai is on the way!")
    shop_test.go:24: Send called 2 times, want 1
FAIL
exit status 1
FAIL    shop    0.002s

The mock is told the expected calls up front, checks each call as it arrives, and the test checks the count at the end: it catches the duplicate SMS.

Double Does Use it to
Fake a simple working version (records, keeps data in a map) check what the code did
Stub returns pre-set answers force a situation (an error, a value)
Mock knows the expected calls; fails on wrong, missing or extra ones check the interaction itself

gomock and testify (third-party)

  • gomock (go.uber.org/mock, maintained by Uber since Google stopped maintaining golang/mock): the mockgen tool generates mock types from an interface; tests then write expectations like m.EXPECT().Send("98", gomock.Any()).Return(nil).Times(1).
  • testify (github.com/stretchr/testify): assert.Equal(t, 450, got) reports and continues (like t.Error); require.NoError(t, err) stops the test (like t.Fatal); plus mock and suite packages.

Both are third-party (not in the standard library; add them with go get). The standard testing package is all you need to start, and many Go teams use only it.

Black-box vs white-box tests

Black-box White-box
Package clause package shop_test package shop
Sees only exported names, via import "shop" everything, including unexported names
Like a customer who sees the menu a chef inside the kitchen

shop.go:

package shop

func Bill(amount int) int {
    return amount - discount(amount)
}

// discount is unexported: lowercase, private to package shop
func discount(amount int) int {
    if amount >= 500 {
        return amount / 10
    }
    return 0
}

shop_test.go:

package shop_test // black-box: outside the package

import (
    "shop"
    "testing"
)

func TestBill(t *testing.T) {
    if got := shop.Bill(500); got != 450 {
        t.Errorf("Bill(500) = %d, want 450", got)
    }
    if got := shop.discount(500); got != 50 {
        t.Errorf("discount(500) = %d, want 50", got)
    }
}

Run in the package folder:

go test

Output (real run):

$ go test
FAIL    shop [build failed]
# shop_test [shop.test]
./shop_test.go:12:20: name discount not exported by package shop

shop.go:

package shop

func Bill(amount int) int {
    return amount - discount(amount)
}

func discount(amount int) int { // unexported
    if amount >= 500 {
        return amount / 10
    }
    return 0
}

bill_test.go:

package shop_test // black-box: only the public API

import (
    "shop"
    "testing"
)

func TestBill(t *testing.T) {
    if got := shop.Bill(500); got != 450 {
        t.Errorf("Bill(500) = %d, want 450", got)
    }
}

discount_test.go:

package shop // white-box: inside, sees unexported names

import "testing"

func TestDiscount(t *testing.T) {
    if got := discount(500); got != 50 {
        t.Errorf("discount(500) = %d, want 50", got)
    }
}

Run in the package folder:

go test -v

Output (real run):

$ go test -v
=== RUN   TestDiscount
--- PASS: TestDiscount (0.00s)
=== RUN   TestBill
--- PASS: TestBill (0.00s)
PASS
ok      shop    0.006s

Both kinds can live in the same folder. Prefer black-box tests for behaviour; use white-box tests for tricky internals.

testdata and golden files (the reference photo)

In a restaurant kitchen In a Go test
A photo of the perfect thali; every plate is compared to it a golden file: the saved, approved output
The cupboard for reference photos the testdata folder, ignored by the go tool
New menu? Take a new photo, on purpose an -update flag that rewrites the golden file

flag.Bool("update", false, "...") defines a command-line flag (an option typed after the command, like -update) for the test binary. Flags get their own episode later.

shop.go:

package shop

import "fmt"

func line(name string, rs int) string {
    return fmt.Sprintf("%-8s Rs %3d\n", name, rs) // new: width 3
}

func Receipt(chai, samosa int) string {
    return "--- Raju's Chai ---\n" + line("chai", chai) +
        line("samosa", samosa) + line("TOTAL", chai+samosa)
}

shop_test.go:

package shop

import (
    "flag"
    "os"
    "testing"
)

var update = flag.Bool("update", false, "rewrite golden files")

func TestReceipt(t *testing.T) {
    got := Receipt(40, 30)
    golden := "testdata/receipt.golden"
    if *update {
        os.WriteFile(golden, []byte(got), 0o644)
    }
    want, _ := os.ReadFile(golden)
    if got != string(want) {
        t.Errorf("got:\n%s\nwant:\n%s", got, want)
    }
}

testdata/receipt.golden:

--- Raju's Chai ---
chai     Rs 40
samosa   Rs 30
TOTAL    Rs 70

Run in the package folder:

go test
go test -update

Output (real run):

$ go test
--- FAIL: TestReceipt (0.00s)
    shop_test.go:19: got:
        --- Raju's Chai ---
        chai     Rs  40
        samosa   Rs  30
        TOTAL    Rs  70

        want:
        --- Raju's Chai ---
        chai     Rs 40
        samosa   Rs 30
        TOTAL    Rs 70
FAIL
exit status 1
FAIL    shop    0.006s
$ go test -update
PASS
ok      shop    0.002s

The first run shows got and want: the new layout pads prices to 3 characters (Rs 40). The change was intended, so go test -update rewrote the golden file. Review the golden file's diff before committing: if a change was an accident, the golden file is what catches it.

Example tests

A function ExampleXxx in a _test.go file is both a test and documentation: go test runs it and compares what it printed with the // Output: comment; go doc and pkg.go.dev show it as a usage example. ExampleBill documents Bill; a suffix after _ starting with a lowercase letter (ExampleBill_edge) adds more examples.

shop.go:

package shop

// Bill gives 10% off on orders of Rs 500 or more.
func Bill(amount int) int {
    if amount >= 500 {
        return amount * 90 / 100
    }
    return amount
}

example_test.go:

package shop_test

import (
    "fmt"
    "shop"
)

func ExampleBill() {
    fmt.Println(shop.Bill(300))
    fmt.Println(shop.Bill(800))
    // Output:
    // 300
    // 720
}

func ExampleBill_edge() {
    fmt.Println(shop.Bill(500))
    // Output: 500
}

Run in the package folder:

go test -v

Output (real run):

$ go test -v
=== RUN   ExampleBill
--- PASS: ExampleBill (0.00s)
=== RUN   ExampleBill_edge
--- FAIL: ExampleBill_edge (0.00s)
got:
450
want:
500
FAIL
exit status 1
FAIL    shop    0.002s

An Example without an // Output: comment is compiled but not run. // Unordered output: compares lines in any order.

TestMain and t.Context

shop_test.go:

package shop

import (
    "fmt"
    "testing"
)

func TestMain(m *testing.M) {
    fmt.Println("setup: start the test database (once)")
    code := m.Run() // runs every test
    fmt.Println("teardown: stop the database, exit code", code)
}

func TestOrders(t *testing.T) {
    ctx := t.Context() // Go 1.24: cancelled when the test ends
    t.Cleanup(func() {
        fmt.Println("in cleanup, ctx:", ctx.Err())
    })
    fmt.Println("during the test, ctx:", ctx.Err())
}

func TestMenu(t *testing.T) {} // a second test, same setup

Run in the package folder:

go test -v

Output (real run):

$ go test -v
setup: start the test database (once)
=== RUN   TestOrders
during the test, ctx: <nil>
in cleanup, ctx: context canceled
--- PASS: TestOrders (0.00s)
=== RUN   TestMenu
--- PASS: TestMenu (0.00s)
PASS
teardown: stop the database, exit code 0
ok      shop    0.002s
  • TestMain(m *testing.M): if a test file defines it, go test calls it instead of running the tests directly. Do setup, call m.Run() (runs every test, returns the exit code), then teardown. Once per package. Since Go 1.15 you may simply return; go test passes m.Run's result to os.Exit.
  • t.Context() (Go 1.24): a context is a value that carries a "stop now" signal to code that's doing work (it gets its own episode later). t.Context() is cancelled when the test ends, just before the Cleanup functions run, so code under test can stop its goroutines.

t.Parallel (one stove vs three stoves)

shop_test.go:

package shop

import (
    "testing"
    "time"
)

// each test waits 1 second, like a slow API call
func TestChai(t *testing.T) {
    t.Parallel() // may run at the same time as other parallel tests
    time.Sleep(time.Second)
}

func TestSamosa(t *testing.T) {
    t.Parallel()
    time.Sleep(time.Second)
}

func TestLassi(t *testing.T) {
    t.Parallel()
    time.Sleep(time.Second)
}

Run in the package folder:

go test -parallel 1 .
go test .
go test -parallel 3 .

Output (real run):

$ go test -parallel 1 .
ok      shop    3.003s
$ go test .
ok      shop    2.003s
$ go test -parallel 3 .
ok      shop    1.003s
  • By default, tests in a package run one after another.
  • t.Parallel() marks a test as allowed to run at the same time as other parallel tests.
  • -parallel n sets how many run at once. The default is GOMAXPROCS (the number of CPUs Go uses): this machine has 2, hence 2 seconds; -parallel 3 gives 1 second.
  • Parallel tests must not change shared things (a global map, a file, an environment variable) or they race (episode 46). t.Setenv refuses:

shop_test.go:

package shop

import "testing"

func TestCity(t *testing.T) {
    t.Parallel()
    t.Setenv("SHOP_CITY", "Pune")
}

Run in the package folder:

go test

Output (real run):

$ go test
--- FAIL: TestCity (0.00s)
panic: testing: test using t.Setenv or t.Chdir can not use t.Parallel [recovered]
    panic: testing: test using t.Setenv or t.Chdir can not use t.Parallel

goroutine 18 [running]:
testing.tRunner.func1.2({0x548800, 0x5b0cd0})
    /usr/local/go1.24.7/src/testing/testing.go:1734 +0x21c
testing.tRunner.func1()
    /usr/local/go1.24.7/src/testing/testing.go:1737 +0x35e
panic({0x548800?, 0x5b0cd0?})
    /usr/local/go1.24.7/src/runtime/panic.go:792 +0x132
testing.(*T).checkParallel(...)
    /usr/local/go1.24.7/src/testing/testing.go:1604
testing.(*T).Setenv(0xc000124380?, {0x578f43?, 0xc00005a760?}, {0x57826b?, 0x492db3?})
    /usr/local/go1.24.7/src/testing/testing.go:1618 +0x65
shop.TestCity(0xc000124380)
    shop_test.go:7 +0x3a
testing.tRunner(0xc000124380, 0x5856c0)
    /usr/local/go1.24.7/src/testing/testing.go:1792 +0xf4
created by testing.(*T).Run in goroutine 1
    /usr/local/go1.24.7/src/testing/testing.go:1851 +0x413
exit status 2
FAIL    shop    0.005s

-short and build tags

shop_test.go:

package shop

import (
    "testing"
    "time"
)

func TestBill(t *testing.T) {} // fast unit test

func TestMonthlyReport(t *testing.T) {
    if testing.Short() {
        t.Skip("slow: skipped with -short")
    }
    time.Sleep(2 * time.Second) // 30 days of orders
}

db_test.go:

//go:build integration

package shop

import "testing"

// needs a real database: only with -tags integration
func TestRealDatabase(t *testing.T) {
    t.Log("connected to the staging database")
}

Run in the package folder:

go test -v -short
go test -v
go test -v -tags integration

Output (real run):

$ go test -v -short
=== RUN   TestBill
--- PASS: TestBill (0.00s)
=== RUN   TestMonthlyReport
    shop_test.go:12: slow: skipped with -short
--- SKIP: TestMonthlyReport (0.00s)
PASS
ok      shop    0.004s
$ go test -v
=== RUN   TestBill
--- PASS: TestBill (0.00s)
=== RUN   TestMonthlyReport
--- PASS: TestMonthlyReport (2.00s)
PASS
ok      shop    2.002s
$ go test -v -tags integration
=== RUN   TestRealDatabase
    db_test.go:9: connected to the staging database
--- PASS: TestRealDatabase (0.00s)
=== RUN   TestBill
--- PASS: TestBill (0.00s)
=== RUN   TestMonthlyReport
--- PASS: TestMonthlyReport (2.00s)
PASS
ok      shop    2.002s
  • testing.Short() is true when -short was given; t.Skip(reason) marks the test SKIP and stops it.
  • A build constraint (build tag) is a //go:build expr line at the top of a file, before package, followed by a blank line. The file is only compiled when the expression is true. //go:build integration files are compiled only with -tags integration. Other common tags: linux, windows, amd64, !race.
  • An integration test checks several real parts together (a real database, a real HTTP server); a unit test checks one piece alone.
  • Typical workflow: go test -short ./... many times a day; go test -tags integration ./... in CI before release.

Test caching and -count=1

shop.go:

package shop

func Bill(amount int) int {
    if amount >= 500 {
        return amount * 90 / 100
    }
    return amount
}

shop_test.go:

package shop

import (
    "testing"
    "time"
)

func TestBill(t *testing.T) {
    time.Sleep(time.Second) // a slow test
    if Bill(500) != 450 {
        t.Error("Bill(500) wrong")
    }
}

Run in the package folder:

go test .
go test .
go test -count=1 .

Output (real run):

$ go test .
ok      shop    1.003s
$ go test .
ok      shop    (cached)
$ go test -count=1 .
ok      shop    1.010s
  • go test . (or ./...) is package list mode: you name the packages. Only this mode caches. Plain go test (local directory mode) never caches.
  • (cached): same test binary, same cacheable flags, same files and environment variables the test read → go test replays the saved result. Change anything relevant and it runs again.
  • A cached pass can hide a failure caused by something outside (a database, the clock, a remote API). -count=1 (run each test once) is the idiomatic way to turn caching off.

Mini project: test an order service

Checkout charges the customer through a Payments interface and then sends the SMS. Test that a failed payment sends no SMS (stub Payments + fake SMS), and that Charge is called exactly once with the right total (a mock). For the receipt, add a golden file with -update, as in the GOLDEN program.

Solution

shop.go:

package shop

import "fmt"

type Notifier interface{ Send(phone, msg string) error }
type Payments interface{ Charge(phone string, rs int) error }

type Shop struct {
    N Notifier
    P Payments
}

// Checkout charges the customer, then texts them.
func (s Shop) Checkout(phone string, cart map[string]int) error {
    total := 0
    for _, rs := range cart {
        total += rs
    }
    if err := s.P.Charge(phone, total); err != nil {
        return fmt.Errorf("checkout: %w", err) // no SMS if not paid
    }
    return s.N.Send(phone, fmt.Sprintf("Paid Rs %d. Thank you!", total))
}

shop_test.go:

package shop

import (
    "errors"
    "testing"
)

type FakeSMS struct{ Sent []string }

func (f *FakeSMS) Send(phone, msg string) error {
    f.Sent = append(f.Sent, msg)
    return nil
}

type StubPay struct{ Err error }

func (s StubPay) Charge(string, int) error { return s.Err }

type MockPay struct {
    t     *testing.T
    want  int
    calls int
}

func (m *MockPay) Charge(phone string, rs int) error {
    m.calls++
    if rs != m.want {
        m.t.Errorf("Charge(%q, %d), want Rs %d", phone, rs, m.want)
    }
    return nil
}

func TestCheckoutPaymentFails(t *testing.T) {
    sms := &FakeSMS{}
    s := Shop{N: sms, P: StubPay{errors.New("card declined")}}
    err := s.Checkout("98", map[string]int{"chai": 40})
    t.Log(err)
    if err == nil || len(sms.Sent) != 0 {
        t.Fatalf("err = %v, sent %v; want an error and no SMS", err, sms.Sent)
    }
}

func TestCheckoutChargesOnce(t *testing.T) {
    pay := &MockPay{t: t, want: 70}
    sms := &FakeSMS{}
    Shop{N: sms, P: pay}.Checkout("98", map[string]int{"chai": 40, "samosa": 30})
    if pay.calls != 1 {
        t.Errorf("Charge called %d times, want 1", pay.calls)
    }
    t.Log(sms.Sent)
}

Run in the package folder:

go test -v

Output (real run):

$ go test -v
=== RUN   TestCheckoutPaymentFails
    shop_test.go:37: checkout: card declined
--- PASS: TestCheckoutPaymentFails (0.00s)
=== RUN   TestCheckoutChargesOnce
    shop_test.go:50: [Paid Rs 70. Thank you!]
--- PASS: TestCheckoutChargesOnce (0.00s)
PASS
ok      shop    0.002s

Common mistakes (and the real messages)

Mistake Real message / result Why Fix
tests call the real SMS gateway dial tcp 127.0.0.1:9: connect: connection refused no seam interface + test double
black-box test uses discount name discount not exported by package shop outside the package test via Bill, or package shop
a wrong // Output: got: 450 want: 500 example out of date fix the example
t.Setenv in a parallel test panic: testing: test using t.Setenv or t.Chdir can not use t.Parallel env is process-wide no t.Parallel there
trusting a cached pass ok shop (cached) outside state changed -count=1
golden file updated blindly test passes, bug committed -update accepts anything review the diff
//go:build after the package line not a constraint: the file is always built constraints must come before package move it to the top

Practice

  1. (Homework) Build the checkout mini project (solution above).
  2. (Homework) Write a mock for Payments that also checks the phone number.
  3. (Homework) Add an Example to one of your packages, and see it with go doc.
  4. (Homework) Tag one slow test integration and run it only with -tags integration.
Solution 2

Add a phone string field to MockPay and check it in Charge: if phone != m.phone { m.t.Errorf("Charge to %q, want %q", phone, m.phone) }.

Solution 3

In example_test.go, func ExampleBill() { fmt.Println(shop.Bill(800)) // Output: 720 } (with the comment on its own line), then go doc -all shop or the pkg.go.dev page shows it under Bill.

Quick quiz

1. go test . passes in about a second. You run it again without changing anything. What does it print? (From the video.)

A. ok shop (cached) · B. ok shop 1.003s · C. ? shop [no test files] · D. FAIL shop

Answer

A. Nothing changed and only cacheable flags were used. See the caching program above; -count=1 runs it for real.

2. A test should check that PlaceOrder returns an error when the gateway is down. Fake, stub or mock?

Answer

A stub that returns the error.

3. Can a test in package shop_test call shop.discount?

Answer

No: black-box tests see only exported names.

4. Where do golden files go, and why there?

Answer

In testdata/: the go tool ignores directories named testdata.

Interview questions

  1. How do you test code that calls an external service? Depend on an interface; inject a fake, stub or mock in tests; keep real calls for integration tests.
  2. Fake vs stub vs mock? Fake: simple working version; stub: canned answers; mock: verifies expected calls.
  3. "Accept interfaces, return structs": how does it help testing? Functions that accept interfaces can be given doubles.
  4. Black-box vs white-box tests in Go? package x_test (exported API only) vs package x (internals too).
  5. What are golden files? Approved expected output stored in testdata, compared in tests, regenerated with a flag and reviewed.
  6. What is TestMain for? Package-wide setup and teardown around m.Run().
  7. What does t.Parallel do, and what's the risk? Runs the test alongside other parallel tests (up to -parallel, default GOMAXPROCS); shared state can race.
  8. How do you separate unit and integration tests? -short with testing.Short(), or //go:build integration files with -tags integration.
  9. Why does go test print (cached), and how do you force a rerun? Package list mode caches passing results; -count=1.

Glossary

Term Meaning Example
SMS gateway a service that delivers text messages for a fee the server at 127.0.0.1:9
Flaky test a test that passes or fails for reasons outside the code fails when the network is slow
Seam a place where a part can be swapped for another the Notifier interface
Testability how easy code is to test depending on interfaces
Dependency injection passing a part in from outside instead of creating it inside Shop{N: fake}
Test double a stand-in for a real part in a test FakeSMS
Fake a simple working double that records or stores FakeSMS.Sent
Stub a double that returns canned answers StubSMS{Err: ...}
Mock a double that knows the expected calls and checks them MockSMS
gomock a third-party mocking framework (go.uber.org/mock) mockgen
mockgen gomock's tool that generates mocks from interfaces go install go.uber.org/mock/mockgen@latest
testify a third-party testing toolkit: assert, require, mock, suite assert.Equal(t, 450, got)
assert / require testify checks that continue / stop the test require.NoError(t, err)
Third-party package code from outside the standard library github.com/stretchr/testify
Black-box test a test outside the package, public API only package shop_test
White-box test a test inside the package, sees internals package shop
testdata a folder the go tool ignores; holds test files testdata/receipt.golden
Golden file saved approved output compared in a test receipt.golden
Command-line flag an option typed after a command -update
-update a custom flag that rewrites golden files go test -update
Example test ExampleXxx with // Output:; test and documentation ExampleBill
// Output: the expected printed output of an Example // Output: 450
TestMain func TestMain(m *testing.M): runs around all tests setup, m.Run(), teardown
*testing.M the handle TestMain gets; m.Run() runs the tests code := m.Run()
Context a value carrying a stop signal to code doing work ctx.Err()
t.Context a context cancelled when the test ends (Go 1.24) ctx := t.Context()
t.Parallel allow the test to run alongside other parallel tests t.Parallel()
-parallel n maximum tests running at once (default GOMAXPROCS) go test -parallel 3
GOMAXPROCS how many CPUs Go runs code on at once 2 on this machine
Race two goroutines changing shared data at once a shared map
-short / testing.Short flag and check to shorten slow tests if testing.Short() { t.Skip(...) }
t.Skip stop a test and mark it SKIP t.Skip("slow")
Build constraint / build tag //go:build expr: include a file only when true //go:build integration
-tags turn build tags on go test -tags integration
Integration test checks several real parts together a real database
Package list mode go test with packages named (., ./...) go test .
Local directory mode go test with no packages; never caches go test
Test caching replaying a saved passing result ok shop (cached)
-count=1 run each test once; disables the cache go test -count=1 .

Summary

  • Code that calls real services makes tests slow, costly and flaky: depend on an interface and inject a test double.
  • Fake records, stub gives canned answers, mock checks expected calls; gomock and testify help in bigger projects.
  • package shop_test = black-box (public API); package shop = white-box.
  • Golden files in testdata hold big expected outputs; regenerate with -update and review.
  • Example tests with // Output: are documentation that is checked.
  • TestMain runs setup once; t.Context is cancelled when the test ends.
  • t.Parallel + -parallel run tests together; never share changing state.
  • -short, t.Skip and //go:build integration + -tags choose what runs.
  • Package list mode caches passes ((cached)); -count=1 runs for real.

Next episode: Benchmarks and fuzzing: testing.B, b.Loop, -bench, -benchmem, ns/op, allocs/op, benchstat, native fuzzing, FuzzXxx, the seed corpus.