Comparing Expected and Actual

## Go has no assertion vocabulary, on purpose Many test frameworks give you a sentence-shaped API - `assertEquals`, `expect(x).toBe(y)`. Go's standard `testing` package gives you none of that. A test is a plain function, a comparison is a plain `if`, and reporting a failure is a call to `t.Errorf` or `t.Fatalf`. Nothing is magic, which means nothing is hidden - and it also means the quality of a test's failure output is entirely on the person who wrote it. That splits the job into two decisions: **which comparison**, and **what the failure message says**. ## Choosing the comparison - **`==`** works for *comparable* types: numbers, strings, booleans, pointers, channels, interfaces, and structs or arrays whose fields are all themselves comparable. This is the default and you should reach for it first - it is exact, it is fast, and it is checked at compile time. - **A struct containing a slice, a map or a function is not comparable**, and `got == want` on one does not compile. That compile error is the usual reason a test author reaches for something else. - **`reflect.DeepEqual(got, want)`** walks two values recursively and reports whether they are deeply equal. It works on anything, which is exactly why it needs care: it compares every field, including unexported ones, it treats a nil slice and an empty non-nil slice as different, and it reports false for two `NaN` float values. - **`slices.Equal(got, want)`** compares two slices of comparable elements element by element. It is checked at compile time, it is cheaper than reflection, and it reports true for any two length-zero slices. `maps.Equal` is its counterpart for maps. - **Compare one field** when only one field is the point of the case. A narrow assertion produces a narrow failure message. ## Writing the failure message The convention throughout the standard library's own tests is to make the message read like the expression that was evaluated, followed by the expectation: ``` Total(items) = 499, want 500 Apply(order, "DE") = 119, want 120 ``` Three things earn their place in that line: 1. **The call and the inputs that identify the case.** Someone reading a CI log should know which case failed without opening the file. 2. **The value you got.** First, because the reader is looking for what the code did. 3. **The value you wanted.** Second, after `want`. The verb matters less than the consistency. A package where half the messages read `want 500, got 499` and half read the other way forces every reader to work out which number is which, and a reversed message sends people hunting for a bug on the wrong side. Pick the verb to match the value: - `%v` for most values. - `%q` for strings, so trailing whitespace and empty strings are visible. - `%+v` for structs, so field names appear. - `%#v` when the two sides print identically under `%v` - a nil slice and an empty slice both print as `[]`, and a message reading `got [], want []` helps nobody. ## Error or Fatal `t.Errorf` records the failure and lets the function continue, so a test that checks several independent things reports all of them in one run. `t.Fatalf` stops the test function immediately - the right choice when continuing would dereference something you just failed to obtain, because the follow-on failures would be noise. ## What this looks like in a library other teams import Suppose you maintain a small money and tax library and `Total` returns the order total in minor units: ```go func TestTotal(t *testing.T) { items := []Item{{Cents: 199}, {Cents: 301}} got := Total(items) if want := 500; got != want { t.Errorf("Total(%v) = %d, want %d", items, got, want) } } ``` The comparison is one line. The message tells a reader on a different team, reading a failed CI job on a dependency bump, exactly what was fed in and what came back. That is the entire craft here: Go gives you no assertion helper, so the assertion and its message are yours to write well. ## Anti-patterns worth naming - `t.Error("mismatch")` - true and useless. - Comparing formatted strings (`fmt.Sprint(got) == fmt.Sprint(want)`) instead of values, which silently equates values of different types. - Panicking instead of reporting, which loses the test framework's file and line attribution. - Reversing got and want in some tests but not others.