Testcontainers ใช้จริง — TestMain, suite และ sync.Once

1 · ต้นทุนที่แท้จริงของ "container ต่อหนึ่งเทส"

ผมเขียนเทส 4 ตัวที่เหมือนกันเป๊ะ ต่างกันแค่วิธีจัดการ container แบบแรกคือแบบที่ทุกคนเขียนโดยธรรมชาติ — Run ต้นเทส Terminate ท้ายเทส:

=== RUN   TestFreshA
    percontainer_test.go:42: fresh container boot=1.015561625s dsn=postgres://testuser:testpass@localhost:32778/testdb?sslmode=disable
--- PASS: TestFreshA (1.16s)
=== RUN   TestFreshB
    percontainer_test.go:52: fresh container boot=755.348ms dsn=postgres://testuser:testpass@localhost:32779/testdb?sslmode=disable
--- PASS: TestFreshB (0.90s)
=== RUN   TestFreshC
    percontainer_test.go:62: fresh container boot=752.309917ms dsn=postgres://testuser:testpass@localhost:32780/testdb?sslmode=disable
--- PASS: TestFreshC (0.88s)
=== RUN   TestFreshD
    percontainer_test.go:72: fresh container boot=761.385084ms dsn=postgres://testuser:testpass@localhost:32781/testdb?sslmode=disable
--- PASS: TestFreshD (0.91s)
PASS
ok  	tcdemo/test/percontainer	4.264s

อ่านตัวเลขให้ออก: ตัวแรกแพงกว่าเพื่อน (1.01s) เพราะครั้งแรกของการรันหนึ่งครั้ง testcontainers จะแอบเปิด container ผู้ช่วยอีกตัวชื่อ Ryuk ขึ้นมาด้วย (Ryuk คือ container ตัวจิ๋วที่คอยตามลบ container ที่เราลืมปิด — หัวข้อ 7 จะพิสูจน์ให้ดูว่ามันทำงานยังไง ตอนนี้รู้แค่ว่ามันกินเวลาของเทสตัวแรกไปราว 0.25 วินาทีก็พอ)
ตัวถัด ๆ ไปไม่ต้องเปิด Ryuk ซ้ำ จึงเหลือประมาณ 0.75 วินาทีเท่ากันหมด
แปลว่าต้นทุนของการเพิ่มเทสอีก 1 ตัว คือ ~760 มิลลิวินาที — โปรเจกต์ที่มี 60 เทสก็คือรอ 45 วินาทีทุกครั้งที่กด save

2 · sync.Once — เปิดครั้งเดียว ใช้ทั้ง package

ใน บทเรียน 24 คุณเรียนว่า package sync มีไว้ประสานงานระหว่าง goroutine
sync.Once คืออีกตัวในตระกูลเดียวกัน สัญญาของมันสั้นมาก: โค้ดใน Do(f) จะรันแค่ครั้งเดียวตลอดอายุของ process ต่อให้ถูกเรียกพร้อมกันจากหลาย goroutine ก็ตาม — คนที่มาทีหลังจะรอจนตัวแรกทำเสร็จ

var (
    sharedOnce sync.Once
    sharedCtr  *tcpostgres.PostgresContainer
    sharedDB   *gorm.DB
    sharedDSN  string
    sharedErr  error
    SharedBoot time.Duration
)

// SharedDB คืน DB ที่ใช้ร่วมกันทั้ง process โดย boot container แค่ครั้งเดียว
func SharedDB(t *testing.T) (*gorm.DB, string) {
    t.Helper()  // ทำให้ error ชี้ไปที่เทสที่เรียก ไม่ใช่ชี้มาที่ฟังก์ชันนี้ — หัวข้อ 6 จะพิสูจน์ให้ดู
    sharedOnce.Do(func() {
        ctx := context.Background()
        var d time.Duration
        sharedCtr, d, sharedErr = StartPostgres(ctx)
        SharedBoot = d
        if sharedErr != nil {
            return
        }
        sharedDB, sharedDSN, sharedErr = OpenGorm(ctx, sharedCtr)
        log.Printf("[sync.Once] container booted in %v dsn=%s", d, sharedDSN)
    })
    if sharedErr != nil {
        t.Fatalf("shared container failed: %v", sharedErr)
    }
    return sharedDB, sharedDSN
}

