• add the ability to manipulate observed time through the clock and timecop package
• add experimental spec helpers to the httpspec
• add support to simulate random io reads with random.Random
• add the ability to pretty print any object, diff them in GNU side-by-side Diff style
• support accessing a testcase.Var's Super value when you define it in a sub context
  • this allows you to wrap entities with Spies and Stubs to do various things, such as fault injection.
• testcase.LetValue accepts more value as long they are safe to use due to pass-by-value.
• support table tests with table test helper.

Happy testing!

upgrade testcase to the latest

• a new fault injection framework
  • allows injecting errors into a specific package/receiver/function's context.Err call
  • includes a fault injection middleware/round-tripper that allows propagating faults in distributed systems.
  • Added the ability to propagate injected faults in the round-tripper
  • allows the ability to inject errors through the HTTP API in a controlled manner
  • has a Global Enable Disable toggle to exclude all possibilities where faults injection is are not expected on an environment.
    • default is off

defer faultinject.Enable()()

ctx := context.Background()

// all fault field is optional.
// in case left as zero value,
// it will match every caller context,
// and returns on the first .Err() / .Value(faultinject.Fault{})
ctx = faultinject.Inject(ctx, faultinject.CallerFault{
	Package:  "targetpkg",
	Receiver: "*myreceiver",
	Function: "myfunction",
}, errors.New("boom"))

// from and after call stack reached: targetpkg.(*myreceiver).myfunction
if err := ctx.Err(); err != nil {
	fmt.Println(err) // in the position defined by the Fault, it will yield an error
}

• added support for a deterministic random generation as io.Reader with random.Random

rnd := random.New(rand.NewSource(time.Now().Unix()))

p := make([]byte, 42)
n, err := rnd.Read(p)

_, _ = n, err

• added support for deterministic random error generation

rnd := random.New(rand.NewSource(time.Now().Unix()))
err := rnd.Error()
_ = err

• nil is an acceptable constant value for the testcase.LetValue
• more examples in the pkg documentation
  • https://pkg.go.dev/github.com/adamluzsi/testcase#pkg-examples
  • https://pkg.go.dev/github.com/adamluzsi/testcase/random#pkg-examples
  • https://pkg.go.dev/github.com/adamluzsi/testcase/faultinject#pkg-examples
• changed signature to accept receiver in the Before hook of a testcase.Var,
  • This allows the use of a global testcase.Var with a dynamic Before hook arrangement without the need to use the init() function.

var v = testcase.Var[int]{
	ID:   "myvar",
	Init: func(t *testcase.T) int { return 42 },
	Before: func(t *testcase.T, v testcase.Var[int]) {
		t.Logf(`I'm from the Var.Before block, and the value: %#v`, v.Get(t))
	},
}

• [EXPERIMENT] deprecate Around, AroundAll, After, AfterAll to trim down on the testcase's API
  • They can be expressed using a Before/BeforeAll with T.Defer or T.Cleanup
• added support for sandboxing function blocks
  • This allows testing test helpers easily without letting your test exit with runtime.Goexit on testing.TB.FailNow

var tb testing.TB = &testcase.StubTB{}
outcome := testcase.Sandbox(func() {
	// some test helper function calls fatal, which cause runtime.Goexit after marking the test failed.
	tb.FailNow()
})

fmt.Println("The sandbox run has finished without an issue", outcome.OK)
fmt.Println("runtime.Goexit was called:", outcome.Goexit)
fmt.Println("panic value:", outcome.PanicValue)

• added support for assert.NoError

var tb testing.TB
assert.NoError(tb, nil)                // passes
assert.NoError(tb, errors.New("boom")) // fails

• improved the usability of StubTB to make it easier to assert the log content

stub := &testcase.StubTB{}
stub.Log("hello", "world")
fmt.Println(stub.Logs.String())

• added commonly used charsets to make random string generation more convenient for a given charset

rnd := random.New(rand.NewSource(time.Now().Unix()))
rnd.StringNWithCharset(42, random.Charset())
rnd.StringNWithCharset(42, random.CharsetASCII())
rnd.StringNWithCharset(42, random.CharsetAlpha())
rnd.StringNWithCharset(42, "ABC")

• added alias for random.StringWithCharset to make it easier to use

rnd := random.New(rand.NewSource(time.Now().Unix()))
rnd.StringNC(42, random.Charset())

• extend assert.ErrorIs to check equality even with wrapped values
• move Eventually async test helper into the assert package
  • backward compatibility is ensured for awhile
• add more safety guards to prevent variables without ID
• added http.Handler middleware contract to httpspec
  • if you write an http.Handler-based middleware ensures that the minimum expectations are there.

myHandlerWithFaultInjectionMiddleware := fihttp.Handler{
	Next:        myHandler,
	ServiceName: "our-service-name",
	FaultsMapping: fihttp.FaultsMapping{
		"mapped-fault-name": func(ctx context.Context) context.Context {
			return faultinject.Inject(ctx, FaultTag{}, errors.New("boom"))
		},
	},
}

• many small improvements

