Test JavaScript unit conversions against exact rational answers

rakesh vetal — Fri, 06 Nov 2026 18:09:22 +0000

Unit conversion functions are short enough to look correct at a glance. A swapped factor or confused unit can still survive a handful of examples. A useful test strategy combines familiar anchor values, fractional inputs, reverse conversions and invalid-input checks.

Disclosure: I work on Calxo.ai. The examples below use our independently written, MIT-licensed calculator resource library.

Give the API an explicit contract

Our length function accepts a non-negative finite number and case-sensitive unit symbols. Unsupported units and negative lengths throw errors. That contract is deliberately about length magnitudes; another application might need signed displacements and should define that behavior separately.

Install the published package in a Node.js project (Node.js 22 or 24, ESM):

npm install @rakeshvetal/calculator-resources

Save this as conversion-checks.mjs:

import assert from "node:assert/strict";
import { convertLength, convertSpeed } from "@rakeshvetal/calculator-resources";

const closeTo = (actual, expected, tolerance = 1e-10) => {
  assert.ok(Math.abs(actual - expected) <= tolerance);
};

closeTo(convertLength(1, "nmi", "km"), 1.852);
closeTo(convertLength(0.5, "nmi", "m"), 926);
closeTo(convertLength(18.52, "km", "nmi"), 10);
closeTo(convertSpeed(22, "yd/s", "mph"), 45);
assert.equal(convertLength(0, "m", "ft"), 0);
assert.throws(() => convertLength(-1, "m", "km"), RangeError);
assert.throws(() => convertLength(1, "m", "unknown"), RangeError);
assert.throws(() => convertLength(NaN, "m", "km"), TypeError);

Run it with node conversion-checks.mjs. A successful run exits without an assertion error. The npm package contains the standalone functions and documentation. The larger reference dataset, generators and tests live in the source repository.

Keep reference answers separate from the implementation

An expected value calculated by calling the same conversion function cannot detect a mistake in that function. Our accompanying reference dataset instead uses integer ratios to represent the unit definitions and computes the answer with BigInt arithmetic.

For one international nautical mile in kilometers, the exact answer is 1852 / 1000, reduced to 463 / 250. A JavaScript Number gives a floating-point approximation to that rational result. Storing both the fraction and the approximation helps readers distinguish the definition from its numerical representation.

The NOAA explanation of nautical miles and knots and NIST conversion guide provide the definition references. Our generated cases are authored examples, not datasets supplied by those organizations.

Combine relative and absolute tolerance

For reference values at different magnitudes, use:

const accepted = Math.abs(actual - expected) <= Math.max(
  absoluteTolerance,
  relativeTolerance * Math.abs(expected)
);

The absolute tolerance handles values near zero. The relative term scales with the expected result. Choose tolerances for the domain and magnitudes being tested; a tolerance suitable for these examples is not automatically suitable for every numerical application.

Keep round trips, but add anchor values

Converting from A to B and back is helpful, but two reciprocal mistakes can cancel. A function could incorrectly equate a nautical mile with a statute mile and still pass a round-trip test. The independently known 1 nmi = 1.852 km anchor catches that confusion.

The repository includes 612 synthetic length and speed cases. A public Kaggle notebook reproduces the comparison in Python, with the reference dataset attached. The JavaScript library and dataset are MIT licensed; the Kaggle-hosted notebook copy is Apache 2.0.

This remains a compact reference set: it does not replace invalid-input testing, extreme-value testing or a review of the definitions themselves. For a visual counterpart to the nautical examples, Calxo's nautical miles to kilometers converter exposes an interactive calculation.

DEV Community: rakesh vetal

Test JavaScript unit conversions against exact rational answers

Give the API an explicit contract

Keep reference answers separate from the implementation

Combine relative and absolute tolerance

Keep round trips, but add anchor values