จุดที่คนมักพลาด: ต้องเก็บ sharedErr ไว้นอก Do
เพราะถ้า container พังในการเรียกครั้งแรก Do จะไม่รันซ้ำให้เทสตัวที่สอง — เทสตัวที่สองต้องรู้ว่า "ตัวแรกพังไปแล้ว" จาก error ที่เก็บไว้ ไม่งั้นมันจะได้ nil แล้ว panic แทน

เอาโค้ดเทส 4 ตัวเดิมเป๊ะ ๆ มาเปลี่ยนแค่บรรทัดที่ขอ DB:

=== RUN   TestSharedA
2026/08/18 19:55:05 [sync.Once] container booted in 1.03324475s dsn=postgres://testuser:testpass@localhost:32783/testdb?sslmode=disable
    sharedcontainer_test.go:41: A total=1.056020208s
--- PASS: TestSharedA (1.06s)
=== RUN   TestSharedB
    sharedcontainer_test.go:36: shared dsn=postgres://testuser:testpass@localhost:32783/testdb?sslmode=disable
    sharedcontainer_test.go:41: B total=2.067417ms
--- PASS: TestSharedB (0.00s)
=== RUN   TestSharedC
    sharedcontainer_test.go:41: C total=1.95025ms
--- PASS: TestSharedC (0.00s)
=== RUN   TestSharedD
    sharedcontainer_test.go:41: D total=1.747666ms
--- PASS: TestSharedD (0.00s)
PASS
[TestMain] shared container boot time = 1.03324475s
ok  	tcdemo/test/sharedcontainer	1.727s

หมายเหตุ: เทสทั้งสี่เรียก helper ตัวเดียวกัน (สังเกตว่า total= ชี้ที่ :41 เหมือนกันหมด) ดังนั้นบรรทัด shared dsn= ที่ :36 จริง ๆ พิมพ์ออกมาครบทั้ง A B C D — ในบล็อกนี้ตัดของ A, C, D ออก เพราะซ้ำกับของ B ทุกตัวอักษร (dsn เดียวกัน port เดียวกัน)

container ใหม่ทุกเทส : 4.264s   (boot 1.015 / 0.755 / 0.752 / 0.761)
sync.Once ตัวเดียว   : 1.727s   (boot 1.033 ครั้งเดียว · เทสถัดไป 2.07 / 1.95 / 1.75 ms)

                       เร็วขึ้น 2.47 เท่า ที่ 4 เทส
ต้นทุนต่อเทสที่เพิ่มมา : 760 ms  →  2 ms   (ต่างกัน ~380 เท่า)

3 · TestMain — ประตูเข้าออกของทั้ง package

sync.Once ตอบเรื่อง "เปิดครั้งเดียว" ได้ แต่ยังเหลือคำถามว่า แล้วใครปิด? — defer ในเทสตัวไหนก็ผิดหมด เพราะเทสตัวอื่นยังใช้ container นั้นอยู่
Go มีฟังก์ชันพิเศษชื่อ TestMain ให้ครอบการรันเทสทั้ง package:

func TestMain(m *testing.M) {
    code := m.Run()          // ← เทสทุกตัวใน package รันตรงบรรทัดนี้
    testutil.TerminateShared()  // ← cleanup หลังเทสจบครบแล้ว
    fmt.Printf("[TestMain] shared container boot time = %v\n", testutil.SharedBoot)
    os.Exit(code)             // ← ส่งผลแพ้ชนะออกไปเป็น exit code
}

4 · -short ที่ได้ผลจริง ๆ กับที่ได้ผลแค่ในสไลด์

testing.Short() คืนค่า true เมื่อรันด้วย go test -short ใช้คู่กับ t.Skip เพื่อบอกว่า "เทสนี้หนัก ข้ามไปก่อน":

func TestWrongTable(t *testing.T) {
    if testing.Short() {
        t.Skip("short mode: no docker")
    }
    ...
}

แต่ก่อนจะเชื่อว่ามันช่วยจริง ลองอ่านโค้ดนี้ให้ดี:

// main_test.go — คนเขียนอยากประหยัด จึงเช็ค -short ตั้งแต่ TestMain
func TestMain(m *testing.M) {
    fmt.Println("about to call testing.Short() before m.Run()...")

    if !testing.Short() {          // ← บรรทัดนี้
        bootContainer()
    }

    code := m.Run()
    os.Exit(code)
}

about to call testing.Short() before m.Run()...
panic: testing: Short called before Parse

goroutine 1 [running]:
testing.Short(...)
	/Users/tuwanon/.local/share/mise/installs/go/1.26.5/src/testing/testing.go:693
tcdemo/test/eager.TestMain(0x6e0a31b128c0)
	/private/tmp/.../test/eager/eager_test.go:23 +0x27c
main.main()
	_testmain.go:48 +0x88
FAIL	tcdemo/test/eager	0.304s

func TestMain(m *testing.M) {
    flag.Parse()
    fmt.Printf("ใน TestMain หลัง flag.Parse(): testing.Short() = %v\n", testing.Short())
    os.Exit(m.Run())
}

$ go test -v
ใน TestMain หลัง flag.Parse(): testing.Short() = false

$ go test -short -v
ใน TestMain หลัง flag.Parse(): testing.Short() = true

eager vs lazy — ต่างกันตรงไหน

func TestMain(m *testing.M) {
    ctr, _ := tcpostgres.Run(...)
    code := m.Run()
    ctr.Terminate(ctx)
    os.Exit(code)
}

func TestMain(m *testing.M) {
    code := m.Run()
    testutil.TerminateShared()
    os.Exit(code)
}

ทีนี้เอา TestMain ฝั่ง eager มาแก้ให้รันได้จริงก่อน — เอาบรรทัด testing.Short() ที่ทำให้ panic ออก เหลือแค่ boot container ตรง ๆ แล้วเทียบกับฝั่ง lazy ด้วยคำสั่งเดียวกัน:

// go test -short -v ./test/eager/      ← eager (แก้ให้ไม่เรียก testing.Short() แล้ว)
[eager TestMain] container booted BEFORE m.Run() in 1.047302208s
=== RUN   TestEagerOne
    eager_test.go:45: short mode: skipped, but the container was ALREADY started
--- SKIP: TestEagerOne (0.00s)
PASS
ok  	tcdemo/test/eager	1.673s

// go test -short -v ./test/integration/   ← lazy
--- SKIP: TestSearchByCity_CaughtByRealPostgres (0.00s)
--- SKIP: TestTypoInColumn (0.00s)
--- SKIP: TestWrongTable (0.00s)
--- SKIP: TestNilSliceMatrix (0.00s)
--- SKIP: TestSharedA (0.00s)
--- SKIP: TestSharedB (0.00s)
--- SKIP: TestSharedC (0.00s)
--- SKIP: TestUserRepoSuite (0.00s)
PASS
[TestMain] shared container boot time = 0s
ok  	tcdemo/test/integration	0.353s

5 · testify suite — SetupSuite ไม่ใช่ SetupTest

ใน บทเรียน 17 คุณใช้ testify แค่ฝั่ง assert/require — package suite คืออีกครึ่งที่ยังไม่ได้แตะ มันให้ struct หนึ่งตัวถือ state ร่วม (db, repo, ctx) แล้วมี hook ให้แขวนงานเตรียมของ
มีกติกา 3 ข้อที่ต้องรู้ก่อนอ่านโค้ดข้างล่าง:
1. บรรทัด suite.Suite ที่เขียนลอย ๆ ไม่มีชื่อ field คือการฝัง struct ของ testify เข้ามาในของเรา ผลคือ struct ของคุณได้ method ของ testify ติดมาฟรี ตัวที่ใช้บ่อยที่สุดคือ s.T() ซึ่งคืน *testing.T ของเทสที่กำลังรันอยู่ตอนนั้น เอาไว้ส่งต่อให้ฟังก์ชันที่ต้องการ *testing.T เช่น testutil.SharedDB(s.T())
2. เฉพาะ method ที่ชื่อขึ้นต้นด้วย Test เท่านั้นที่จะถูกรันเป็นเทส ถ้าตั้งชื่อว่า CreateAndGet เฉย ๆ จะไม่มีอะไรเกิดขึ้นและไม่มี error ฟ้องเลย — เทสหายไปเงียบ ๆ แล้วขึ้น PASS
3. testify ไม่ได้ถูก go test เห็นเอง ต้องมีเทสธรรมดา 1 ตัว (func TestUserRepoSuite(t *testing.T)) เรียก suite.Run(t, new(UserRepoSuite)) เป็นประตูเข้า อย่างที่เห็นบรรทัดสุดท้ายของโค้ด

