Skip to content

README.md

Latest commit

 

History

History
216 lines (172 loc) · 9.06 KB

README.md

File metadata and controls

216 lines (172 loc) · 9.06 KB

TOON Test Fixtures

This directory contains language-agnostic JSON test fixtures for validating TOON implementations against the specification. These fixtures cover core specification requirements; conformance is defined by SPEC.md (§13 and Appendix C), not by this fixture suite.

Directory Structure

tests/
├── fixtures.schema.json    # JSON Schema for fixture validation
├── fixtures/
│   ├── encode/             # Encoding tests (JSON → TOON)
│   │   ├── primitives.json
│   │   ├── objects.json
│   │   ├── arrays-primitive.json
│   │   ├── arrays-tabular.json
│   │   ├── arrays-nested.json
│   │   ├── arrays-objects.json
│   │   ├── delimiters.json
│   │   ├── whitespace.json
│   │   └── key-folding.json
│   └── decode/             # Decoding tests (TOON → JSON)
│       ├── primitives.json
│       ├── numbers.json
│       ├── objects.json
│       ├── arrays-primitive.json
│       ├── arrays-tabular.json
│       ├── arrays-nested.json
│       ├── delimiters.json
│       ├── whitespace.json
│       ├── root-form.json
│       ├── validation-errors.json
│       ├── indentation-errors.json
│       ├── blank-lines.json
│       └── path-expansion.json
└── README.md               # This file

Fixture Format

All test fixtures follow a standard JSON structure defined in fixtures.schema.json:

{
  "version": "<spec-version>",
  "category": "encode",
  "description": "Brief description of test category",
  "tests": [
    {
      "name": "descriptive test name",
      "input": "JSON value or TOON string",
      "expected": "TOON string or JSON value",
      "options": {},
      "specSection": "7.2",
      "note": "Optional explanation"
    }
  ]
}

<spec-version> is the baseline spec version for the file (e.g., "1.4", "3.2"); individual tests MAY override with minSpecVersion when they exercise a newer feature. See the field-descriptions table below.

Field Descriptions

Field Required Description
version Yes Baseline TOON spec version for this file. Per-test minSpecVersion overrides this for individual tests that exercise newer behavior. Fixtures remain valid for all later versions.
category Yes Test category: "encode" or "decode"
description Yes Brief description of what this fixture tests
tests Yes Array of test cases
tests[].name Yes Descriptive name explaining what is validated
tests[].input Yes Input value (JSON for encode, TOON string for decode)
tests[].expected Yes Expected output (TOON string for encode, JSON for decode)
tests[].shouldError No If true, expects an error (default: false)
tests[].options No Encoder/decoder options (see below)
tests[].specSection No Reference to specification section (e.g., "7.2", "§6")
tests[].note No Optional explanation for special cases
tests[].minSpecVersion No Minimum spec version required (e.g., "1.3")

Options

Encoding Options

{
  "delimiter": ",",
  "indent": 2,
  "keyFolding": "safe",
  "flattenDepth": 3
}
  • delimiter: "," (comma, default), "\t" (tab), or "|" (pipe). Affects encoder output; decoders parse the delimiter declared in array headers
  • indent: Number of spaces per indentation level (default: 2)
  • keyFolding: "off" (default) or "safe". Enables key folding to collapse single-key object chains into dotted-path notation
  • flattenDepth: Integer. Maximum depth to fold key chains when keyFolding is "safe" (default: Infinity). Values less than 2 have no practical folding effect

Decoding Options

{
  "indent": 2,
  "strict": true,
  "expandPaths": "safe"
}
  • indent: Expected number of spaces per indentation level (default: 2)
  • strict: Enable strict validation (default: true). When expandPaths is "safe", strict mode controls conflict resolution: errors on conflicts when true, LWW when false
  • expandPaths: "off" (default) or "safe". Enables path expansion to split dotted keys into nested object structures

Error Tests

Error tests use shouldError: true to indicate that the test expects an error to be thrown:

{
  "name": "throws on array length mismatch",
  "input": "tags[3]: a,b",
  "expected": null,
  "shouldError": true,
  "options": { "strict": true }
}

Note: Error tests do not specify expected error messages, as these are implementation-specific and vary across languages.

Using These Tests

To validate your TOON implementation against these fixtures:

  1. Load a fixture file from fixtures/encode/ or fixtures/decode/.
  2. Iterate through the tests array in the fixture.
  3. For each test case:
    • If shouldError is true: verify your implementation throws an error.
    • Otherwise: assert that your encoder/decoder produces the expected output when given the input.
  4. Pass options from test.options to your encoder/decoder (if present).

The fixture format is language-agnostic JSON, so you can load and iterate it using your language's standard JSON parser and test framework.

Note (spec v3.3+): Encoder fixtures for numbers inside the canonical range (n = 0 or 1e-6 ≤ |n| < 1e21, per §2) are byte-equal across conformant implementations. For values outside that range, §2 permits multiple valid forms; such fixtures verify via decode-and-compare round-trip.

Test Coverage

Encoding Tests (fixtures/encode/)

File Description Spec Sections
primitives.json String, number, boolean, null encoding and escaping §7.1/§7.2, §2
objects.json Simple objects, nested objects, key encoding §8 (keys: §7.3/§7.1)
arrays-primitive.json Inline primitive arrays, empty arrays §9.1
arrays-tabular.json Tabular format with header and rows §9.3
arrays-nested.json Arrays of arrays, mixed arrays §9.2/§9.4
arrays-objects.json Objects as list items, complex nesting §9, §10
delimiters.json Tab and pipe delimiter options §11
whitespace.json Formatting invariants and indentation §12
key-folding.json Key folding with safe mode, depth control, collision avoidance §13.4

Decoding Tests (fixtures/decode/)

File Description Spec Sections
primitives.json Parsing primitives, unescaping, ambiguity §4, §7.1/§7.4
numbers.json Number edge cases, exponent forms, leading zeros §4
objects.json Parsing objects, keys, nesting §8 (keys: §7.3/§7.1)
arrays-primitive.json Inline array parsing §9.1
arrays-tabular.json Tabular format parsing §9.3
arrays-nested.json Nested and mixed array parsing §9.2/§9.4
delimiters.json Delimiter detection and parsing §11
whitespace.json Whitespace tolerance and token trimming §12
root-form.json Root form detection (empty, single primitive) §5
validation-errors.json Syntax errors, length mismatches, malformed input §6, §14
indentation-errors.json Strict mode indentation validation §14.2, §12
blank-lines.json Blank line handling in arrays §14.2, §12
path-expansion.json Path expansion with safe mode, deep merge, strict-mode conflicts §13.4, §14.3

Coverage note: §3 host-type normalization (NaN/±Infinity → null, host Date/Set/Map/BigInt mappings) is intentionally outside these JSON fixtures, since the fixture format cannot express non-JSON encode inputs. Implementations should cover §3 in their language-local test suites.

Validating Fixtures

All fixture files should validate against fixtures.schema.json. Run the commands below from the repository root:

# Using ajv-cli
npx ajv-cli validate -s tests/fixtures.schema.json -d "tests/fixtures/**/*.json"

# Using check-jsonschema (Python)
pip install check-jsonschema
check-jsonschema --schemafile tests/fixtures.schema.json tests/fixtures/**/*.json

Contributing Test Cases

To contribute new test cases:

  1. Identify the category: Which fixture file should contain the test?
  2. Follow the format: Use the structure defined in fixtures.schema.json
  3. Add spec references: Link to relevant specification sections
  4. Validate: Verify the expected output against SPEC.md and that the fixture validates against the schema
  5. Submit PR: Include clear description of what the test validates

See CONTRIBUTING.md for detailed guidelines.

Questions or Issues?

If you find:

  • Test cases that contradict the specification
  • Missing coverage for edge cases
  • Ambiguous expected outputs
  • Schema validation issues

Please open an issue with:

  • Fixture file and test case name
  • Description of the issue
  • Proposed fix (if applicable)