Skip to content

RDE-1.10: javascript-excel's conformance corpus through the public API - #213

Merged
securedeveloper merged 2 commits into
mainfrom
rde-1.10-conformance
Nov 17, 2026
Merged

securedeveloper merged 2 commits into
mainfrom
rde-1.10-conformance

Conversation

@securedeveloper

@securedeveloper securedeveloper commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Runs javascript-excel's conformance corpus (its JSE-9 files 01-values … 19-builders and 99-kitchen-sink) through react-data-export's public API and compares the result with javascript-excel's own output. The new docs/conformance.md has the per-file results.

How

  • Corpus. The corpus isn't in the javascript-excel npm package, so scripts/sync-jse-corpus.mjs copies test/conformance/corpus.ts and test/interop/xlsx_dump.py from the javascript-excel git tag that matches the installed version (currently v2.0.0-alpha.3; the corpus hasn't changed through alpha.7). The only edit is that the import of ../../src/index becomes javascript-excel. You refresh it with npm run conformance:sync. CI runs it with --check, so the copy can't drift from the engine under test. The copied files don't record the version, so an engine upgrade that leaves the corpus unchanged doesn't need a new copy.
  • Conversion (test/conformance/to-spec.ts). Each corpus workbook becomes an exportWorkbook spec:
    • a sheet frozen below a row of titles becomes a dataset with that row as its header, plus freezeHeader;
    • any other sheet becomes headerless blocks of array rows (header: false, index columns, fromDatasets offsets).
    • Column widths, hidden columns, column styles (as the column's style/headerStyle), right-to-left, the active sheet, document properties and write options all carry over.
    • Anything else is reported as "lost". Nothing is approximated.
  • Checks per file (conformance.test.ts):
    • the lost features are exactly the ones listed in expressible.ts, each with a reason;
    • the file is byte-identical to javascript-excel's file. When nothing is lost, that's the corpus file itself. Otherwise it's the same workbook without the lost features.
    • read back with javascript-excel/read: no warnings, and the same sheets, values, merges and names;
    • opened with openpyxl: the same sheets and cell values as javascript-excel's full corpus file;
    • for single-sheet files, exportDataset gives the same bytes as exportWorkbook, and format: 'csv' matches toCsvBlob.
  • Hooks and components (golden.test.tsx):
    • the 19-builders Dataset and Stacked sheets, built from the corpus's dataset input through exportWorkbook, exportDataset, useExcelExport and <ExcelExport>;
    • javascript-excel's table golden case through exportTable, useTableExport and <ExportTableButton>.
    • All of them are byte-identical to the javascript-excel builder plus toUint8Array. A guard test fails if the corpus's builder input changes.

Results

  • Byte-identical as-is: 05-formulas, 11-number-formats-locale, 12-colours, 18-limits (including the cell at XFD1048576 and the 64,000 cell formats).

  • Byte-identical without the listed features: every other file.

  • Not expressible through the React API:

    • column styles on the column itself, and column outline levels;
    • width: 'auto''s bestFit flag;
    • row heights, hidden rows, row outline levels and row styles;
    • the default row height;
    • merges other than header groups;
    • hidden sheets and tab colours;
    • zoom, gridlines, headings and the active cell;
    • frozen columns, or frozen rows other than the header rows;
    • an autofilter on a range other than the header and data rows;
    • print setup and defined names;
    • the 1904 date system and the workbook default font.

    The reasons are in docs/conformance.md. 19-builders is listed only because it's converted from the finished sheet; built from its dataset input, it's byte-identical.

CI

  • The full Node × React matrix runs the conformance tests as part of npm test. They skip openpyxl when it isn't installed.
  • A new Conformance job (Node 26) checks the corpus copy against the tag. It installs openpyxl==3.1.5 into a virtualenv (the same version javascript-excel's CI uses) and runs test/conformance with openpyxl required. It isn't a required check; whether to make it one is your call.
  • Upgrading javascript-excel now also needs npm run conformance:sync in the same PR, or this job fails. This is noted in CONTRIBUTING.md.

Dependencies

No new runtime or dev dependencies. openpyxl is a Python package, installed in the CI job's virtualenv only, as in javascript-excel.

No changeset: the change is tests, CI and docs only.

Local runs (Node 26): with javascript-excel 2.0.0-alpha.7 installed in place of alpha.3, the full suite passes, openpyxl included, and --check passes against the v2.0.0-alpha.7 tag. npm test passes on React 19 and React 17 (via scripts/use-react.mjs 17). npm run typecheck and docs:check pass. test/conformance with openpyxl passes 112 tests, with 1 skipped: openpyxl on the heavy 18-limits, which javascript-excel skips as well.

…c API

Every corpus workbook is converted to exportWorkbook input and compared with
javascript-excel's own file: byte-identical where the API can express the
whole file, otherwise byte-identical to the same workbook without the listed
features (docs/conformance.md). Also read back with javascript-excel/read,
opened with openpyxl in a new Conformance CI job, and the builder and table
golden cases go through the hooks and components.

The corpus is copied from javascript-excel's tag for the installed version
(npm run conformance:sync, checked in CI).
An upgrade that leaves the corpus unchanged then needs no new copy.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant