feat: support naming assertions to help describe their purpose (#19)

This change adds a new "Ensure(string)" function to the "Verifier"
interface. This method will apply a description to the current verifier
which will be prepended to potential failures, should those happen.

Usage:

    With(t).Ensure("my feature should yield a popup").Verify(...)...

Author: arikkfir

asserter.go

@@ -2,33 +2,48 @@ package justest
 
 import (
 	"fmt"
-	"github.com/arikkfir/justest/internal"
 	"path/filepath"
 	"regexp"
+	"strings"
 	"time"
+
+	"github.com/arikkfir/justest/internal"
 )
 
 //go:noinline
-func With(t T) Verifier {
+func With(t T) VerifierAndEnsurer {
 	if t == nil {
 		panic("given T instance must not be nil")
 	}
 	GetHelper(t).Helper()
 	return &verifier{t: t}
 }
 
+type VerifierAndEnsurer interface {
+	Verifier
+	Ensure(string) Verifier
+}
+
 type Verifier interface {
 	Verify(actuals ...any) Asserter
 }
 
 type verifier struct {
-	t T
+	t    T
+	desc string
+}
+
+//go:noinline
+func (v *verifier) Ensure(description string) Verifier {
+	GetHelper(v.t).Helper()
+	v.desc = description
+	return v
 }
 
 //go:noinline
 func (v *verifier) Verify(actuals ...any) Asserter {
 	GetHelper(v.t).Helper()
-	return &asserter{t: v.t, actuals: actuals}
+	return &asserter{t: v.t, desc: v.desc, actuals: actuals}
 }
 
 type Asserter interface {
@@ -38,6 +53,7 @@ type Asserter interface {
 type asserter struct {
 	t       T
 	actuals []any
+	desc    string
 }
 
 //go:noinline
@@ -46,6 +62,7 @@ func (a *asserter) Will(m Matcher) Assertion {
 
 	aa := &assertion{
 		t:        a.t,
+		desc:     a.desc,
 		location: nearestLocation(),
 		actuals:  a.actuals,
 		matcher:  m,
@@ -75,6 +92,7 @@ type assertion struct {
 	contain   bool
 	cleanup   []func()
 	evaluated bool
+	desc      string
 }
 
 //go:noinline
@@ -284,6 +302,11 @@ func (a *assertion) Failed() bool {
 func (a *assertion) Fatalf(format string, args ...any) {
 	GetHelper(a).Helper()
 
+	if a.desc != "" {
+		f := strings.ToLower(string(format[0])) + format[1:]
+		format = a.desc + " failed: " + f
+	}
+
 	if a.contain {
 		panic(internal.FormatAndArgs{Format: &format, Args: args})
 	} else {

asserter_test.go

@@ -22,6 +22,12 @@ func TestWith(t *testing.T) {
 		}()
 		With(nil)
 	})
+	t.Run("description propagated to failure message", func(t *testing.T) {
+		t.Parallel()
+		mt := NewMockT(t)
+		defer mt.Verify(FailureVerifier("^user feature failed: unexpected.*"))
+		With(mt).Ensure("user feature").Verify(1).Will(EqualTo(2)).OrFail()
+	})
 }
 
 func TestCorrectActualsPassedToMatcher(t *testing.T) {