type UserRepoSuite struct {
    suite.Suite
    db   *gorm.DB
    dsn  string
    repo *repository.UserRepository
    ctx  context.Context
}

// SetupSuite — รันครั้งเดียวทั้ง suite: ขอ container ที่ share ไว้
func (s *UserRepoSuite) SetupSuite() {
    if testing.Short() {
        s.T().Skip("skipping integration suite in -short mode")
    }
    s.ctx = context.Background()
    s.db, s.dsn = testutil.SharedDB(s.T())
    s.repo = repository.NewUserRepository(s.db)
}

// SetupTest — รันก่อนทุกเทส: ล้างตาราง ไม่ต้องเปิด container ใหม่
func (s *UserRepoSuite) SetupTest() {
    testutil.TruncateUsers(s.T(), s.db)
}

func TestUserRepoSuite(t *testing.T) {
    suite.Run(t, new(UserRepoSuite))
}

ลำดับ hook ทั้งหมด ผมรันจริงกับ suite ที่มี 2 เทส ได้แบบนี้:

  SetupSuite                          ←  1 ครั้ง
    SetupTest                         ┐
      BeforeTest(OrderSuite, TestApple)│
        >> body TestApple             │ ← ทุกเทส
      AfterTest(OrderSuite, TestApple) │
    TearDownTest                      ┘
    SetupTest
      BeforeTest(OrderSuite, TestZebra)
        >> body TestZebra
      AfterTest(OrderSuite, TestZebra)
    TearDownTest
  TearDownSuite                       ←  1 ครั้ง

BeforeTest/AfterTest เป็นของแถมที่สไลด์ไม่ได้พูดถึง — มันรับ (suiteName, testName string) เข้ามาด้วย เอาไว้ log หรือตั้งชื่อ schema แยกต่อเทสได้

// ในไฟล์ ผมประกาศ TestZebra ไว้ "ก่อน" TestApple

func (s *OrderSuite) TestZebra() { ... }   // บรรทัดที่ 30
func (s *OrderSuite) TestApple() { ... }   // บรรทัดที่ 40

=== RUN   TestOrderSuite
=== RUN   TestOrderSuite/TestApple
=== RUN   TestOrderSuite/TestZebra
--- PASS: TestOrderSuite (0.00s)
    --- PASS: TestOrderSuite/TestApple (0.00s)
    --- PASS: TestOrderSuite/TestZebra (0.00s)

พอประกอบครบ นี่คือหน้าตาของการรัน integration suite เต็ม ๆ:

=== RUN   TestSearchByCity_CaughtByRealPostgres
    badsql_test.go:24: VERBATIM real-postgres error: ERROR: column "city" does not exist (SQLSTATE 42703)
--- PASS: TestSearchByCity_CaughtByRealPostgres (1.23s)
...
=== RUN   TestUserRepoSuite
    user_suite_test.go:33: SetupSuite: got DB in 3.292µs  dsn=postgres://testuser:testpass@localhost:32812/testdb?sslmode=disable
=== RUN   TestUserRepoSuite/TestCreateAndGet
=== RUN   TestUserRepoSuite/TestDelete
=== RUN   TestUserRepoSuite/TestDeleteMissingReturnsNotFound
=== RUN   TestUserRepoSuite/TestNilSliceVsEmptySlice
=== RUN   TestUserRepoSuite/TestUniqueIndexIsRealDDL
    user_suite_test.go:85: VERBATIM duplicate-key error: ERROR: duplicate key value violates unique constraint "idx_users_email" (SQLSTATE 23505)
