Skip to content
FmtTools

Workflow toolkit

Tools for Building Test Fixtures

The edge cases that break software are not random: absent keys, 2^53 boundaries, invisible marks, delimiters and coerced scalars. Build them on purpose, and keep the byte counts next to them.

Updated
November 17, 2026
Reading time
17 min read
Length
3,700 words
Reviewer note
Checked against the published specification
Cover illustration for the test fixture workflow page: a grid of small data samples with empty values, long numbers, emoji and quoted text marked up like a test report.

Production incidents almost never start in the middle of a value range. They start at a seam: the field that was absent rather than empty, the identifier one digit too long, the emoji that halved into a surrogate, the description that contained a comma. Random data generators are excellent at the middle and useless at the seams, so a fixture set worth keeping is built from the boundaries a specification describes and a real implementation gets wrong.

Edge cases cluster at boundaries, so build them there

A fixture is a piece of data with a written reason for existing. The reason is what separates it from sample data: a sample shows you what a record looks like, a fixture shows you what a record can legally be. RFC 8259 devotes a section to interoperability issues — the places where implementations are allowed to disagree. That clause is a fixture specification. Everything the standard permits without requiring, or requires without defining, is a place where two correct programs can disagree about your data.

Work the field list, not the file. For every field in your payload, the classes below are all reachable, and a fixture set that covers them for one record covers more ground than a thousand generated records that never leave the happy path. Each class is testable in one of the converters on this site, which means the fixture is verifiable before it ever reaches a pipeline.

The seven classes every fixture field should be assignable to
ClassWhat it probesExample valueWhere it bites
PresenceDoes the reader distinguish absent, null and empty?absent, null, ""Defaults, form validation, database NOT NULL
MagnitudeDoes the value fit the type it lands in?9007199254740991 then +2JSON.parse, doubles, spreadsheet display
Character classDoes the text contain a syntax character?"a,b", "say ""hi""", "=SUM(A1)"CSV splitting, formula evaluation, shell quoting
EncodingDo bytes, code units and code points agree?one ZWJ family emojiColumn widths, slice-based truncation, hashing
InvisibilityIs the value what it looks like?U+202E before a filenameLogs, review UIs, comparisons after normalisation
CoercionDoes a second reader type it differently?NO, 1.10, 0755, 1:30YAML config, query parameters, spreadsheet import
StructureDoes the shape rather than the value break things?201 arrays deep, duplicate keysRecursive parsers, object mapping, flattening

Two fields per class is enough for one record. A fixture file with fourteen fields can carry all seven classes twice.

Start with presence and magnitude, because those two change values silently. Then character class and coercion, which surface as parse failures and are the easiest to notice. Encoding and invisibility come next, since they show up as comparisons that fail for reasons nobody can see. Structure last, because it tends to be a property of the whole document. Keep the boundary values rather than the extreme ones: 9007199254740991 is a fixture; ten to the four hundred is a curiosity. For every numeric or length ceiling in your system, write the value just below the limit, the value exactly at it, and the value just past it.

Empty states and the three lengths of a string

There are at least six ways for a field to carry nothing, and most code can only tell two of them apart. Presence, emptiness and nullity are three distinct facts; a fixture that collapses them cannot detect a bug that collapses them further. The record below keeps all six in one object and is 47 bytes minified.

empty-states.json10 lines
{
  "absent": "the key below is not in the object at all",
  "nullValue": null,
  "emptyString": "",
  "spaceString": " ",
  "emptyObject": {},
  "emptyArray": [],
  "zero": 0,
  "false": false
}

Seven nothing-values plus one key that never appears. A whitespace-only string is not empty by length and not blank by intent, which is the seam most trim-on-read code falls into.

Test the absent key three ways, because the three tests are not equivalent: Object.hasOwn(record, key) answers whether the field was produced, record[key] === undefined answers whether it is undefined, and ?? and || answer different questions again. JSON has no undefined, so a missing key is the only absence a JSON document can carry — which is why code that maps JSON onto a typed object needs the distinction spelled out in the schema.

What each empty state becomes, measured through the converters on this site
Source stateIn JSONAfter CSV to JSON (safe)Back to CSVSurvives the pair?
key absent from the objectnothing to writenot applicable, keys come from the headerempty fieldno
empty cell in a rown/anullempty field, unquotedyes, as null
cell with one space" "string " " (untrimmed)quoted " "yes
cell with the text NULL"NULL"null via the token listNULLno, unless tokens are cleared
JSON nullnulln/aempty field, unquotedindistinguishable from empty
JSON empty string""n/aempty field, unquotedindistinguishable from null
JSON empty object{}n/athe two characters {}yes, as text
JSON empty array[]n/ajoined to an empty fieldno

