tests/README.md

Tests

This deployment repo would normally carry no tests — upstream has them, and a copy-and-push pipeline has little to verify. These exist because of one thing: overlay/sdr-api-core.js is a hand-written JavaScript port of upstream's 1,200-line Python server, and a port that drifts from the server it mirrors makes the Space lie about what the tool does.

Nothing else in the build would notice that drift. These two suites do.

node tests\parity\run-parity.mjs         # the port vs. the real app.py
node tests\browser\run-browser-check.mjs # the built site in a real browser

Both run automatically in scripts\deploy.ps1 before anything is pushed, since a Static Space goes live the instant the push lands.

parity/ — is the port the same program?

run-parity.mjs replays one 67-request workflow twice and diffs the results:

• The reference. reference.py imports the vendored app.py from app/, points its storage at a temporary directory, replaces utc_now and uuid4 with counters, and serves it over real HTTP on a single-threaded server.
• The port. run-parity.mjs loads overlay/sdr-api-core.js in Node with an in-memory store and the same counters.

Then it compares every response status, every response body, the SHA-256 of the downloaded bytes, the final record store, and the list of stored uploads.

Two details do most of the work:

• Sequential timestamps and ids. Because the clock advances one second per call and ids count up from 1, the port has to call them the same number of times in the same order. A missing utc_now() or an extra uuid4() — easy to introduce, since Python builds its migration defaults dict eagerly and consumes an id whether it uses one or not — becomes a visible mismatch instead of a value nobody compares.
• A JSON round-trip on every load and save. app.py re-reads its file per request, so a handler that mutates a record and then fails without saving throws the change away. The in-memory store copies on load and save for the same reason; handing out a live object would let those changes stick and hide the difference.

The corpus

corpus/ is committed and covers the rubric and the text pipeline:

File	What it is for
clean-policy.md	All six required sections, long enough, no findings
messy-draft.md	Every placeholder form, two vague phrases, an overlong sentence, missing sections
tiny.txt	Short-document and every missing-section finding at once
unicode.md	Word counting across scripts, apostrophes, hyphens, and combining marks — where Python's Unicode-aware \w and JavaScript's ASCII \w would otherwise disagree
whitespace.txt	Rejected: no readable text
notes.rtf	Rejected: unsupported type

.corpus/ is generated by reference.py on each run and gitignored, because the fixtures are binary or encoding-specific: a deflated DOCX, a stored DOCX, a ZIP with no word/document.xml, a file that is not a ZIP at all, UTF-16 with a BOM, cp1252 with bytes that are not valid UTF-8, and an empty file.

corpus/** is marked -text in .gitattributes. One rubric rule counts characters between sentence terminators, so a CRLF checkout would change a finding.

Accepted divergences

ACCEPTED_DIVERGENCES in run-parity.mjs lists differences that are correct, each with its reason, and prints them on every run rather than dropping them. There is currently one: mimetypes.guess_type returns application/octet-stream for .docx on a Windows machine with no Office mapping, where the port always sends the real OOXML type.

Add to that list only for a difference you can justify in a sentence. Anything not on it fails the run.

browser/ — does it work as a page?

The parity suite runs the port in Node, so it says nothing about the parts between the port and the browser. run-browser-check.mjs serves the repository root over HTTP — plainly, with no SPA fallback, the way a Static Space does — opens it in headless Chromium through the DevTools protocol, and drives the real UI: upload, review, add a reviewer, assign, approve, download, reload.

It checks the things only a browser can prove:

• both overlay scripts loaded, in order, before app.js ran
• upstream's XMLHttpRequest calls are answered locally
• IndexedDB keeps the workspace across a reload
• the Download button produces a file instead of navigating to a path that does not exist on a static host
• no console errors anywhere in the run

It talks the DevTools protocol directly instead of adding a browser-automation dependency this repo otherwise has no use for. It finds Edge or Chrome from the usual Windows install paths; set BROWSER to override, and pass --headed to watch it happen.

One quirk worth knowing: approving a document that still has findings goes through window.confirm, and an unanswered dialog blocks the renderer — including the evaluation waiting on it. The client accepts the dialog over CDP rather than stubbing confirm in the page, so the real code path runs.

When a test fails after an upstream change

That is the intended outcome, not a broken test. build-static.ps1 will already have refused to build for the same reason. Read the upstream diff, carry the behavior into overlay/sdr-api-core.js, re-run both suites, then acknowledge the change with .\scripts\build-static.ps1 -AcceptUpstreamChanges.