=== RUN   TestUserRepoSuite/TestUpdate
--- PASS: TestUserRepoSuite (0.02s)
    (ตัดบรรทัด --- PASS: TestUserRepoSuite/<ชื่อ> ของ sub-test ทั้ง 6 ตัวออก)
PASS
[TestMain] shared container boot time = 1.203335125s
ok  	tcdemo/test/integration	1.757s

6 · t.Helper() — บรรทัดเดียวที่ทำให้ error ชี้ถูกที่

ฟังก์ชันอย่าง TruncateUsers(t, db) หรือ SharedDB(t) คือ "ฟังก์ชันช่วยเทส" ที่ถูกเรียกจากหลายที่ ถ้ามันฟ้อง error คุณอยากรู้ว่าเทสตัวไหนเรียก ไม่ใช่ว่ามันฟ้องที่บรรทัดไหนในตัวเอง

 7	func mustEqualWithHelper(t *testing.T, got, want string) {
 8		t.Helper()
 9		if got != want {
10			t.Errorf("got %q want %q", got, want)
11		}
12	}
13
14	func mustEqualNoHelper(t *testing.T, got, want string) {
15		if got != want {
16			t.Errorf("got %q want %q", got, want)
17		}
18	}
19
20	func TestWithHelper(t *testing.T) {
21		mustEqualWithHelper(t, "a", "b")
22	}
23
24	func TestWithoutHelper(t *testing.T) {
25		mustEqualNoHelper(t, "a", "b")
26	}

=== RUN   TestWithHelper
    helper_test.go:21: got "a" want "b"      ← จุดที่ "เรียก" ในเทส
--- FAIL: TestWithHelper (0.00s)
=== RUN   TestWithoutHelper
    helper_test.go:16: got "a" want "b"      ← t.Errorf ข้างในฟังก์ชันช่วย
--- FAIL: TestWithoutHelper (0.00s)
FAIL	tcdemo/test/helper	0.729s

7 · cleanup — Ryuk เก็บกวาดให้จริงไหม

คำถามที่ควรถามคือ "ถ้าผมลืม Terminate จะมี container ค้างกิน RAM กับ disk ไหม"
ผมทดลองแล้ว: ปล่อยให้เทสจบโดยไม่ Terminate แล้วนั่งจับเวลาดู docker ps ทุกไม่กี่วินาที

// ลืม Terminate โดย Ryuk เปิดอยู่ (ค่า default)
// running_pg = postgres ที่ยังรันอยู่ (docker ps) · all_pg = นับรวมตัวที่ตายแล้วแต่ยังไม่ถูกลบด้วย (docker ps -a) · running_ryuk = ตัว Ryuk เอง
test process exited at t=0
t+0s   running_pg=1 all_pg=1 running_ryuk=1
t+3s   running_pg=1 all_pg=1 running_ryuk=1
t+9s   running_pg=1 all_pg=1 running_ryuk=1
t+10s  running_pg=0 all_pg=0 running_ryuk=0
t+23s  running_pg=0 all_pg=0 running_ryuk=0

// TESTCONTAINERS_RYUK_DISABLED=true + ลืม Terminate
t+0s:  1 postgres running
t+10s: 1 postgres running
t+25s: 1 postgres running
=== final docker ps ===
e43f38657fa3	postgres:16-alpine	thirsty_curie	Up 28 seconds

Ryuk คือ container ตัวเล็ก ๆ ที่ testcontainers เปิดให้อัตโนมัติ หนึ่งตัวต่อหนึ่ง test process (ไม่ใช่ต่อหนึ่ง container) มันถือ TCP connection (สายที่ต่อค้างไว้ระหว่างสองโปรแกรม พอฝั่งหนึ่งตาย อีกฝั่งรู้ทันที) กับ test process ไว้ พอ process ตายก็เริ่มนับถอยหลัง ประมาณ 10 วินาที แล้วลบทุก container ที่มี label (ป้ายชื่อที่แปะไว้บน container) ของการรันครั้งนั้น รวมถึงลบตัวเองด้วย

8 · กับดักที่เหลือ

8.1 Run คืน error พร้อมกับ container ที่ไม่ใช่ nil