The writer quotes a field only when RFC 4180 requires it, and a zero-length field requires nothing, so null and empty string both leave as nothing.

An empty document is not the same test as an empty field. {} and [] are both valid JSON, but a bare empty input is not, and the JSON validator says so with a dedicated empty-input error. The other near-misses deserve fixtures: [ ] with a single space, an object whose only key is the empty string, and an array holding one null.

Unicode and the three lengths of a string

Every length assertion in your code base measures one of four things: UTF-8 bytes, UTF-16 code units, Unicode code points, or user-perceived characters. UAX #29 defines the last as the extended grapheme cluster and states that a size limit counted in clusters is a user-perceived limit rather than a data-size limit. A fixture must therefore be tested with all four numbers written down.

unicode.json19 lines
{
  "familyZWJ": "👨‍👩‍👧‍👦",
  "flagUS": "🇺🇸",
  "skinTone": "👍🏽",
  "variationSelector": "❤️",
  "keycap": "1️⃣",
  "astralIdeograph": "𠀀",
  "combiningNFD": "café",
  "precomposedNFC": "café",
  "compatLigature": "file",
  "ohmSign": "Ω",
  "fullwidthC": "C",
  "oneHalf": "½",
  "hebrew": "שלום",
  "arabicRTL": "مرحبا",
  "cyrillicHomoglyph": "p\u0430l",
  "turkishI": "İstanbul",
  "sharpS": "Straße"
}

Seventeen values, all legal, all different lengths depending on which ruler you pick.

Measured lengths for six of those values, using a UTF-8 encoder and Intl.Segmenter
ValueUTF-16 unitsCode pointsUTF-8 bytesGrapheme clustersWhy it differs
family ZWJ emoji117251Four astral emoji at two units each plus three joiners
US flag4281A pair of regional indicator symbols, each astral
thumbs up with tone4281Modifier base plus Fitzpatrick sequence
heart with U+FE0F2261BMP base, emoji presentation selector
CJK extension ideograph U+200002141A single astral character, one surrogate pair
e plus U+03012231Combining mark: decomposed form, same cluster
fi ligature U+FB011131Compatibility character, one unit but three bytes

A varchar(255) column counts characters, a JavaScript .length check counts units, a byte budget counts bytes, and a UI label limit counts clusters.

slice(0, 1) on an astral value produces half a surrogate. TextEncoder replaces it with the three bytes of U+FFFD. Case mapping and normalisation both change lengths: lowercasing the dotted capital I yields an i plus a combining dot, and NFKC turns the fi ligature into f and i, the ohm sign into Greek capital omega, and one half into a digit, a fraction slash and a digit. Build both: a fixture pair that is canonically equal but byte-different, and one that is only compatibility-equal.

equality-pairs.json7 lines
{
  "canonicallyEqualButDifferentBytes": ["caf\u00e9", "cafe\u0301"],
  "compatibilityEqualOnly": ["file", "file"],
  "visuallyIdenticalDifferentCharacter": ["pal", "p\u0430l"],
  "uppercaseChangesLength": ["straße", "STRASSE"],
  "sameClusterDifferentCodePoints": ["👍", "👍🏽"]
}

Row three is the one that breaks joins: the Cyrillic а in the second value is U+0430, not the Latin a, so the strings differ in code points while displaying identically.

Invisible characters and strings that break parsers

The most expensive fixture characters are the ones nobody can see in a pull request. These fall into three groups with three different failure modes: format characters that change rendering direction, zero-width characters that change string identity, and syntax characters that are legal in one place and fatal in another. All three are testable by pasting into a tool that reports code points rather than shapes.

Invisible and bidirectional characters worth a fixture, with what each one breaks
Code pointNameWhat it does to a valueHow the tools report it
U+200Bzero width spaceSplits a token without splitting a word; three code points for "ab"unexpected-token error outside strings
U+00A0no-break spaceLooks like a separator, is not whitespace to a JSON readerinvalid-whitespace error naming the code point
U+FEFFzero width no-break spaceA byte order mark in the middle of a documentinvalid-whitespace error; utf8-bom warning at offset zero
U+200E / U+200FLRM / RLMReverses the direction of adjacent runs, so a filename renders differently from its bytesnothing visible in output; check the code point dump
U+202Eright-to-left overrideEverything after it renders right-to-left until the terminatornothing: it is a legal character inside a JSON string
U+2028 / U+2029line / paragraph separatorValid JSON inside a string, breaks eval-based consumptionjs-unsafe-line-separator info
U+0000 to U+001FC0 control charactersRFC 8259 section 7 requires all of them to be escapedunescaped-control-char error with the hex code
U+007FdeleteNot a control character under that clause, but not friendly to YAMLthe YAML writer quotes it; JSON does not mind
U+2044fraction slashAppears when normalising ½, and looks like an ordinary slashonly visible as bytes or as a code point dump

