In a Go test, how do you assert that a call returned a particular error?

## What "the right error" means in an assertion A Go function returns an error value, and a test has to decide what it is really asserting about it. There are four distinct claims, and they are not interchangeable: 1. **No error occurred.** 2. **Some error occurred.** 3. **This specific sentinel error occurred**, possibly wrapped inside other context. 4. **An error of this type occurred**, and its fields say something specific. Most weak error assertions are a case of asserting (2) while intending (3). ## The happy path Check it and stop: ```go got, err := Apply(order, "DE") if err != nil { t.Fatalf("Apply(order, %q) unexpected error: %v", "DE", err) } ``` `t.Fatalf` rather than `t.Errorf` because everything after this line reads `got`, and `got` is a zero value when the call failed. Continuing produces a cascade of secondary failures that bury the real one. ## Asserting a sentinel A sentinel is a package-level error value that callers are meant to recognise. The assertion is `errors.Is`: ```go if _, err := Apply(order, "XX"); !errors.Is(err, ErrUnknownJurisdiction) { t.Errorf("Apply(order, %q) error = %v, want %v", "XX", err, ErrUnknownJurisdiction) } ``` Two properties make this the right shape. It matches even when the library added context on the way out, so the test does not break the day someone adds detail to the message. And `errors.Is(nil, target)` is false for a non-nil target, so this single check also fails when the call unexpectedly succeeded - you do not need a separate `err == nil` guard. Using `err == ErrUnknownJurisdiction` instead is the classic mistake: it works today and breaks silently the moment the error is wrapped anywhere in the call chain. ## Asserting a typed error When the test cares about *what* was wrong - which field, which line item, which amount - declare a variable of the concrete error type and let `errors.As` fill it: ```go var verr *ValidationError if !errors.As(err, &verr) { t.Fatalf("Apply(order) error = %v, want a *ValidationError", err) } if verr.Field != "Amount" { t.Errorf("ValidationError.Field = %q, want %q", verr.Field, "Amount") } ``` The two-step shape matters: `Fatalf` on the type check, because the field assertion below would dereference a nil pointer otherwise. ## Why not compare the message `if err.Error() != "unknown jurisdiction: XX"` is tempting because it is one line and reads like the failure a user would see. It is a poor assertion: - Error messages are **prose**. Someone improves the wording, twenty tests go red, and the behaviour never changed. - Messages often embed **varying detail** - an id, a file path, a duration - so the test either becomes brittle or grows a substring match that no longer pins much. - **Two unrelated failures can produce the same text**, so a green assertion is not evidence the intended path ran. - The text is **not part of the contract** unless you have said it is. There is a real exception: when the message genuinely is the product - a command-line tool's output, an error body an API returns - assert it, once, in the test that owns that output. Not in every unit test that happens to be near an error. ## The assertion that pins nothing ```go if err == nil { t.Fatal("expected an error") } ``` This is honest but weak. It passes if the function fails for any reason at all, including a nil dereference you introduced in the line above the validation you meant to test. Reviewers should treat a bare non-nil check on a case whose whole point is *which* error as an unfinished assertion: either the package has no sentinel to match, in which case the gap is in the library's API rather than the test, or the test author skipped a step. ## Putting it together For a library other teams import, the error values are part of the exported surface, and the tests are where you demonstrate that. A case that asserts `errors.Is(err, ErrUnknownJurisdiction)` is simultaneously a test and a worked example of how a consumer is supposed to branch on the failure - which is a good reason to write it that way even when a cruder check would go green.