feat: add CheckedClose test helper (#27217)

gwossum · web-flow · commit 0f3436d10dff · 2026-02-12T18:00:56.000-06:00
* feat: add CheckedClose test helper Add CheckedClose test helper to improve readability of the following pattern in tests. ``` defer func() { require.NoError(t, c.Close()) }() ``` This can now be replaced with `defer CheckedClose(t, c)()`. * feat: add CheckedCloseOnce Add CheckedCloseOnce test helper function to create close functions that check for errors and only call the underlying Close method once. Clean chery-pick from master-1.x. (cherry picked from commit 093bd3f)
diff --git a/pkg/testing/helper/helpers.go b/pkg/testing/helper/helpers.go
@@ -0,0 +1,54 @@
+package helper
+
+import (
+	"io"
+	"sync"
+
+	"github.com/stretchr/testify/require"
+)
+
+// CheckedClose returns a function that can be used with a defer to check that a
+// Closer's Close method does not return an error.
+//
+// By using CheckedClose, the following code:
+// defer func() { require.NoError(t, c.Close()) }()
+// can be replaced by:
+// defer CheckedClose(t, c)()
+func CheckedClose(t require.TestingT, c io.Closer) func() {
+	return func() {
+		if h, ok := t.(interface{ Helper() }); ok {
+			h.Helper()
+		}
+
+		require.NoError(t, c.Close())
+	}
+}
+
+// CheckedCloseOnce returns a function that will call Close on c and check
+// for errors. The returned function has no effect after being called the first
+// time. It can be used to replace code like the following:
+//
+//	c := NewSomeCloser()
+//	defer func() {
+//		if c != nil {
+//			require.NoError(c.Close())
+//			c = nil
+//		}
+//	}()
+//	...
+//	require.NoError(t, c.Close())
+//	c = nil
+//
+// Example:
+//
+//	closer := CheckedCloseOnce(t, c)
+//	defer closer()
+//	...
+//	closer()
+func CheckedCloseOnce(t require.TestingT, c io.Closer) func() {
+	innerCloser := CheckedClose(t, c)
+	var o sync.Once
+	return func() {
+		o.Do(innerCloser)
+	}
+}
diff --git a/pkg/testing/helper/helpers_test.go b/pkg/testing/helper/helpers_test.go
@@ -0,0 +1,155 @@
+package helper
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// mockCloser is an io.Closer that returns a configurable error.
+type mockCloser struct {
+	err        error
+	closed     bool
+	closeCount int
+}
+
+func (m *mockCloser) Close() error {
+	m.closed = true
+	m.closeCount++
+	return m.err
+}
+
+// mockTestingT implements require.TestingT for testing CheckedClose behavior.
+type mockTestingT struct {
+	failed     bool
+	helperUsed bool
+}
+
+func (m *mockTestingT) Errorf(format string, args ...any) {
+	m.failed = true
+}
+
+func (m *mockTestingT) FailNow() {
+	m.failed = true
+}
+
+func (m *mockTestingT) Helper() {
+	m.helperUsed = true
+}
+
+func TestCheckedClose(t *testing.T) {
+	t.Run("returns a function", func(t *testing.T) {
+		closer := &mockCloser{}
+		fn := CheckedClose(t, closer)
+		require.NotNil(t, fn)
+	})
+
+	t.Run("calls Close on the closer", func(t *testing.T) {
+		closer := &mockCloser{}
+		fn := CheckedClose(t, closer)
+		fn()
+		require.True(t, closer.closed)
+	})
+
+	t.Run("does not fail when Close returns nil", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{err: nil}
+		fn := CheckedClose(mockT, closer)
+		fn()
+		require.False(t, mockT.failed)
+	})
+
+	t.Run("fails when Close returns an error", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{err: errors.New("close error")}
+		fn := CheckedClose(mockT, closer)
+		fn()
+		require.True(t, mockT.failed)
+	})
+
+	t.Run("calls Helper when available", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{}
+		fn := CheckedClose(mockT, closer)
+		fn()
+		require.True(t, mockT.helperUsed)
+	})
+
+	t.Run("works with defer", func(t *testing.T) {
+		closer := &mockCloser{}
+		func() {
+			defer CheckedClose(t, closer)()
+			require.False(t, closer.closed, "should not be closed yet")
+		}()
+		require.True(t, closer.closed, "should be closed after function returns")
+	})
+}
+
+func TestCheckedCloseOnce(t *testing.T) {
+	t.Run("returns a function", func(t *testing.T) {
+		closer := &mockCloser{}
+		fn := CheckedCloseOnce(t, closer)
+		require.NotNil(t, fn)
+	})
+
+	t.Run("calls Close on the closer", func(t *testing.T) {
+		closer := &mockCloser{}
+		fn := CheckedCloseOnce(t, closer)
+		fn()
+		require.True(t, closer.closed)
+	})
+
+	t.Run("does not fail when Close returns nil", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{err: nil}
+		fn := CheckedCloseOnce(mockT, closer)
+		fn()
+		require.False(t, mockT.failed)
+	})
+
+	t.Run("fails when Close returns an error", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{err: errors.New("close error")}
+		fn := CheckedCloseOnce(mockT, closer)
+		fn()
+		require.True(t, mockT.failed)
+	})
+
+	t.Run("calls Helper when available", func(t *testing.T) {
+		mockT := &mockTestingT{}
+		closer := &mockCloser{}
+		fn := CheckedCloseOnce(mockT, closer)
+		fn()
+		require.True(t, mockT.helperUsed)
+	})
+
+	t.Run("works with defer", func(t *testing.T) {
+		closer := &mockCloser{}
+		func() {
+			defer CheckedCloseOnce(t, closer)()
+			require.False(t, closer.closed, "should not be closed yet")
+		}()
+		require.True(t, closer.closed, "should be closed after function returns")
+	})
+
+	t.Run("only closes once when called multiple times", func(t *testing.T) {
+		closer := &mockCloser{}
+		fn := CheckedCloseOnce(t, closer)
+		fn()
+		fn()
+		fn()
+		require.Equal(t, 1, closer.closeCount)
+	})
+
+	t.Run("works with defer and explicit call", func(t *testing.T) {
+		closer := &mockCloser{}
+		func() {
+			closeFn := CheckedCloseOnce(t, closer)
+			defer closeFn()
+			closeFn() // explicit early close
+			require.Equal(t, 1, closer.closeCount, "should be closed exactly once")
+		}()
+		require.Equal(t, 1, closer.closeCount, "should still be closed exactly once after defer")
+	})
+}