A character can be entirely legal in the format and still make your logs, your review UI and your filename display lie about what the value is.

The bidirectional controls are the ones to fixture first, because they are invisible in the tool that reviews the fixture. A string written as the letters txt, then U+202E, then exe renders right-to-left after the override, so what a reviewer sees is not what the bytes say. Pair the fixture with an assertion on the code point list rather than on the rendered text.

Strings that break parsers, spreadsheets and shells

RFC 4180 gives CSV exactly three structural characters: the comma, the double quote and the line break. A CSV fixture is therefore a test of four states: text containing a delimiter, text containing a quote, text containing a line break, and text with significant leading or trailing whitespace. A fixture value that is inert in JSON may also be an indicator in YAML or a control sequence in a shell, so build a field that is simultaneously a JSON string, a formula prefix, a YAML indicator, and something containing </.

hostile-but-legal.json13 lines
{
  "bidiOverride": "‮txt.exe",
  "rtlMarkTrailing": "invoice‏",
  "zeroWidthInside": "to​ken",
  "nbspInsteadOfSpace": "key value",
  "formula": "=SUM(A1:A9)",
  "atCommand": "@SUM(A1)",
  "yamlIndicator": "- not a list",
  "colonSpace": "note: see below",
  "closeTag": "</script>",
  "escapedBackslash": "C:\\tmp",
  "quotePair": "He said \"hi\"."
}

Eleven values, one document. The last two lines are the ones that most often fail on the way into a fixture file: a Windows path needs a doubled backslash in JSON, and a quoted phrase needs doubled quotes.

quoting.csv3 lines
id,plain,has_comma,has_quote,has_newline,padded,formula,negative,at_sign,tab_char
1,plain text,"Sausalito, CA","She said ""hi""","line one
line two"," leading and trailing ","=SUM(A1:A9)","-4+5","@SUM(A1)","one	two"

Nine fields in one row, each one targeting a single CSV rule. The embedded line break is the reason a row count is not a record count.

Number boundaries and identifiers that must stay text

The number grammar in RFC 8259 is one line — number = [ minus ] int [ frac ] [ exp ] — and almost every production failure of a numeric fixture is a violation of it rather than a size problem. A leading zero is not a legal integer, a plus sign is not a legal exponent prefix, and there is no literal for NaN or Infinity. Size problems are quieter: they change the value and leave the syntax valid.

The ceiling everybody means by a precision limit is 2^53, and the largest integer below it that is safe is 9007199254740991: the value of Number.MAX_SAFE_INTEGER. One above the ceiling, 9007199254740993 is not a different number from 9007199254740992 once parsed by a double-based reader: Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2 is true.

numbers.json18 lines
{
  "atTheCeiling": 9007199254740991,
  "onePastIt": 9007199254740992,
  "anOddNumberAboveIt": 9007199254740993,
  "belowTheFloor": -9007199254740993,
  "epochMilliseconds": 1703215800000,
  "epochMicroseconds": 1703215800000000,
  "epochNanoseconds": 1703215800000000000,
  "sixteenNines": 9999999999999999,
  "eighteenDigits": 453201511283036612,
  "negativeZero": -0,
  "overflowToInfinity": 1e400,
  "underflowToZero": 1e-400,
  "largestDouble": 1.7976931348623157e308,
  "smallestPositive": 5e-324,
  "binaryFloatSum": 0.30000000000000004,
  "asTextInstead": "9007199254740993"
}

Sixteen numeric states. Paste it into the validator: the whole numbers past the ceiling come back as unsafe-integer warnings, while every one of these parses.

Three of those values are more interesting than they look. 1e400 overflows to positive infinity, which has no JSON number form, so JSON.stringify writes null in its place. 1e-400 underflows to zero without complaint. And -0 is a real value in IEEE 754 that JSON.stringify prints as plain 0, so the sign survives in memory and disappears in the wire format. A fixture of nanoseconds since the epoch is around 1.7 times ten to the eighteen, more than a hundred times past the ceiling, while microseconds at 1.7 times ten to the fifteen are still safe.

