testing

Instruction file imported from kod88vn/dexssil (.github/instructions/testing.instructions.md). Copyright stays with the author.

Testing

What actually matters here

The risk in this system is not that a button fails to click. It is that a number is wrong, a competitor brand leaks, or a layout drifts. Weight the suite accordingly.

Mandatory assertions

These encode findings from real client documents. They must exist and must never be weakened.

it.each([
  ["450°F", "232ºC"],
  ["0°F", "-18ºC"],
  ["-10°F", "-23ºC"],
  ["620 kgf", "6082 N"],
  ["143 cSt at 40°C", "143mm2/s a 40ºC"],
])("converts %s → %s", (input, expected) => {
   expect(convertToMetric(input).display).toBe(expected);
});

it("accepts a document with no temperature range (DEXSSIL 2801)", () => { /* ... */ });
it("accepts a document with no medioAmbiente (DEXSSIL 428)", () => { /* ... */ });
it("accepts a human override without a written reason", () => { /* ... */ });
it("freezes the disclaimer", () => expect(sha256(DISCLAIMER_ES)).toBe(KNOWN_HASH));
it("consumes every template placeholder", () => { /* ... */ });

Rules

1. Every exported function gets a test. No exceptions in packages/rules and packages/schema, which require ≥ 90% line coverage.
2. Test behaviour, not implementation. Never assert on a private function or an internal call count. If you must spy to test it, the seam is in the wrong place.
3. Fakes, not mocks. Implement the port interface with an in-memory fake in packages/ports/fakes. Do not vi.mock a vendor SDK — that tests your mock, not your code.
4. No network in unit tests. LlamaParse output is cached in fixtures/parsed/<sha256>.md. Tests run offline, free, and deterministically. Re-recording is an explicit manual command.
5. A test with no assertion is not a test. Never write a test that only checks the code did not throw, unless not-throwing is the actual requirement being stated.
6. Never change a test to make code pass. If a test is wrong, say so and explain why before touching it.
7. Name the scenario, not the function. accepts an override without a reason, not test patchDocument.

Word template tests

Template tests use a fixed valid document and a tracked .docx template:

1. Fill the template through the document port.
2. Open the resulting OOXML package and assert that no placeholder remains.
3. Assert that representative values, row numbers, and the product code are present.
4. Assert that the output is a valid .docx and preserves the supplied template structure.

Do not compare generated content against the historical DEXSSIL PDFs. The client has confirmed that final output intentionally differs from source content and that missing information may be supplied later. Extraction evaluation must use hand-labelled source ground truth instead.

Deferred platform integration

Database, queue, worker, and object-storage integration are deferred with those systems. They are not part of this delivery.

Route integration tests

Use the synchronous route with fake parser and transformer adapters returning recorded fixtures. Required scenarios cover valid PDF upload, magic-byte rejection, typed transformation/validation failures, and successful .docx response headers.

Full-platform revision, override, and worker scenarios are deferred.

Reporting

Never say "tests pass" without running them. Paste the command and its real output:

yarn test