feat: add recover pattern (#130)

Signed-off-by: Tronje Krop <[email protected]>

Author: tkrop

.github/workflows/build.yaml

@@ -25,24 +25,24 @@ jobs:
         path-to-profile: ./build/test-all.cover
 
 
-  macos:
-    runs-on: macos-latest
-    steps:
-    - name: Set up Go
-      uses: actions/setup-go@v5
-      with:
-        go-version: 1.25
-        cache: false
+  # macos:
+  #   runs-on: macos-latest
+  #   steps:
+  #   - name: Set up Go
+  #     uses: actions/setup-go@v5
+  #     with:
+  #       go-version: 1.25
+  #       cache: false
 
-    - name: Checkout code
-      uses: actions/checkout@v4
+  #   - name: Checkout code
+  #     uses: actions/checkout@v4
 
-    - name: Build and tests
-      env:
-        BASH_COMPAT: 3.2
-        CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
-        LANG: en_US.UTF-8
-      run: make all
+  #   - name: Build and tests
+  #     env:
+  #       BASH_COMPAT: 3.2
+  #       CODACY_PROJECT_TOKEN: ${{ secrets.CODACY_PROJECT_TOKEN }}
+  #       LANG: en_US.UTF-8
+  #     run: make all
 
 
   release:

VERSION

@@ -1 +1 @@
-0.0.43
+0.0.44

go.mod

@@ -15,8 +15,8 @@ require (
 
 require (
 	github.com/h2non/parth v0.0.0-20190131123155-b4df798d6542 // indirect
-	golang.org/x/mod v0.29.0 // indirect
-	golang.org/x/sync v0.17.0 // indirect
+	golang.org/x/mod v0.30.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -28,10 +28,10 @@ github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
 go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
-golang.org/x/mod v0.29.0 h1:HV8lRxZC4l2cr3Zq1LvtOsi/ThTgWnUk/y64QSs8GwA=
-golang.org/x/mod v0.29.0/go.mod h1:NyhrlYXJ2H4eJiRy/WDBO6HMqZQ6q9nk4JzS3NuCK+w=
-golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
-golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/mod v0.30.0 h1:fDEXFVZ/fmCKProc/yAXXUijritrDzahmwwefnjoPFk=
+golang.org/x/mod v0.30.0/go.mod h1:lAsf5O2EvJeSFMiBxXDki7sCgAxEUcZHXoXMKT4GJKc=
+golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
 golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
 golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM=
 golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=

gock/controller_test.go

@@ -75,11 +75,7 @@ func TestController(t *testing.T) {
 
 func TestPanic(t *testing.T) {
 	// Given
-	defer func() {
-		if err := recover(); err == nil {
-			assert.Fail(t, "did not panic")
-		}
-	}()
+	defer test.Recover(t, "gock not supported by test setup")
 
 	// When
 	gock.NewGock(gomock.NewController(struct{ gomock.TestReporter }{}))

internal/sync/waitgroup_test.go

@@ -7,13 +7,14 @@ import (
 	"github.com/stretchr/testify/assert"
 
 	"github.com/tkrop/go-testing/internal/sync"
+	"github.com/tkrop/go-testing/test"
 )
 
 func TestWaitGroup(t *testing.T) {
 	t.Parallel()
 
 	// Given
-	defer func() { _ = recover() }()
+	defer test.Recover(t, "sync: negative WaitGroup counter")
 	wg := sync.NewWaitGroup()
 
 	// When
@@ -23,7 +24,7 @@ func TestWaitGroup(t *testing.T) {
 	wg.Done()
 
 	// Then
-	assert.Fail(t, "not recovered from panic")
+	assert.Fail(t, "did not panic")
 }
 
 func TestLenientWaitGroup(t *testing.T) {

mock/mocks_test.go

@@ -557,10 +557,7 @@ var panicTestCases = map[string]PanicParams{
 func TestPanic(t *testing.T) {
 	test.Map(t, panicTestCases).Run(func(t test.Test, param PanicParams) {
 		// Given
-		defer func() {
-			err := recover()
-			assert.Equal(t, param.expectError, err)
-		}()
+		defer test.Recover(t, param.expectError)
 
 		// When
 		MockSetup(t, param.setup)

test/README.md

@@ -188,44 +188,22 @@ source of the panic, you need to spawn a new unrecovered go-routine.
 hard to recreate. Do not try it.
 
 
-## Test result builder
-
-Setting up tests and comparing test results is most efficient, when you
-directly can set up and compare the actual objects. However, this is sometimes
-prevented by the objects not being open for construction and having private
-states.
-
-To cope with this challenge the `test`-package supports helpers to access, i.e.
-read and write, private fields of objects using reflection.
-
-* `test.NewBuilder[...]()` allows constructing a new object from scratch.
-* `test.NewGetter(...)` allows reading private fields of an object by name.
-* `test.NewSetter(...)` allows writing private fields by name, and finally
-* `test.NewAccessor(...)` allows reading and writing of private fields by name.
-
-The following example shows a real world example of how the private properties
-of a closed error can be set up using the `test.NewBuilder[...]()`.
-
-```go
-    err := test.NewBuilder[viper.ConfigFileNotFoundError]().
-        Set("locations", fmt.Sprintf("%s", "...path...")).
-        Set("name", "test").Build()
-```
+## Out-of-the-box test patterns
 
-Similar we can set up input objects with private properties to minimize the
-dependencies in the test setup, however, using this features exposes the test
-to internal changes.
+Currently, the package supports two _out-of-the-box_ test patterns:
 
+1. `test.Main(func())` - allows to test main methods by calling the main
+   method with arguments in a well controlled test environment.
+2. `test.Recover(Test,any)` - allows to check the panic result in simple test
+   scenarios where `test.Panic(any)` is not applicable.
 
-## Out-of-the-box test patterns
 
-Currently, the package supports only one _out-of-the-box_ test pattern to test
-the `main`-methods of commands.
+### Main method tests pattern
 
-The pattern executes the `main` method in a separate process to protect the
-test execution against `os.Exit` calls while allowing to capture and check the
-exit code against the expectation. The following example demonstrates how to
-use the pattern to test a `main` method:
+The `test.Main(func())` pattern executes the `main` method in a separate test
+process to protect the test execution against `os.Exit` calls while allowing to
+capture and check the exit code against the expectation. The following example
+demonstrates how to use the pattern to test a `main` method:
 
 ```go
 mainTestCases := map[string]test.MainParams{
@@ -253,4 +231,30 @@ e.g. as follows:
 however, it is focused on testing the `main` methods with and without parsing
 command line arguments.
 
+**Note:** In certain situations, `test.Main(func())` currently fails to obtain
+the coverage metrics for the test execution, since `go test` is using the
+standard output to collect results. We are investigating how we can separate
+these in the test execution from expected test output.
+
+
+## Convenience functions
+
+The test package contains a number of convenience functions to simplify the
+test setup and apply certain test patterns. Currently, the following functions
+currently supported:
+
+* `test.Must[T](T, error) T` - a convenience method for fluent test case setup
+  that converts an error into a panic.
+* `test.Cast[T](T) T` - a convenience method for fluent test case setup that
+  converts an casting error into a panic compliant with linting requirements.
+* `test.Ptr[T](T) *T` - a convenience method for fluent test case setup that
+  converts a literal value into a pointer.
+* `test.First[T](T, ...any)` - a convenience method for fluent test case setup
+  that extracts the first value of a response ignoring the others.
+
+Please also have a look at the convenience functions provided by the
+[reflect](../reflect) package, that allows you to fluently access non-exported
+fields for setting up and checking.
+
+
 [gomock]: <https://go.uber.org/mock>

test/caller_test.go

@@ -128,12 +128,12 @@ var (
 	CallerTestError = path.Join(SourceDir, "context.go:352")
 	// CallerReporterErrorf provides the file with the line number of the
 	// `Errorf` call in the test reporter/validator implementation.
-	CallerReporterError = path.Join(SourceDir, "reporter.go:83")
+	CallerReporterError = path.Join(SourceDir, "reporter.go:87")
 
 	// CallerTestErrorf provides the file with the line number of the `Errorf`
 	// call in the test context implementation.
 	CallerTestErrorf = path.Join(SourceDir, "context.go:370")
 	// CallerReporterErrorf provides the file with the line number of the
 	// `Errorf` call in the test reporter/validator implementation.
-	CallerReporterErrorf = path.Join(SourceDir, "reporter.go:105")
+	CallerReporterErrorf = path.Join(SourceDir, "reporter.go:109")
 )

test/pattern.go

@@ -46,6 +46,19 @@ func Ptr[T any](v T) *T {
 // others arguments. The method allows to write concise test setup code.
 func First[T any](arg T, _ ...any) T { return arg }
 
+// Recover is a convenience method to be used in deferred calls to verify that
+// a panic occurred with the expected panic response. The function creates a
+// test failure if no panic occurred or the panic response does not match the
+// expected value.
+func Recover(t Test, expect any) {
+	// revive:disable-next-line:defer // caller is expected to use defer.
+	if actual := recover(); actual != nil {
+		assert.Equal(t, expect, actual)
+	} else {
+		assert.Fail(t, "did not panic: %#v", expect)
+	}
+}
+
 // TODO: consider following convenience methods:
 //
 // // Check is a convenience method that returns the second argument and swallows