Numeric literals, what they mean after a parse, and what the validator says
LiteralAfter a double parseReportFixture it as
9007199254740991exactnothing, it is inside the safe intervalnumber
90071992547409939007199254740992unsafe-integer warningstring
-9007199254740993-9007199254740992unsafe-integer warningstring
007not parsedleading-zero error, hint suggests quotingstring "007"
+7not parsedmalformed-number errorstring, or 7
.5 and 7.not parsedmalformed-number errorstring, or 0.5 / 7
1_000not parsednumeric-separator errornumber 1000
NaN, Infinitynot parsednon-standard-number errornull, or the string "Infinity"
1.7976931348623157e308exact, the largest doublenothingnumber
0.30000000000000004exact, this is what 0.1 + 0.2 isnothingnever compare with ===
"9007199254740993"unchanged textnothingstring, the correct fixture

The formatter and minifier print number literals from the source text rather than from a parsed value, so 9007199254740993 survives re-indenting.

Identifiers that look like numbers and must stay text

An identifier is a fixed-width string that happens to be spelled with digits. Two things go wrong at opposite ends: a value with a leading zero loses its left side to any numeric read, and a value longer than fifteen digits loses its right side to a double. Every system that touches the field has an opinion about which one happens, so the fixture has to carry both shapes side by side.

identifiers.json19 lines
{
  "uuidV4": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "uuidNil": "00000000-0000-0000-0000-000000000000",
  "uuidWithUppercaseHex": "3F2504E0-4F89-41D3-9A0C-0305E82C3301",
  "zipWithLeadingZeros": "00123",
  "e164Phone": "+44 20 7946 0958",
  "iban": "DE89 3704 0044 0532 0130 00",
  "gtin14": "00000123456780",
  "cardPan": "4532015112830366",
  "snowflakeId": "1234567890123456789",
  "semanticVersion": "1.10.0",
  "octalFileMode": "0755",
  "clockTime": "1:30",
  "israelCountryCode": "IL",
  "norwayCountryCode": "NO",
  "featureFlag": "on",
  "partNumber": "0000-00001",
  "sameValueAsNumber": 12
}

Sixteen identifiers plus the number 12 for contrast. 0000-00001 is a part number, and 12 is a quantity, and a fixture that keeps both proves which one your code retyped.

The same identifier text through three readers, measured against this site's engines
Fixture textAs JSONCSV to JSON, safe inferenceYAML 1.1 readerYAML 1.2 core reader
00123"00123" if quotedstring, leading zero fails the number grammarinteger 123 (octal in 1.1)string
0755"0755"stringinteger 493string
010"010"stringinteger 8string
1:30"1:30"stringinteger 90, base 60string
1.10.0"1.10.0"stringstringstring
1.10"1.10"number 1.1, the trailing zero is gonefloat 1.1float 1.1
NO"NO"stringboolean falsestring
on"on"stringboolean truestring
1e5"1e5"number 100000float 100000float 100000
4532015112830366"4532015112830366"string plus an unsafe-integer warningfloat, digits lostfloat, digits lost
1234567890123456789"1234567890123456789"string, above the ceilingfloat, digits lostfloat, digits lost

Every row is a value somebody has legitimately stored in an identifier column. The JSON column is the only one where the text survives untouched, and only because you quoted it first.

YAML coercion, depth, and duplicate keys

YAML is the only format on this site that types a plain scalar implicitly, and it has two mutually inconsistent rules for doing so. A fixture written for YAML has to survive both readers, which means knowing exactly which strings are also numbers, booleans, nulls or timestamps. The classification below is what the YAML to JSON converter produces when it reads each plain scalar against both schemas.

Plain scalars, what each YAML version resolves them to, and the risk label attached
Written asYAML 1.1 resolves toYAML 1.2 core resolves toRiskWhy it matters
NOboolean falsestring "NO"highThe country code for Norway, and a feature flag meaning no
onboolean truestring "on"highSwitches written as on and off, and the two-letter state code
y / n / Y / NbooleanstringhighAnswer columns in a fixture dataset
0755integer 493string "0755"highA leading zero means octal in 1.1: file modes and zip codes
010integer 8string "010"highVersion tens written as two digits become eight
1:30integer 90string "1:30"highColons mean base sixty, so clock times become durations
2024-01-15timestampstringhighExporters then write an epoch or a zone-shifted string
1.10float 1.1float 1.1mediumBoth versions agree, and both drop your trailing zero
1e5float 100000float 100000noneScientific notation is a number in both, even for IDs
~ / emptynullnullnoneA blank value is null in both, so absence needs a key
9007199254740993floatfloatmediumLonger than fifteen digits, so the last digit moves

