test: add ErrorAs helper and fix up examples

README.md

@@ -18,6 +18,11 @@ There are five key packages,
 - `portal` - utilities for allocating free ports for network listeners in tests
 
 ### Changes
+:ballot_box_with_check: v1.11.0 adds an ErrorAs helper
+
+ - FS examples are more reliable
+ - Examples run on non-Unix OS when possible
+
 :ballot_box_with_check: v1.10.0 adds a `util` package for helpers that return values
 
  - Adds ability to create and automatically clean up temporary files

examples_test.go

@@ -1,19 +1,17 @@
 // Copyright (c) The Test Authors
 // SPDX-License-Identifier: MPL-2.0
 
-//go:build unix
-
 package test
 
 import (
 	"errors"
 	"fmt"
 	"io/fs"
 	"math"
-	"os"
 	"regexp"
 	"strconv"
 	"strings"
+	"testing/fstest"
 	"time"
 
 	"github.com/shoenig/test/wait"
@@ -225,23 +223,17 @@ func ExampleDescendingLess() {
 	// Output:
 }
 
-func ExampleDirExists() {
-	DirExists(t, "/tmp")
-	// Output:
-}
-
 func ExampleDirExistsFS() {
-	DirExistsFS(t, os.DirFS("/"), "tmp")
-	// Output:
-}
-
-func ExampleDirNotExists() {
-	DirNotExists(t, "/does/not/exist")
+	fsys := fstest.MapFS{
+		"foo": &fstest.MapFile{Mode: fs.ModeDir},
+	}
+	DirExistsFS(t, fsys, "foo")
 	// Output:
 }
 
 func ExampleDirNotExistsFS() {
-	DirNotExistsFS(t, os.DirFS("/"), "does/not/exist")
+	fsys := fstest.MapFS{}
+	DirNotExistsFS(t, fsys, "does/not/exist")
 	// Output:
 }
 
@@ -311,61 +303,56 @@ func ExampleErrorContains() {
 
 func ExampleErrorIs() {
 	e1 := errors.New("e1")
-	e2 := errors.New("e2")
-	e3 := errors.New("e3")
-	errorChain := errors.Join(e1, e2, e3)
-	ErrorIs(t, errorChain, e2)
+	e2 := fmt.Errorf("e2: %w", e1)
+	e3 := fmt.Errorf("e3: %w", e2)
+	ErrorIs(t, e3, e1)
 	// Output:
 }
 
-func ExampleFalse() {
-	False(t, 1 == int('a'))
-	// Output:
+func ExampleErrorAs() {
+	e1 := FakeError("e1")
+	e2 := fmt.Errorf("e2: %w", e1)
+	e3 := fmt.Errorf("e3: %w", e2)
+	var target FakeError
+	ErrorAs(t, e3, &target)
+	fmt.Println(target.Error())
+	// Output: e1
 }
 
-func ExampleFileContains() {
-	_ = os.WriteFile("/tmp/example", []byte("foo bar baz"), fs.FileMode(0600))
-	FileContains(t, "/tmp/example", "bar")
+func ExampleFalse() {
+	False(t, 1 == int('a'))
 	// Output:
 }
 
 func ExampleFileContainsFS() {
-	_ = os.WriteFile("/tmp/example", []byte("foo bar baz"), fs.FileMode(0600))
-	FileContainsFS(t, os.DirFS("/tmp"), "example", "bar")
-	// Output:
-}
-
-func ExampleFileExists() {
-	_ = os.WriteFile("/tmp/example", []byte{}, fs.FileMode(0600))
-	FileExists(t, "/tmp/example")
+	fsys := fstest.MapFS{
+		"example": &fstest.MapFile{
+			Data: []byte("foo bar baz"),
+		},
+	}
+	FileContainsFS(t, fsys, "example", "bar")
 	// Output:
 }
 
 func ExampleFileExistsFS() {
-	_ = os.WriteFile("/tmp/example", []byte{}, fs.FileMode(0600))
-	FileExistsFS(t, os.DirFS("/tmp"), "example")
-	// Output:
-}
-
-func ExampleFileMode() {
-	_ = os.WriteFile("/tmp/example_fm", []byte{}, fs.FileMode(0600))
-	FileMode(t, "/tmp/example_fm", fs.FileMode(0600))
+	fsys := fstest.MapFS{
+		"example": &fstest.MapFile{},
+	}
+	FileExistsFS(t, fsys, "example")
 	// Output:
 }
 
 func ExampleFileModeFS() {
-	_ = os.WriteFile("/tmp/example_fm", []byte{}, fs.FileMode(0600))
-	FileModeFS(t, os.DirFS("/tmp"), "example_fm", fs.FileMode(0600))
-	// Output:
-}
-
-func ExampleFileNotExists() {
-	FileNotExists(t, "/tmp/not_existing_file")
+	fsys := fstest.MapFS{
+		"example": &fstest.MapFile{Mode: 0600},
+	}
+	FileModeFS(t, fsys, "example", fs.FileMode(0600))
 	// Output:
 }
 
 func ExampleFileNotExistsFS() {
-	FileNotExistsFS(t, os.DirFS("/tmp"), "not_existing_file")
+	fsys := fstest.MapFS{}
+	FileNotExistsFS(t, fsys, "not_existing_file")
 	// Output:
 }
 

examples_unix_test.go

@@ -0,0 +1,44 @@
+// Copyright (c) The Test Authors
+// SPDX-License-Identifier: MPL-2.0
+
+//go:build unix
+
+package test
+
+import (
+	"io/fs"
+	"os"
+)
+
+func ExampleDirExists() {
+	DirExists(t, "/tmp")
+	// Output:
+}
+
+func ExampleDirNotExists() {
+	DirNotExists(t, "/does/not/exist")
+	// Output:
+}
+
+func ExampleFileContains() {
+	_ = os.WriteFile("/tmp/example", []byte("foo bar baz"), fs.FileMode(0600))
+	FileContains(t, "/tmp/example", "bar")
+	// Output:
+}
+
+func ExampleFileExists() {
+	_ = os.WriteFile("/tmp/example", []byte{}, fs.FileMode(0600))
+	FileExists(t, "/tmp/example")
+	// Output:
+}
+
+func ExampleFileMode() {
+	_ = os.WriteFile("/tmp/example_fm", []byte{}, fs.FileMode(0600))
+	FileMode(t, "/tmp/example_fm", fs.FileMode(0600))
+	// Output:
+}
+
+func ExampleFileNotExists() {
+	FileNotExists(t, "/tmp/not_existing_file")
+	// Output:
+}

internal/assertions/assertions.go

@@ -130,14 +130,14 @@ func Unreachable() (s string) {
 
 func Error(err error) (s string) {
 	if err == nil {
-		s = "expected non-nil error; is nil\n"
+		s = "expected non-nil error; got nil\n"
 	}
 	return
 }
 
 func EqError(err error, msg string) (s string) {
 	if err == nil {
-		s = "expected error; got nil\n"
+		s = "expected non-nil error; got nil\n"
 		return
 	}
 	e := err.Error()
@@ -151,13 +151,30 @@ func EqError(err error, msg string) (s string) {
 
 func ErrorIs(err error, target error) (s string) {
 	if err == nil {
-		s = "expected error; got nil\n"
+		s = "expected non-nil error; got nil\n"
 		return
 	}
 	if !errors.Is(err, target) {
 		s = "expected errors.Is match\n"
-		s += bullet(" error: %v\n", err)
 		s += bullet("target: %v\n", target)
+		s += bullet("   got: %v\n", err)
+	}
+	return
+}
+
+func ErrorAs[E error, Target *E](err error, target Target) (s string) {
+	if err == nil {
+		s = "expected non-nil error; got nil\n"
+		return
+	}
+	if target == nil {
+		s = "expected non-nil target; got nil\n"
+		return
+	}
+	if !errors.As(err, target) {
+		s = "expected errors.As match\n"
+		s += bullet("target: %v\n", target)
+		s += bullet("   got: %v\n", err)
 	}
 	return
 }
@@ -172,7 +189,7 @@ func NoError(err error) (s string) {
 
 func ErrorContains(err error, sub string) (s string) {
 	if err == nil {
-		s = "expected non-nil error\n"
+		s = "expected non-nil error; got nil\n"
 		return
 	}
 	actual := err.Error()