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 testingon 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 testingon TestMain: "If a test file contains a functionfunc 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-tagsingo help build.- Go 1.15 release notes (go1.15.html): "A
TestMainfunction is no longer required to callos.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/mockrepo. 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 withgo 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) andsuite(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 maintaininggolang/mock): themockgentool generates mock types from an interface; tests then write expectations likem.EXPECT().Send("98", gomock.Any()).Return(nil).Times(1). - testify (
github.com/stretchr/testify):assert.Equal(t, 450, got)reports and continues (liket.Error);require.NoError(t, err)stops the test (liket.Fatal); plusmockandsuitepackages.
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 testcalls it instead of running the tests directly. Do setup, callm.Run()(runs every test, returns the exit code), then teardown. Once per package. Since Go 1.15 you may simply return;go testpassesm.Run's result toos.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 theCleanupfunctions 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 nsets how many run at once. The default isGOMAXPROCS(the number of CPUs Go uses): this machine has 2, hence 2 seconds;-parallel 3gives 1 second.- Parallel tests must not change shared things (a global map, a file, an environment variable) or they race (episode 46).
t.Setenvrefuses:
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-shortwas given;t.Skip(reason)marks the test SKIP and stops it.- A build constraint (build tag) is a
//go:build exprline at the top of a file, beforepackage, followed by a blank line. The file is only compiled when the expression is true.//go:build integrationfiles 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. Plaingo test(local directory mode) never caches.(cached): same test binary, same cacheable flags, same files and environment variables the test read →go testreplays 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
- (Homework) Build the checkout mini project (solution above).
- (Homework) Write a mock for
Paymentsthat also checks the phone number. - (Homework) Add an
Exampleto one of your packages, and see it withgo doc. - (Homework) Tag one slow test
integrationand 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
- 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.
- Fake vs stub vs mock? Fake: simple working version; stub: canned answers; mock: verifies expected calls.
- "Accept interfaces, return structs": how does it help testing? Functions that accept interfaces can be given doubles.
- Black-box vs white-box tests in Go?
package x_test(exported API only) vspackage x(internals too). - What are golden files? Approved expected output stored in
testdata, compared in tests, regenerated with a flag and reviewed. - What is TestMain for? Package-wide setup and teardown around
m.Run(). - What does
t.Paralleldo, and what's the risk? Runs the test alongside other parallel tests (up to-parallel, default GOMAXPROCS); shared state can race. - How do you separate unit and integration tests?
-shortwithtesting.Short(), or//go:build integrationfiles with-tags integration. - Why does
go testprint(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
testdatahold big expected outputs; regenerate with-updateand review. - Example tests with
// Output:are documentation that is checked. TestMainruns setup once;t.Contextis cancelled when the test ends.t.Parallel+-parallelrun tests together; never share changing state.-short,t.Skipand//go:build integration+-tagschoose what runs.- Package list mode caches passes (
(cached));-count=1runs for real.
Next episode: Benchmarks and fuzzing: testing.B, b.Loop, -bench, -benchmem, ns/op, allocs/op, benchstat, native fuzzing, FuzzXxx, the seed corpus.