The risk labels are the converter's own: high means a 1.1 reader and a 1.2 reader disagree about the type, medium means one type was chosen but the text changed.

fixture.yaml18 lines
- case: "no-coercion"
  country: "NO"
  flag: "on"
  mode: "0755"
  duration: "1:30"
  version: "1.10"
  day: "2024-01-15"
  id: "9007199254740993"
  answer: "y"
- case: "coerced-if-you-forget-quotes"
  country: NO
  flag: on
  mode: 0755
  duration: 1:30
  version: 1.10
  day: 2024-01-15
  id: 9007199254740993
  answer: y

Two documents in one block: the quoted record and the unquoted one. Convert the second and read the coercion report.

The JSON to YAML writer quotes by default any string that a YAML 1.1 reader would resolve to something other than a string, and returns the list of what it protected with the reason for each one. Two structural traps are YAML-specific: a stream containing multiple documents separated by three dashes converts only the first one, and anchors and aliases are shared references rather than copies, so a small YAML file can expand into an enormous structure.

Depth, duplicate keys and a root that is not an object

Structural fixtures break the container rather than the value, and they are the cheapest to write because they do not depend on your domain. Depth is a limit nobody documents: the JSON scanner behind the formatter and validator stops at 200 nested levels and reports a max-depth error. The fixture that matters is not the 200-level one but the 40-level and 8-level ones, because those pass here and break a recursive validator somewhere else.

Duplicate names are legal-ish and always lossy. RFC 8259 section 4 states that names within an object SHOULD be unique, and JSON.parse keeps the last value. A fixture with {"status":"ok","status":"error"} tests which side of the sentence your code is on. The validator reports the duplicate as a warning, and the formatter prints both members because it works from the syntax tree.

structure.json8 lines
{
  "duplicateName": { "status": "ok", "status": "error" },
  "emptyRootVariants": [ {}, [], [null], [[]] ],
  "mixedArray": [ 1, "1", true, null, { "a": 1 }, [2] ],
  "pathCollision": { "a.b": 1, "a": { "b": 2 } },
  "scalarRoot": 42,
  "deepButLegal": [ [ [ [ [ [ [ [ [ [ 1 ] ] ] ] ] ] ] ] ] ]
}

Six shapes. The pathCollision object is the sneaky one: flatten it with dotted paths and the two values land in one column.

Root shapes and what the JSON to CSV converter says about each
Root valueShape reportedOutputFinding
[{"a":1},{"a":2}]array-of-objectsone row per elementheterogeneous-records when keys differ
[[1,2],[3]]array-of-arraysheaderless table, column_1 onwardinfo, add the header yourself
[1,2,3]array-of-scalarsone column named valueinfo
[{"a":1},[2],"x"]mixed-arrayflattened independently, scalars in valuewarning
{"u1":{...},"u2":{...}}object-of-objectsrows with an added key columninfo, objects are unordered
{"a":1}single-objectone data rownothing
42scalara one-cell tablewarning, a bare value cannot be a table
[]empty-arraynothing at allerror, CSV needs a record to infer columns

The stats panel reports the same distinctions numerically: depth, object and array counts, the largest array, the record count, and a duplicate count.

CSV portability and schema contracts

A CSV fixture is finished when three unrelated programs agree on the same cell grid: a state machine that follows the grammar, such as the one behind CSV to JSON, a spreadsheet that picks a type before it asks you, and a bulk loader that decides what an empty field means. Begin with the smallest file that still touches every rule.

minimal-portable.csv4 lines
id,text,num,flag
1,"line one
line two",42.5,""

47 bytes as written here, with LF endings and a trailing line break. The same grid costs 50 bytes with CRLF and 53 with a byte-order mark in front.

In the fileOur parserA spreadsheetPostgreSQL COPY (FORMAT csv)
"" quoted emptyempty string, kept verbatimempty cell, General formatempty string, never null
nothing between two delimitersempty string here, null after safe type inferenceempty cellnull, unless the column is in FORCE_NOT NULL
NULL as bare textnull under the default tokens NULL and N/Athe four-letter wordtext, unless you declare the null string
unquoted 00123string; the number grammar rejects a leading zero123, and the zero is gone123 into an integer column, 00123 into text
unquoted =SUM(A1:A2)text, plus one formula-injection findingexecutes when the file openstext here; the damage happens on the next export

Those are not three implementations of one rule. They are three rules over the same bytes, so a fixture that only satisfies the first column is a parser test, not a portability test.

