impr: return pass/fail flag

Author: nalgeon

README.md

@@ -4,10 +4,10 @@ If you want simple test assertions and feel like [testify](https://pkg.go.dev/gi
 
 Highlights:
 
--   Minimal API: `Equal`, `Err`, and `True` assertions.
--   Correctly compares `time.Time` values and other types with an `Equal` method.
--   Flexible error assertions: check if an error exists, check its value, type, or any combination of these.
--   Zero hassle.
+- Minimal API: `Equal`, `Err`, and `True` assertions.
+- Correctly compares `time.Time` values and other types with an `Equal` method.
+- Flexible error assertions: check if an error exists, check its value, type, or any combination of these.
+- Zero hassle.
 
 Be is new, but it's ready for production (or maybe I should say "testing" :) I've used it in three very different projects — a CLI tool, an API server, and a database engine — and it worked great every time.
 
@@ -19,6 +19,8 @@ Install with go get:
 go get github.com/nalgeon/be
 ```
 
+### Equality
+
 `Equal` asserts that two values are equal:
 
 ```go
@@ -47,6 +49,8 @@ func Test(t *testing.T) {
 }
 ```
 
+### Errors
+
 `Err` asserts that there is an error:
 
 ```go
@@ -119,6 +123,8 @@ func Test(t *testing.T) {
 }
 ```
 
+### True/false
+
 `True` asserts that an expression is true:
 
 ```go
@@ -129,6 +135,21 @@ func Test(t *testing.T) {
 }
 ```
 
+### Conditional checks (work in progress)
+
+Each `be` function also returns a `bool` that shows whether the assertion passed or failed. You can use this to stop early or run extra checks:
+
+```go
+func Test(t *testing.T) {
+    s := "go is awesome"
+    if be.True(t, len(s) > 0) {
+        be.Equal(t, s[0:2], "go")
+        be.Equal(t, s[len(s)-2:], "me")
+    }
+    // ok
+}
+```
+
 That's it!
 
 ## Design decisions

be.go

@@ -29,29 +29,32 @@ type equaler[T any] interface {
 }
 
 // Equal asserts that got is equal to any of the wanted values.
-func Equal[T any](tb testing.TB, got T, wants ...T) {
+// Returns true if there is a match, false otherwise.
+func Equal[T any](tb testing.TB, got T, wants ...T) bool {
 	tb.Helper()
 
 	if len(wants) == 0 {
 		tb.Fatal("no wants given")
-		return
+		return false
 	}
 
 	// Check if got matches any of the wants.
 	for _, want := range wants {
 		if areEqual(got, want) {
-			return
+			return true
 		}
 	}
 
 	// There are no matches, report the failure.
 	if len(wants) == 1 {
 		// There is only one want, report it directly.
 		tb.Errorf("got: %#v; want: %#v", got, wants[0])
-		return
+		return false
 	}
+
 	// There are multiple wants, report a summary.
 	tb.Errorf("got: %#v; want any of: %v", got, wants)
+	return false
 }
 
 // Err asserts that the got error matches any of the wanted values.
@@ -65,23 +68,24 @@ func Equal[T any](tb testing.TB, got T, wants ...T) {
 //   - Otherwise fails the check.
 //
 // If no wants are given, checks if got is not nil.
-func Err(tb testing.TB, got error, wants ...any) {
+// Returns true if there is a match, false otherwise.
+func Err(tb testing.TB, got error, wants ...any) bool {
 	tb.Helper()
 
 	// If no wants are given, we expect got to be a non-nil error.
 	if len(wants) == 0 {
 		if got == nil {
 			tb.Error("got: <nil>; want: error")
 		}
-		return
+		return got != nil
 	}
 
 	// Special case: there's only one want, it's nil, but got is not nil.
 	// This is a fatal error, so we fail the test immediately.
 	if len(wants) == 1 && wants[0] == nil {
 		if got != nil {
 			tb.Fatalf("unexpected error: %v", got)
-			return
+			return false
 		}
 	}
 
@@ -90,7 +94,7 @@ func Err(tb testing.TB, got error, wants ...any) {
 	for _, want := range wants {
 		errMsg := checkErr(got, want)
 		if errMsg == "" {
-			return
+			return true
 		}
 		if message == "" {
 			message = errMsg
@@ -101,18 +105,22 @@ func Err(tb testing.TB, got error, wants ...any) {
 	if len(wants) == 1 {
 		// There is only one want, report it directly.
 		tb.Error(message)
-		return
+		return false
 	}
+
 	// There are multiple wants, report a summary.
 	tb.Errorf("got: %T(%v); want any of: %v", got, got, wants)
+	return false
 }
 
 // True asserts that got is true.
-func True(tb testing.TB, got bool) {
+// Returns true if got is true, false otherwise.
+func True(tb testing.TB, got bool) bool {
 	tb.Helper()
 	if !got {
 		tb.Error("got: false; want: true")
 	}
+	return got
 }
 
 // areEqual checks if a and b are equal.