Add Must & Mustf

[FGasper]

Summary

Convenience methods around operations that must succeed.

Changes

• Add require.Must and require.Mustf generic functions.
• Add corresponding require.Assertions methods.

These are usable only in Go 1.21+ and 1.27+, respectively. (The function versions would work in 1.18-1.20, but release-tag limitations in those versions prevent that.)

Motivation

These are convenience methods. Usage looks thus:

func stringOrErr() (string, error) { … }

myStr := require.Must(t, stringOrErr())
assert.Equal(t, "expected", myStr)

It’s a bit more ergonomic than:

myStr, err := stringOrErr()
require.NoError(t, err)

assert.Equal(t, "expected", myStr)

Thank you!

[brackendawson]

Lots of new concepts to testify here.

• Generics
• Assertions gated by go version build constraints
• Assertions which are only in the require package
• It's also debatable that this isn't an assertion, it's a helper function you can use in test setup.

The precedent has been clear in the past that testify does not try to be a utility package. Is it worth breaking all this new ground for what amounts to a 1-line saving.

Also is "must" the best name? By convention it raises errors to a panic, not a test failure.

It's not a no, but these are some points around which I would need some convincing to include the change.

[brackendawson]

Probably better to gate this on 1.27 too, like in require.Assertions.Must

[FGasper]

Why so, when 1.21 can run the static functions?

[brackendawson]

I think it might be confusing to someone using 1.21-1.26 to find that it's available under require but not available under require.Assertions.

I could probably be sold on not changing this part.

[FGasper]

Maybe add it here just for 1.27, and seeing if there’s a demand for static-only usage in prior.

[brackendawson]

Don't mix any and interface{} in the same function declaration.

[FGasper]

Whoops! Missed this, sorry.

[FGasper]

Thank you for your notes.

To your concerns:

• Generics: I think these are, after several years now, a sufficiently-established pattern in Go.
• Build-constraint gating: Is the concern here one of maintenance? There’s no danger that I see to existing codebases. Anyhow, this, too, seems well-established enough to justify itself.
• Require-only assertions. This one I get … would an assert equivalent just return a zero value, maybe? I can’t really see the utility of assert.Must, or I’d have included it.
• Helper function: It’s basically a helper-wrap around NoError() … ample precedent for which seems to exist.

I would argue that testify already is a utility package, insofar as it wraps testing.T’s primitives with convenience logic like NoError().

In my own experience this 1-line savings repeats over & over, impeding legibility & making tests clunkier.

To your points, though: this sort of thing may be more germane to OpenAPI’s fork.

[brackendawson]

I think we can probably include this.

Should we make an assert version too? I'd say no. This is permissible:

func TestIfy(t *testing.T) {
	b := bytes.Buffer{}
	count, err := b.Write(nil)
	assert.NoError(t, err)
	assert.Equal(t, count, 0)
}

But the return parameter is already occupied and almost always ignored so we just can't do it sensibly.

I actually never use the assert package myself, only require. I'm also quite supportive of the OpenAPI fork, it's close to the v2 I've always wanted to write. Any major version bump of a Go module is a fork, even if it's made in the same repo, and Stretchr is not the place to go starting a new fork.

[fredbi]

@FGasper hey. Sorry I missed this PR. Indeed a good demo of how generics may help write more concise tests. Will definitely add this to go-openapi/testify/v2 fork (next release if scheduled for ~ end september). Thanks for this great idea.

fred

[fredbi]

@FGasper I've experimented with a few implementations on my fork since your proposals.
And all were so far a bit disappointing.

We all agree that this feature is all about providing a syntactic sugar to replace

value, err := fn(args...)
require.NoError(t, err)
...

by something more concise and that better conveys the intent to use the value.

Your proposal comes a bit short of that as soon as the function takes some parameters:
Yields:

value := require.Must(t, func() (string, error) { return fn(args...) })
...

Not much of an improvement, uh?

I have tried yet another way:

func Must[V any](t TestingT, msgAndArgs ...any) func() (V, error) {
  ....
}

And usage looks like:

value := require.Must[int](t)(strconv.Atoi("1"))
...

or as a "forward" method:

myTest := require.New(t)
value := myTest.Must[int]()(strconv.Atoi("1"))
...

which arguably look better (I can inline the function arguments), but requires an explicit type hint.
go is unable to infer the type parameter directly from the the function. This doesn't build as of go1.27:

value := require.Must(t)(strconv.Atoi("1"))
...

A bit disappointing. This kind of mitigated my initial enthusiasm to add this (at least to the fork I am maintaining, which has full support for generics and generic methods).

Further, this helper is decidedly suited for require and doesn't make much sense with assert (or would it be called Should ?). This kind of break the symmetry of these packages: either the "assert" version becomes blocking (or "Must" doesn't make much of sense) or it is not generated there, or it is renamed as Should... In either case, this would need a lot of additional explanations, for overall a saving of perhaps 10-15 characters.

Maybe I missed something - I'd be happy to try alternate ways, but for now I am a bit short of brighter ideas that could make the helper, actually useful. Any thoughts?

[FGasper]

@fredbi et al.: I remember why I never submitted this idea before.

The idea is to mimic samber/lo.Must:

jsonBytes := req.Must(json.Marshal(whatsit))

That works only as a generic method because it doesn’t require *testing.T as an argument. As a static function it doesn’t work because Go won’t parse static require.Must(t, json.Marshal(whatsit)) with args (*testing.T, T, error).

So in 1.27 this is useful where require.Assertions is used. I personally, though, don’t frequently use require.Assertions.

I’ll leave this open in case others have ideas, but I’m OK to close this. Sorry, I should have fleshed this out better before opening the PR.