Line endings are the cheapest disagreement to remove and the most expensive to debug. RFC 4180 separates records with CRLF, but LF-only files are usable, and mixing them inside one file is what breaks. The byte-order mark is three bytes, EF BB BF, that our parser reports as a bom info finding and that Excel on Windows needs in order to auto-detect UTF-8. A loader that reads the header literally reads those bytes as part of the first column name and rejects the load. The spreadsheet-damage audit walks the parsed records and emits a cell, a column, the file line, a risk name, a reason and a fix: a leading =, + or @ is formula injection; 00123 is a dropped leading zero; twelve or more consecutive digits is precision loss; and a cell over 8,192 characters is flagged against the 32,767-character ceiling.

A schema that matches the fixture, not the happy path

A JSON Schema states the contract, and the interesting question is never whether the happy-path record passes. It is which of your fixtures is supposed to fail and for which keyword. Write the schema next to the fixture set, run every fixture through it, and check that the failures are exactly the ones you designed.

fixture.schema.json29 lines
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/customer-fixture",
  "title": "Customer fixture record",
  "type": "object",
  "additionalProperties": false,
  "required": ["id", "createdAt", "displayName", "amount"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "createdAt": {
      "type": "string",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$"
    },
    "displayName": { "type": ["string", "null"], "minLength": 1 },
    "amount": { "type": "string", "pattern": "^-?[0-9]+[.][0-9]{2}$" },
    "zip": { "type": "string", "pattern": "^[0-9]{5}(-[0-9]{4})?$" },
    "legacyTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 },
    "tags": {
      "type": "array",
      "items": { "enum": ["empty", "unicode", "boundary", "structural"] },
      "uniqueItems": true,
      "maxItems": 8
    },
    "legacyName": { "type": "string", "contentEncoding": "base64" }
  }
}

Draft 2020-12. Three decisions carry this file: additionalProperties is false, money is a string with a pattern, and displayName is nullable but never empty.

KeywordWhat it rejectsThe fixture that proves the keyword is wired up
requireda record that omits the keythe absent-key field, not the one where it is null
additionalProperties: falseany key outside propertiesthe same record plus one stray debug field
type as a uniona number where string or null was alloweddisplayName of 0 next to displayName of null
minLength and maxLengththe empty string, and the 4,000-character noteboth ends of one field, in one fixture
patternright type, wrong shapea version-1 UUID in a field patterned for version 4
formatnothing, unless the validator asserts formats2024-02-30 is the record to try
minimum and maximumintegers outside the stated range2^53 minus 1 and 2^53 as adjacent records
oneOfa record that matches two branches at onceamount sent as a number somewhere and a string elsewhere
uniqueItems and maxItemsa repeated tag, or a ninth tagthe mixed-array fixture, tightened
contentEncodinga string that is not valid base64pair it with the Base64 page before you ship

Every row needs a fixture that violates it. A schema no fixture fails is documentation, not a test.

format deserves the confusion it causes: in draft 2020-12 it is an annotation, so a validator that has not opted into format assertion accepts any string, including 2024-02-30T00:00:00Z. V8 rolls February 30 forward to 2024-03-01 without complaint, and treats a second value of 60, which RFC 3339 explicitly allows for leap seconds, as an invalid time. Either assert formats in the schema test or normalise timestamps with a parser that errors.

Deterministic fixtures and size you can defend

A snapshot that changes because the clock moved is not a test, it is a coin toss. Every source of drift below has turned a build red in some project at some hour, and each one is fixed by the same three moves: fix the input, fix the serialisation, redact what you cannot fix.

Source of driftWhat it does to the outputThe fix
the clockcreatedAt differs on every runa literal timestamp, and an injected clock in code
random identifiersevery run is a new documenta seeded generator, or one constant UUID
key ordera text diff shows a rewrite that changed nothingsort keys ascending, or compare parsed values
integer-like keysan object written 2, 1, 0, b, a prints as 0, 1, 2, b, aquote identifiers in the fixture when order carries meaning
number formattingstringify writes 1e+21 and 1e-10, not long digit stringsamounts as strings at a fixed scale
signed zerostringify prints -0 as plain 0assert with Object.is in code, never in JSON
collationthe default sort gives B then a then the a-umlaut; a German collator gives a, a-umlaut, Bsort by an explicit key, not by locale
time zonelocal ISO strings differ between a laptop and CIalways Z, or an explicit offset
line endingsCRLF churn, and a diff on every checkoutpin LF in the writer and keep the trailing break
indentation2 versus 4 versus tab rewrites the whole fileone documented indent setting

The integer-like-key row is the one people get wrong: ordering those keys first is specified behaviour, so it is deterministic, but it is not insertion order.

