In XCTest, why does XCTAssertEqual fail on a computed Double such as an average fuel consumption, and how does accuracy fix it?
answer
- decimals stored in binary
- 6.1 is not exactly representable
- compare the difference, not the bits
- fails only when the gap exceeds accuracy
- too wide a tolerance hides a bug
basics
~10 sDouble stores most decimals approximately, so (5.9 + 6.2 + 6.2) / 3 is 6.1000000000000005 and plain XCTAssertEqual fails. XCTAssertEqual(::accuracy:) passes when the two values differ by no more than the accuracy.
solid answer
~40 sPlain `XCTAssertEqual` compares with `==`, and a `Double` holds most decimal fractions only approximately, so `(5.9 + 6.2 + 6.2) / 3` evaluates to `6.1000000000000005`, not `6.1`, and the assertion fails on values that differ only in their last digits. The fix is `XCTAssertEqual(average, 6.1, accuracy: 0.001)`, which records a failure only when the difference between the two values is greater than the accuracy. Choose the accuracy from what the code promises, well below the step a user would notice: a tolerance as wide as `0.1` would let a calculator that returns `6.8` instead of `6.7` pass. `XCTAssertNotEqual` has the same `accuracy:` form, and the older `XCTAssertEqualWithAccuracy` is deprecated in favour of it.
code
swift · 18 linesimport XCTest
struct FuelEconomyCalculator {
func averageConsumption(_ trips: [Double]) -> Double {
trips.reduce(0, +) / Double(trips.count)
}
}
final class FuelEconomyCalculatorTests: XCTestCase {
func testAverageConsumptionOfThreeTrips() {
let average = FuelEconomyCalculator().averageConsumption([5.9, 6.2, 6.2])
// Fails: the computed value is 6.1000000000000005.
// XCTAssertEqual(average, 6.1)
XCTAssertEqual(average, 6.1, accuracy: 0.001, "litres per 100 km")
}
}go deeper
Recall that most decimals are approximate in a Double and that XCTAssertEqual(::accuracy:) compares within a tolerance. Know the failure rule: a difference greater than the accuracy.
Explain why exact == fails, why string comparison does not help, and how to size an absolute tolerance from the precision the feature promises.
Show you review tolerances as risk: a wide accuracy hides real rounding bugs, and a red tolerance test is investigated with the actual value before anyone widens it.
Decide whether money-like or regulated figures should be computed in Decimal rather than tested around Double error, and set the team's default for tolerances in shared helpers.
## Why exact equality fails on Double A `Double` is a **binary floating-point** number. Values such as 5.9, 6.2 and 6.1 have no exact binary representation, so each literal becomes the nearest representable `Double`, and every addition and division rounds its result again. The small errors do not always cancel. In a fuel-economy module that averages three trips: - `(5.9 + 6.2 + 6.2) / 3` evaluates to `6.1000000000000005`; - the literal `6.1` is a different `Double`; - `XCTAssertEqual(_:_:)`, which is generic over `Equatable` and compares with `==`, therefore fails. The two values differ only in the sixteenth significant digit, so the failure looks absurd at first glance. Nothing is wrong with the calculator; the assertion asked for bit-for-bit equality. ## The accuracy overload XCTest has an overload for numbers that should be equal **within a tolerance**: `XCTAssertEqual(_:_:accuracy:_:file:line:)`. In Swift it is generic over `FloatingPoint`, with a second overload for `Numeric`. The Objective-C header describes the rule precisely: it generates a failure when the difference between the two expressions is **greater than** the accuracy. So: | Call | Difference | Result | |---|---|---| | `XCTAssertEqual(6.1000000000000005, 6.1, accuracy: 0.001)` | about 9e-16 | passes | | `XCTAssertEqual(6.8, 6.7, accuracy: 0.001)` | about 0.1 | fails | | `XCTAssertEqual(6.8, 6.7, accuracy: 0.1)` | just under 0.1 | passes | The same `accuracy:` form exists for `XCTAssertNotEqual`. The older names `XCTAssertEqualWithAccuracy` and `XCTAssertNotEqualWithAccuracy` are marked deprecated and renamed to these overloads in the Swift interface, so new code uses the `accuracy:` label. Every variant also takes an optional message, such as `"litres per 100 km"`, which appears beside the two values when the check fails. ## Choosing the tolerance The accuracy is an **absolute** difference in the same unit as the values, not a percentage and not a count of decimal places. Choose it deliberately: 1. Start from the precision the feature promises. A consumption shown to one decimal place has a visible step of 0.1. 2. Pick an accuracy far below that step, such as `0.001`, so a result that rounds to the wrong tenth still fails. 3. Size it per quantity: `0.001` litres per 100 km and `0.001` kilometres on an odometer total are different promises, so each assertion gets an accuracy in its own unit. The third row of the table is the trap. A tolerance as wide as the display step passes a calculator that returns `6.8` where `6.7` was expected, because `6.8 - 6.7` in `Double` arithmetic is `0.09999999999999964`, just under `0.1`. ## What not to do instead - **Do not compare `description` strings.** The description of the average is `"6.1000000000000005"`, so the string comparison fails exactly as the value comparison does, and it adds formatting rules to the test. - **Do not write `XCTAssertTrue(abs(a - b) < 0.001)`.** It works, but on failure XCTest reports only that a Boolean was false; `XCTAssertEqual(_:_:accuracy:)` reports both values. - **Do not use a tolerance for integers, strings or enums.** Exact `XCTAssertEqual` is right there; the accuracy overloads exist for values whose arithmetic rounds. - **Do not loosen the accuracy until a red test turns green.** If a tight tolerance fails, print the actual value first; a difference of 0.1 is a bug, not noise. ## Bounds instead of a single value Sometimes the honest expectation is a range rather than a point. XCTest's comparison assertions take any `Comparable` values: `XCTAssertGreaterThan`, `XCTAssertGreaterThanOrEqual`, `XCTAssertLessThan` and `XCTAssertLessThanOrEqual`. A check that consumption never exceeds a sanity ceiling, such as `XCTAssertLessThanOrEqual(consumption, 30)`, reads better as a bound than as an equality with a huge accuracy. Like `XCTAssertEqual`, each one reports both values on failure and accepts an optional message, so the report says what was measured and against what. ## Where the scenario fits In the fuel-economy module, the calculator averages trips and rounds consumption to one decimal place for display. Test the average with a tight `accuracy:`, and test the rounding with expected values whose wrong neighbours lie outside the tolerance, so both the arithmetic and the rounding rule are pinned down.
- Why not make every floating-point assertion in the suite use accuracy: 0.1 to stop flaky reds?Because the tolerance is the size of bug the test agrees to miss. With `accuracy: 0.1`, a consumption of `6.8` passes where `6.7` was expected, since the difference is just under 0.1. Size each accuracy from what that value promises, well below its visible step, and investigate any failure before widening it.
- What does XCTAssertEqual(_:_:accuracy:) report when it fails, compared with XCTAssertTrue(abs(a - b) < e)?XCTest builds the accuracy assertion's failure description from both values and the accuracy, so the report shows how far apart they were. `XCTAssertTrue` only knows its Boolean was false, so you must add a message by hand to learn the actual value. Both can take an optional message string.
- XCTAssertEqual on two Doubles that print the same always passes.
- The accuracy argument is a percentage of the expected value.
- The accuracy argument counts how many decimal places to compare.
- Comparing the description strings avoids floating-point problems.
- A wider accuracy is always safer because it removes flaky failures.