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.
| Class | What it probes | Example value | Where it bites |
|---|---|---|---|
| Presence | Does the reader distinguish absent, null and empty? | absent, null, "" | Defaults, form validation, database NOT NULL |
| Magnitude | Does the value fit the type it lands in? | 9007199254740991 then +2 | JSON.parse, doubles, spreadsheet display |
| Character class | Does the text contain a syntax character? | "a,b", "say ""hi""", "=SUM(A1)" | CSV splitting, formula evaluation, shell quoting |
| Encoding | Do bytes, code units and code points agree? | one ZWJ family emoji | Column widths, slice-based truncation, hashing |
| Invisibility | Is the value what it looks like? | U+202E before a filename | Logs, review UIs, comparisons after normalisation |
| Coercion | Does a second reader type it differently? | NO, 1.10, 0755, 1:30 | YAML config, query parameters, spreadsheet import |
| Structure | Does the shape rather than the value break things? | 201 arrays deep, duplicate keys | Recursive 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.
{
"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.
| Source state | In JSON | After CSV to JSON (safe) | Back to CSV | Survives the pair? |
|---|---|---|---|---|
| key absent from the object | nothing to write | not applicable, keys come from the header | empty field | no |
| empty cell in a row | n/a | null | empty field, unquoted | yes, as null |
| cell with one space | " " | string " " (untrimmed) | quoted " " | yes |
| cell with the text NULL | "NULL" | null via the token list | NULL | no, unless tokens are cleared |
| JSON null | null | n/a | empty field, unquoted | indistinguishable from empty |
| JSON empty string | "" | n/a | empty field, unquoted | indistinguishable from null |
| JSON empty object | {} | n/a | the two characters {} | yes, as text |
| JSON empty array | [] | n/a | joined to an empty field | no |
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.
{
"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.
| Value | UTF-16 units | Code points | UTF-8 bytes | Grapheme clusters | Why it differs |
|---|---|---|---|---|---|
| family ZWJ emoji | 11 | 7 | 25 | 1 | Four astral emoji at two units each plus three joiners |
| US flag | 4 | 2 | 8 | 1 | A pair of regional indicator symbols, each astral |
| thumbs up with tone | 4 | 2 | 8 | 1 | Modifier base plus Fitzpatrick sequence |
| heart with U+FE0F | 2 | 2 | 6 | 1 | BMP base, emoji presentation selector |
| CJK extension ideograph U+20000 | 2 | 1 | 4 | 1 | A single astral character, one surrogate pair |
| e plus U+0301 | 2 | 2 | 3 | 1 | Combining mark: decomposed form, same cluster |
| fi ligature U+FB01 | 1 | 1 | 3 | 1 | Compatibility 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.
{
"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.
| Code point | Name | What it does to a value | How the tools report it |
|---|---|---|---|
| U+200B | zero width space | Splits a token without splitting a word; three code points for "ab" | unexpected-token error outside strings |
| U+00A0 | no-break space | Looks like a separator, is not whitespace to a JSON reader | invalid-whitespace error naming the code point |
| U+FEFF | zero width no-break space | A byte order mark in the middle of a document | invalid-whitespace error; utf8-bom warning at offset zero |
| U+200E / U+200F | LRM / RLM | Reverses the direction of adjacent runs, so a filename renders differently from its bytes | nothing visible in output; check the code point dump |
| U+202E | right-to-left override | Everything after it renders right-to-left until the terminator | nothing: it is a legal character inside a JSON string |
| U+2028 / U+2029 | line / paragraph separator | Valid JSON inside a string, breaks eval-based consumption | js-unsafe-line-separator info |
| U+0000 to U+001F | C0 control characters | RFC 8259 section 7 requires all of them to be escaped | unescaped-control-char error with the hex code |
| U+007F | delete | Not a control character under that clause, but not friendly to YAML | the YAML writer quotes it; JSON does not mind |
| U+2044 | fraction slash | Appears when normalising ½, and looks like an ordinary slash | only 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 </.
{
"bidiOverride": "txt.exe",
"rtlMarkTrailing": "invoice",
"zeroWidthInside": "token",
"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.
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.
{
"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.
| Literal | After a double parse | Report | Fixture it as |
|---|---|---|---|
| 9007199254740991 | exact | nothing, it is inside the safe interval | number |
| 9007199254740993 | 9007199254740992 | unsafe-integer warning | string |
| -9007199254740993 | -9007199254740992 | unsafe-integer warning | string |
| 007 | not parsed | leading-zero error, hint suggests quoting | string "007" |
| +7 | not parsed | malformed-number error | string, or 7 |
| .5 and 7. | not parsed | malformed-number error | string, or 0.5 / 7 |
| 1_000 | not parsed | numeric-separator error | number 1000 |
| NaN, Infinity | not parsed | non-standard-number error | null, or the string "Infinity" |
| 1.7976931348623157e308 | exact, the largest double | nothing | number |
| 0.30000000000000004 | exact, this is what 0.1 + 0.2 is | nothing | never compare with === |
| "9007199254740993" | unchanged text | nothing | string, 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.
{
"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.
| Fixture text | As JSON | CSV to JSON, safe inference | YAML 1.1 reader | YAML 1.2 core reader |
|---|---|---|---|---|
| 00123 | "00123" if quoted | string, leading zero fails the number grammar | integer 123 (octal in 1.1) | string |
| 0755 | "0755" | string | integer 493 | string |
| 010 | "010" | string | integer 8 | string |
| 1:30 | "1:30" | string | integer 90, base 60 | string |
| 1.10.0 | "1.10.0" | string | string | string |
| 1.10 | "1.10" | number 1.1, the trailing zero is gone | float 1.1 | float 1.1 |
| NO | "NO" | string | boolean false | string |
| on | "on" | string | boolean true | string |
| 1e5 | "1e5" | number 100000 | float 100000 | float 100000 |
| 4532015112830366 | "4532015112830366" | string plus an unsafe-integer warning | float, digits lost | float, digits lost |
| 1234567890123456789 | "1234567890123456789" | string, above the ceiling | float, digits lost | float, 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.
| Written as | YAML 1.1 resolves to | YAML 1.2 core resolves to | Risk | Why it matters |
|---|---|---|---|---|
| NO | boolean false | string "NO" | high | The country code for Norway, and a feature flag meaning no |
| on | boolean true | string "on" | high | Switches written as on and off, and the two-letter state code |
| y / n / Y / N | boolean | string | high | Answer columns in a fixture dataset |
| 0755 | integer 493 | string "0755" | high | A leading zero means octal in 1.1: file modes and zip codes |
| 010 | integer 8 | string "010" | high | Version tens written as two digits become eight |
| 1:30 | integer 90 | string "1:30" | high | Colons mean base sixty, so clock times become durations |
| 2024-01-15 | timestamp | string | high | Exporters then write an epoch or a zone-shifted string |
| 1.10 | float 1.1 | float 1.1 | medium | Both versions agree, and both drop your trailing zero |
| 1e5 | float 100000 | float 100000 | none | Scientific notation is a number in both, even for IDs |
| ~ / empty | null | null | none | A blank value is null in both, so absence needs a key |
| 9007199254740993 | float | float | medium | Longer 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.
- 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: yTwo 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.
{
"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 value | Shape reported | Output | Finding |
|---|---|---|---|
| [{"a":1},{"a":2}] | array-of-objects | one row per element | heterogeneous-records when keys differ |
| [[1,2],[3]] | array-of-arrays | headerless table, column_1 onward | info, add the header yourself |
| [1,2,3] | array-of-scalars | one column named value | info |
| [{"a":1},[2],"x"] | mixed-array | flattened independently, scalars in value | warning |
| {"u1":{...},"u2":{...}} | object-of-objects | rows with an added key column | info, objects are unordered |
| {"a":1} | single-object | one data row | nothing |
| 42 | scalar | a one-cell table | warning, a bare value cannot be a table |
| [] | empty-array | nothing at all | error, 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.
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 file | Our parser | A spreadsheet | PostgreSQL COPY (FORMAT csv) |
|---|---|---|---|
| "" quoted empty | empty string, kept verbatim | empty cell, General format | empty string, never null |
| nothing between two delimiters | empty string here, null after safe type inference | empty cell | null, unless the column is in FORCE_NOT NULL |
| NULL as bare text | null under the default tokens NULL and N/A | the four-letter word | text, unless you declare the null string |
| unquoted 00123 | string; the number grammar rejects a leading zero | 123, and the zero is gone | 123 into an integer column, 00123 into text |
| unquoted =SUM(A1:A2) | text, plus one formula-injection finding | executes when the file opens | text 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.
{
"$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.
| Keyword | What it rejects | The fixture that proves the keyword is wired up |
|---|---|---|
| required | a record that omits the key | the absent-key field, not the one where it is null |
| additionalProperties: false | any key outside properties | the same record plus one stray debug field |
| type as a union | a number where string or null was allowed | displayName of 0 next to displayName of null |
| minLength and maxLength | the empty string, and the 4,000-character note | both ends of one field, in one fixture |
| pattern | right type, wrong shape | a version-1 UUID in a field patterned for version 4 |
| format | nothing, unless the validator asserts formats | 2024-02-30 is the record to try |
| minimum and maximum | integers outside the stated range | 2^53 minus 1 and 2^53 as adjacent records |
| oneOf | a record that matches two branches at once | amount sent as a number somewhere and a string elsewhere |
| uniqueItems and maxItems | a repeated tag, or a ninth tag | the mixed-array fixture, tightened |
| contentEncoding | a string that is not valid base64 | pair 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 drift | What it does to the output | The fix |
|---|---|---|
| the clock | createdAt differs on every run | a literal timestamp, and an injected clock in code |
| random identifiers | every run is a new document | a seeded generator, or one constant UUID |
| key order | a text diff shows a rewrite that changed nothing | sort keys ascending, or compare parsed values |
| integer-like keys | an object written 2, 1, 0, b, a prints as 0, 1, 2, b, a | quote identifiers in the fixture when order carries meaning |
| number formatting | stringify writes 1e+21 and 1e-10, not long digit strings | amounts as strings at a fixed scale |
| signed zero | stringify prints -0 as plain 0 | assert with Object.is in code, never in JSON |
| collation | the default sort gives B then a then the a-umlaut; a German collator gives a, a-umlaut, B | sort by an explicit key, not by locale |
| time zone | local ISO strings differ between a laptop and CI | always Z, or an explicit offset |
| line endings | CRLF churn, and a diff on every checkout | pin LF in the writer and keep the trailing break |
| indentation | 2 versus 4 versus tab rewrites the whole file | one 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.
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.
| Target | Records | Actual bytes | Measured on one machine |
|---|---|---|---|
| 1 KiB | 5 | 901 | the ladder straddles the step: 6 records is 1,081 bytes |
| 1 MiB | 5,735 | 1,048,399 | JSON.parse median of five runs 28.1 ms, range 23.6 to 75.6 |
| 20 MiB | 113,960 | 20,971,496 | JSON.parse median of five runs 491.3 ms, range 370.1 to 552.1 |
| 1 MiB pretty-printed | 5,735 | 1,432,645 | the same data, 1.37 times larger, readable in a diff |
| 1 MiB gzipped | 5,735 | 18,009 | 58.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.
| # | Step | Evidence it was done | Page |
|---|---|---|---|
| 1 | Separate the empty states | absent key, null, empty string, empty object, empty array in one named record | validator |
| 2 | Write down three string lengths | graphemes, code points and UTF-16 units beside every text fixture | Base64 |
| 3 | Give invisible characters a field | no-break space, zero-width joiner, right-to-left override, U+2028, one escaped lone surrogate | encoding workflow |
| 4 | Cross the safe-integer ceiling | 9007199254740991 and 9007199254740992 as adjacent records, money as a string | JSON validator |
| 5 | Keep identifier-like text quoted | 007, 1e5, 1:30, NO, 0755 and a seventeen-digit account number | CSV to JSON |
| 6 | Test one CSV in three readers | BOM on and off, CRLF and LF, an embedded break, a quoted empty field | CSV vs Excel |
| 7 | Quote every coercible YAML scalar | the paired file: twenty-five bare booleans and dates beside their quoted twins | JSON to YAML |
| 8 | Assert structure, not vibes | 201 levels of nesting, duplicate keys, a root array, a root scalar, a mixed array | JSON formatter |
| 9 | Let the schema fail on purpose | one failing fixture per keyword, formats either asserted or dropped | JSON guide |
| 10 | Normalise before you diff | minified, keys sorted, one indent, LF, volatile paths redacted | JSON minifier |
| 11 | Generate the size ladder | 1 KiB, 1 MiB and 20 MiB from a seed, byte counts printed in the log | JSON to CSV |
| 12 | Freeze the artefacts | small fixtures committed, large ones regenerated, counts recorded | API 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]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]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]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]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]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]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]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]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]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)