Do not diff two JSON files as text. Minify both with the same minifier settings, sort keys with the formatter in ascending order at a fixed indent, then compare. Redaction comes before the digest: replace volatile fields by path with a fixed token, sort any array whose order is not the thing under test, and keep the redaction list in the repository beside the fixture.

fixture
Data with a written reason for existing: it exercises one named behaviour of the code under test.
golden file
The recorded output a normalised run is compared against; regenerated deliberately, never accidentally.
canonical form
The serialisation rules applied before comparison: member order, indent, line endings, number rendering, redactions.
boundary value
A value at or one step away from a documented limit, such as 9007199254740991 and its successor.
redaction
Replacing volatile fields with a fixed token before comparison, so a diff can only contain real changes.
seeded generator
A generator whose output depends only on its seed, so a large fixture can be rebuilt and stays byte-stable.

Size fixtures you can defend

Committing a 20 MB blob to a repository buys nothing except a slow checkout. A size fixture should come from a seeded script, in one file, with its byte count printed next to it, so anyone reading the test can tell what big means in bytes and which behaviour it exists to prove: chunking, streaming, progress reporting, memory, or the point where a browser tab stops being willing to hold your table.

make-fixtures.mjs38 lines
import { writeFileSync } from 'node:fs'

const enc = new TextEncoder()
const bytes = (s) => enc.encode(s).length

const record = (id) => ({
  id,
  uuid: '3f2a6c1e-9b47-4c58-8f1d-7e2b9a0c4d63',
  name: 'Zoë Abár-Núñez',
  amount: '1049.95',
  createdAt: '2026-11-12T09:00:00Z',
  tags: ['edge-case', 'fixture'],
  note: null,
})

const encode = (n) => {
  const parts = []
  for (let i = 1; i <= n; i += 1) parts.push(JSON.stringify(record(i)))
  return '[' + parts.join(',') + ']'
}

const atMost = (target) => {
  let lo = 1
  let hi = 400000
  while (lo < hi) {
    const mid = (lo + hi + 1) >> 1
    if (bytes(encode(mid)) <= target) lo = mid
    else hi = mid - 1
  }
  return lo
}

for (const target of [1024, 1048576, 20971520]) {
  const n = atMost(target)
  const text = encode(n)
  writeFileSync('fixture-' + target + '.json', text)
  console.log(target, 'bytes ->', n, 'records,', bytes(text), 'actual,', text.length, 'chars')
}

The script that produced every number in this section. Run it with Node 24. Size is measured in UTF-8 bytes through TextEncoder, never as string length.

TargetRecordsActual bytesMeasured on one machine
1 KiB5901the ladder straddles the step: 6 records is 1,081 bytes
1 MiB5,7351,048,399JSON.parse median of five runs 28.1 ms, range 23.6 to 75.6
20 MiB113,96020,971,496JSON.parse median of five runs 491.3 ms, range 370.1 to 552.1
1 MiB pretty-printed5,7351,432,645the same data, 1.37 times larger, readable in a diff
1 MiB gzipped5,73518,00958.2 to 1, because every record is the same record

Node v24.13.0, one process. The byte counts travel; the timings do not.

Three honesty rules come attached to a table like that. First, bytes are not characters: one record here is 179 UTF-8 bytes and 175 characters, and at the 1 MiB step the file is 1,048,399 bytes against 1,025,459 characters. Second, a ratio of fifty-eight to one is a property of a repetitive synthetic file, not of your API. Third, the timings are medians of five runs with a slowest run 3.2 times the fastest, which is the argument for asserting on byte counts and field counts in a size test rather than milliseconds.

Fixture checklist and the page for each step

Twelve steps, in the order a fixture set gets built. Each row names the artefact that proves the step happened, so the checklist stays auditable instead of aspirational.

#StepEvidence it was donePage
1Separate the empty statesabsent key, null, empty string, empty object, empty array in one named recordvalidator
2Write down three string lengthsgraphemes, code points and UTF-16 units beside every text fixtureBase64
3Give invisible characters a fieldno-break space, zero-width joiner, right-to-left override, U+2028, one escaped lone surrogateencoding workflow
4Cross the safe-integer ceiling9007199254740991 and 9007199254740992 as adjacent records, money as a stringJSON validator
5Keep identifier-like text quoted007, 1e5, 1:30, NO, 0755 and a seventeen-digit account numberCSV to JSON
6Test one CSV in three readersBOM on and off, CRLF and LF, an embedded break, a quoted empty fieldCSV vs Excel
7Quote every coercible YAML scalarthe paired file: twenty-five bare booleans and dates beside their quoted twinsJSON to YAML
8Assert structure, not vibes201 levels of nesting, duplicate keys, a root array, a root scalar, a mixed arrayJSON formatter
9Let the schema fail on purposeone failing fixture per keyword, formats either asserted or droppedJSON guide
10Normalise before you diffminified, keys sorted, one indent, LF, volatile paths redactedJSON minifier
11Generate the size ladder1 KiB, 1 MiB and 20 MiB from a seed, byte counts printed in the logJSON to CSV
12Freeze the artefactssmall fixtures committed, large ones regenerated, counts recordedAPI debugging