Add package level assertion functions to testcase/assert package This will make the assert package align with other popular assertion packages in terms of conventions.

Examples:

• assert.Contain
• assert.ContainExactly
• assert.Empty
• assert.Equal
• assert.ErrorIs
• assert.False
• assert.True
• assert.Nil
• assert.NotContain
• assert.NotEmpty
• assert.NotEqual
• assert.NotNil
• assert.NotPanic
• assert.NotPanic
• assert.Panic

Add testcase.T.SkipUntil that is equivalent to Log followed by SkipNow if the test is executing prior to the given deadline time. SkipUntil is useful when you need to skip something temporarily, but you don't trust your memory enough to return to it on your own.

assert.Asserter.Equal and other assertions that test equality will respect the .IsEqual method on the value. When it does a comparison and .IsEqual is defined, it will use that instead of deep equality checking.

If a value has unexported values or a stateful field that requires a delicate way to compare, through this method, it becomes possible.

example code for .IsEqual

httpspec is extended with a RoundTripperMiddleware contract.

You can verify common scenarios with your round-tripper middleware using the shared spec. This shared contract should allow you to focus on the round-trippers business logic rather than the generic middleware behaviour.

Support for testing library creators

The new StubTB allows testing test-helpers functions with a StubTB that behaves like the testing.TB.

Expose http.Request and ResponseRecorder in httpspec

This should allow reusing them as commonly used testcase.Var(s) in specs focusing on HTTP coverage.

• *testcase.T.Random.String from now on will return generic SQL and NoSQL injection strings as well.
• signature change for fixtures.New to use Go's generics syntax.

The Big List of Naughty Strings is incorporated into the testcase's random generator. Unit tests that use these randomly generated string values will double as an enhanced fuzzing test.

To run your unit tests with various naughty strings, use the -count testing flag. Each test execution by -count will run with a different naughty string.

go test -count 1024 -run TestMyUnit

Exclude the time it takes to construct a dependency from the benchmark time.

func Benchmark_myBench(b *testing.B) {
	s := testcase.NewSpec(b)

	v := testcase.Let(s, func(t *testcase.T) int {
		// benchmark time is not tracked here
		time.Sleep(time.Second / 2) 
		return t.Random.Int()
	})

	s.Test(``, func(t *testcase.T) {
		// benchmark time is tracked here 
		time.Sleep(time.Second) 
		_ = v.Get(t)
	})
}

Both testcase#Retry.Assert and testcase#T.Eventually use the same signature for convenience.

waiter := testcase.Waiter{
	WaitDuration: time.Millisecond,
	WaitTimeout:  time.Second,
}
r := testcase.Retry{Strategy: waiter}
r.Assert(t, func(it assert.It) { // <- assert.It is passed here instead of testing.TB
	if rand.Intn(1) == 0 {
		it.Fatal(`boom`)
	}
})

Assertions now support ErrorIs assertion where you can check both if the error is equal to an expected one, or part of the actual error's error chain. This leaves room for later refactoring like wrapping the error value to give better context to the returned error, without breaking a test.

actualErr := errors.New("boom")
assert.Must(tb).ErrorIs(errors.New("boom"), actualErr)                                  // passes for equality
assert.Must(tb).ErrorIs(errors.New("boom"), fmt.Errorf("wrapped error: %w", actualErr)) // passes for wrapped errors

testcase's API is updated to remove the need for boilerplate when working with test bounded variables.

previous version had to rely on empty interface casting:

s := testcase.NewSpec(t)
input := testcase.Var{ID: "input"}
subject := func(t *testcase.T) string {
	return MyFunc(input.Get(t).(string))
}

The latest release uses type safety through generics:

s := testcase.NewSpec(t)
input := testcase.Var[string]{ID: "input"}
subject := func(t *testcase.T) string {
	return MyFunc(input.Get(t))
}

Happy Coding/Specifying! :)

testcase.Race

Race is a test helper that allows you to create a race situation easily. This is useful when you work on a component that requires thread-safety. By using the Race helper, you can write an example use of your component, and run the testing suite with go test -race. The race detector then should be able to notice issues with your implementation.

testcase.T.Random

T.Random is a random generator that uses the Spec seed. When a test fails with random input from Random generator, the failed test scenario can be recreated simply by providing the same TESTCASE_SEED as you can read from the console output of the failed test.

testcase.Var Thread Safety

testcase.Var.Get and testcase.Var.Set now thread-safe.

testcase.Contract & testcase.RunContract

Contract meant to represent a Role Interface Contract. A role interface is a static code contract that expresses behavioral expectations as a set of method signatures. A role interface used by one or many consumers. These consumers often use implicit assumptions about how methods of the role interface behave. Using these assumptions makes it possible to simplify the consumer code. In testcase convention, instead of relying on implicit assumptions, the developer should create an explicit interface testing suite, in other words, a Contract. The code that supplies a role interface then able to import a role interface Contract, and confirm if the expected behavior is fulfilled by the implementation.

further references:

• testcase/docs/contracts.md
• More Effective DDD with Interface Test Suites
• J B Rainsberger Integrated Tests Are A Scam HD