skip to content

Why should a Go test compare two time.Time values with their Equal method rather than ==?

level: middleimportance: should knowfreq 45%

answer

  1. time.Time is a struct, not an instant
  2. == compares fields, all of them
  3. time.Now carries something extra
  4. monotonic reading and location pointer
  5. Round(0) or UTC() strips the monotonic part

basics

~20 s

== compares every field of the time.Time struct, including the monotonic clock reading and the location pointer, so two values for the same instant can compare unequal. The Equal method compares the instant they represent.

solid answer

~50 s

`time.Time` is a struct, so `==` compares all of its fields - the wall clock, the location pointer and the monotonic clock reading that `time.Now` attaches. Two values that name the same instant therefore compare unequal if one came from `time.Now` and the other was decoded from JSON or a database, or if they carry different `*time.Location` values. `t.Equal(u)` compares the instant instead and is the correct assertion. The same trap hits `reflect.DeepEqual` on any struct that embeds a `time.Time`, because it walks those unexported fields too. Fixes, in order of preference: compare the time field with `Equal`; normalise both sides with `UTC()` or strip the monotonic reading with `Round(0)` before a struct-wide comparison; or, best of all, inject the clock so the library's timestamp is a value your test chose and `want` can be a literal.

code

go · 5 lines
go
start := time.Now()    // carries a monotonic clock reading
wall := start.Round(0) // same instant, monotonic reading stripped

fmt.Println(start == wall)     // false: the struct fields differ
fmt.Println(start.Equal(wall)) // true: the same instant

go deeper

for a junior

Remember the rule and one reason for it: use the Equal method on time.Time values in tests, because == also compares the location and the monotonic reading that time.Now attaches.

for a middle

Explain that time.Time is a struct with unexported wall, extra and location fields, name the monotonic clock reading, and say which calls strip it - Round(0), Truncate(0), UTC, Local and In.

for a senior

Show where the trap leaks into other assertions: any reflect.DeepEqual over a struct holding a timestamp. Then argue for injecting the clock so the value under test is one the test chose.

for a principal

Decide whether a library reads the wall clock at all. A type that takes its time source as an option is testable by every consumer forever; one that calls time.Now internally exports flakiness to everyone who imports it.

## time.Time is a struct, and == compares structs `time.Time` holds three unexported fields: a wall-clock reading, an extra field that carries either seconds or a monotonic clock reading, and a `*time.Location` pointer. Because all three are comparable, `time.Time` is comparable, `==` compiles, and it does exactly what `==` on any struct does - it compares every field. That is almost never the question a test means to ask. A test wants to know **whether two values name the same instant**. `Equal` answers that question; `==` answers a stricter one about representation. ## The three ways == says no when Equal says yes **The monotonic clock reading.** `time.Now` returns a value carrying both a wall-clock reading and a monotonic reading taken from the process's own steadily-increasing clock. The monotonic part exists so that `Sub` and `Since` measure real elapsed time even if the system clock is adjusted. It has no meaning outside the running process, so any value that has been serialised and parsed - through JSON, through a database row, through `time.Parse` - has no monotonic reading. Compare a freshly created value with its round-tripped self and `==` reports false even though the instant is identical. **The location.** The same instant expressed in UTC and in another zone has a different `*time.Location` pointer, so `==` reports false. `Equal` explicitly ignores location: its documentation notes that two times can be equal even when they are in different locations. **Precision.** Not a strict `==` versus `Equal` issue, but the same class of surprise: many stores round or truncate to microseconds, so the value that comes back is genuinely a different instant. `Equal` reports false there too - correctly - and that is the case where the test has found something real. ## Stripping and normalising When you must compare a whole struct that contains a timestamp, normalise before comparing: - `t.Round(0)` strips the monotonic clock reading and leaves the instant alone. `Truncate(0)` does the same. - `t.UTC()` (like `t.In` and `t.Local`) sets the location and, in doing so, also strips the monotonic reading. So `got.CreatedAt = got.CreatedAt.UTC()` on both sides makes a struct-wide comparison meaningful. The important part is that you do this **deliberately and visibly** in the test, so the next reader can see that the timestamp is being compared loosely on purpose. ## reflect.DeepEqual inherits the whole problem A `Result` struct with a `CalculatedAt time.Time` field, compared with `reflect.DeepEqual`, drags in exactly the same unexported fields. This produces one of the most confusing failures in Go testing: the message prints two timestamps that look character-for-character identical, and the assertion says they differ. The difference is the monotonic reading, which no format verb prints by default - `%v` on a `time.Time` with a monotonic reading appends something like `m=+0.001` only when the value is printed directly through its `String` method, and inside a struct printed with `%+v` you do see it, which is often the moment the penny drops. The cleanest structural answer is to compare the time field separately with `Equal` and compare the rest of the struct with whatever comparison suits it. ## The better fix: make the timestamp deterministic If a library stamps its results with the current time, every test comparing that field is comparing something the test did not choose. The durable fix is to let the caller supply the clock - a `now func() time.Time` field or option on the type - so a test passes a fixed instant and `want` becomes an ordinary literal: ```go fixed := time.Date(2026, time.March, 1, 12, 0, 0, 0, time.UTC) calc := Calculator{Now: func() time.Time { return fixed }} ``` Now `got.CalculatedAt.Equal(fixed)` is a real assertion about behaviour rather than a fight with the clock, and the struct comparison stops being flaky. A value built with `time.Date` carries no monotonic reading at all, which removes the whole class of surprise. ## The last resort Comparing `got.Format(time.RFC3339)` against a fixed string does work, and it is sometimes right when the formatted output *is* the contract - a log line, an API response body. Used as a general equality workaround it is worse than `Equal`, because it silently discards sub-second precision and hides zone differences behind whatever layout you picked. ## What to say in an interview Name the mechanism, not just the rule: `==` compares the struct including a monotonic reading and a location pointer; `Equal` compares the instant. Then show you know where it leaks - `reflect.DeepEqual` on any struct holding a `time.Time` - and finish with the fix that removes the problem rather than working around it, which is injecting the clock.

  • Does reflect.DeepEqual on a struct containing a time.Time have the same problem?
    Yes, and worse, because it is invisible. DeepEqual walks the unexported wall, extra and location fields, so a result built in-process compares unequal to one decoded from JSON at the same instant - and the printed message shows two timestamps that look identical. Compare the time field separately with `Equal`, or zero it on both sides before the struct comparison.
  • How would you remove the flakiness altogether rather than working around it?
    Stop letting the library read the wall clock during a test. Give the type a `now func() time.Time` field or option, default it to `time.Now`, and have the test supply a fixed instant built with `time.Date`. Such a value carries no monotonic reading, so `want` can be an ordinary literal and the assertion becomes a statement about behaviour rather than about timing.
  • Which calls strip the monotonic clock reading from a time.Time?
    `Round(0)` and `Truncate(0)` strip it while leaving the instant unchanged, and `UTC`, `Local` and `In` strip it as a side effect of reinterpreting the wall time in another location. Values produced by `time.Date` or by parsing never had one. Stripping it means later `Sub` calls fall back to the wall clock, which is fine in a test and not always fine in production timing code.

Two photographs of the same clock face are pictures of one instant, but the photographs themselves differ in every other way - == compares the photographs, Equal compares the instant.

saying these in an interview costs you the question

  • Says == on time.Time compares only the instant
  • Calls a failure after a JSON round-trip a flaky test
  • Believes time.Time is safe under reflect.DeepEqual because its fields are unexported
  • Compares formatted timestamp strings as a general equality workaround
  • Never questions why the library reads the wall clock during a test