The page column is the tool that shows whether the step happened. A row with no artefact attached is a row nobody can verify.

Answers

Questions about building test fixtures

What is the difference between null, an empty string and a missing key in a fixture?

Three different facts. A missing key says the field was never produced; null says it was produced with no value; "" says it was produced with an empty value. JavaScript collapses all three under truthiness, and CSV collapses all three into one empty field, so a fixture has to carry all three in separate named fields and test presence with Object.hasOwn, emptiness against '', and nullity against null.

Why does 9007199254740993 not work as a test ID?

Because it is not a distinct value in double precision. The largest integer that compares exactly is 9007199254740991 (2^53 − 1), and Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2 is true. The fixture should be the string "9007199254740993" wherever a test wants to prove that digits survive a round trip.

Which YAML values need quoting in a fixture?

Any scalar whose text is also valid as another type. NO, On, y resolve to booleans in YAML 1.1 and stay strings in 1.2; 0755 becomes integer 493 in 1.1 (octal); 1:30 becomes 90 (base 60); 1.10 becomes float 1.1 and loses the trailing zero; 2024-01-15 becomes a timestamp. The JSON to YAML converter quotes them by default and lists what it protected.

Can a JSON fixture contain duplicate keys?

It can, and it should, because that is one of the cheapest ways to find silent data loss. RFC 8259 section 4 says names SHOULD be unique but does not forbid repeats, and JSON.parse keeps the last value. A fixture with {"status":"ok","status":"error"} proves which side of that divide your code is on.

Related

Next up

Sources and further reading

  1. [1]RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format — The grammar (JSON-TEXT = ws value ws, and number = [ minus ] int [ frac ] [ exp ]), the section 4 SHOULD on unique names, section 6 leaving range and precision to the implementation while naming the interoperable interval -9007199254740991 to 9007199254740991, section 7 requiring U+0000 to U+001F to be escaped, and section 8 requiring UTF-8 and forbidding a byte order mark. (accessed November 12, 2026)
  2. [2]RFC 4180: Common Format and MIME Type for CSV Files — The seven record-and-field rules a CSV fixture has to exercise: CRLF-delimited records, an optional trailing break, an optional header line, spaces being part of a field and not ignorable, quoting required for fields containing a line break, a comma or a double quote, and doubled quotes as the only escape. (accessed November 12, 2026)
  3. [3]RFC 3339: Date and Time Formats for Internet Message Transfer — The date-time grammar full-date "T" full-time, the permitted lower-case t and z, the requirement that an offset or Z carries the zone, and the allowance of a second value of 60 for leap seconds. (accessed November 12, 2026)
  4. [4]RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace — The 8-4-4-4-12 hex layout, the version field values one through five, the variant bits, and the nil UUID of all zeros. (accessed November 12, 2026)
  5. [5]Unicode Standard Annex #15: Unicode Normalization Forms — Canonical versus compatibility equivalence and the four normalisation forms, with the warning that compatibility folding erases formatting distinctions and can prevent round-trip conversion. (accessed November 12, 2026)
  6. [6]Unicode Standard Annex #29: Unicode Text Segmentation — The extended grapheme cluster as the user-perceived character, and the statement that a text size limit based on grapheme clusters is a user-perceived limit rather than a data size limit. (accessed November 12, 2026)
  7. [7]Unicode Technical Standard #51: Unicode Emoji — How emoji are built: ZWJ sequences, emoji modifier sequences, Extended Pictographic characters, and tag sequences behind subdivision flags. (accessed November 12, 2026)
  8. [8]MDN: Number.MAX_SAFE_INTEGER — The exact value 9007199254740991, the definition of a safe integer as representable exactly and comparable correctly, and the worked example that MAX_SAFE_INTEGER + 1 === MAX_SAFE_INTEGER + 2 is true. (accessed November 12, 2026)
  9. [9]OWASP Community: CSV Injection (formula injection) — The attack class, the dangerous leading characters (=, +, -, tab and the carriage return and line feed), and the mitigations: quoting fields, prefixing with a single quote, and the tab prefix that survives Excel. (accessed November 12, 2026)