บทที่แล้วสอนรูปแบบ cleanup ที่ถูกไปแล้ว ตรงนี้คือหลักฐานว่าทำไมมันสำคัญ — เมื่อ wait strategy (กติกาที่บอกว่าจะถือว่า container พร้อมใช้เมื่อไหร่ เช่น รอจนเห็น log บรรทัดหนึ่ง) รอจนหมดเวลา Run คืนทั้ง error และ container ที่ start ไปแล้วจริง ๆ:

    waittimeout_test.go:28: VERBATIM wait-timeout error: run postgres: generic container: start container: started hook: wait until ready: "this log line will never appear" matched 0 times, expected 1
        context deadline exceeded
    waittimeout_test.go:29: returned container is nil? false
    waittimeout_test.go:31: container id = 6116d6c24184482b076d1c70a39046ad846920da81381698a84b52b9070ccca9
    waittimeout_test.go:37: TerminateContainer: <nil> (cleaned up)

ctr, err := tcpostgres.Run(ctx, ...)
if err != nil {
    t.Fatal(err)   // ออกก่อนถึง defer
}
defer ctr.Terminate(ctx)

ctr, err := tcpostgres.Run(ctx, ...)
defer func() {
    _ = testcontainers.TerminateContainer(ctr)
}()
if err != nil {
    t.Fatal(err)
}

8.2 terminate container ที่ยังไม่ ready = รอฟรี 10 วินาที

    nowait_test.go:53: VERBATIM early-connect error after 3.590916ms: ...
2026/08/18 20:00:27 🐳 Stopping container: 3270a343e678
2026/08/18 20:00:38 ✅ Container stopped: 3270a343e678
2026/08/18 20:00:38 🐳 Terminating container: 3270a343e678
2026/08/18 20:00:38 🚫 Container terminated: 3270a343e678
--- PASS: TestNoWaitStrategy (11.04s)

เทสล้มตั้งแต่มิลลิวินาทีที่ 3.6 แต่ใช้เวลารวม 11 วินาที — ดู timestamp: 20:00:27 สั่ง stop แต่ 20:00:38 ถึงหยุดได้
เพราะ postgres ที่กำลัง initdb อยู่ไม่ตอบ SIGTERM Docker จึงรอครบ stop timeout (10 วินาที) แล้วค่อย SIGKILL
นี่คือเหตุผลที่สองว่าทำไมต้องใส่ BasicWaitStrategies() — ไม่ใช่แค่กันเทส flaky (เดี๋ยวผ่านเดี๋ยวไม่ผ่านทั้งที่โค้ดไม่ได้เปลี่ยน) แต่กัน teardown ช้าด้วย

8.3 sync.Once กับ t.Parallel() — เตือนไว้ก่อน

ทดสอบความเข้าใจ

--- SKIP: TestSearchByCity_CaughtByRealPostgres (0.00s)
--- SKIP: TestTypoInColumn (0.00s)
--- SKIP: TestWrongTable (0.00s)
--- SKIP: TestNilSliceMatrix (0.00s)
--- SKIP: TestSharedA (0.00s)
--- SKIP: TestSharedB (0.00s)
--- SKIP: TestSharedC (0.00s)
--- SKIP: TestUserRepoSuite (0.00s)
PASS
[TestMain] shared container boot time = 0s
ok  	tcdemo/test/integration	0.353s

[eager TestMain] container booted BEFORE m.Run() in 1.047302208s
--- SKIP: TestEagerOne (0.00s)
ok  	tcdemo/test/eager	1.673s   ← จ่าย 1 วินาทีฟรี ๆ และยังต้องมี Docker

อ้างอิง

• pkg.go.dev — testing: Main — สัญญาของ TestMain และ m.Run()
• pkg.go.dev — testing.T.Helper · testing.Short
• pkg.go.dev — sync.Once — ต่อจาก บทเรียน 24
• testify/suite — รายการ hook ทั้งหมด รวม BeforeTest/AfterTest
• Testcontainers for Go — Garbage Collector (Ryuk)
• modules/postgres v0.44.0 — Run, ConnectionString, BasicWaitStrategies