Tutorials

Debugging starts with a smaller reproduction

A practical way to turn an intermittent problem into a test you can reason about.

2 min read

Demo article · written for this development preview, not author-approved.

“It sometimes fails” describes a symptom, not a test. The first useful debugging task is to make the failure repeatable with as little surrounding code as possible.

Write down the boundary

Capture the input, expected output, actual output, and runtime version. Avoid copying production credentials or personal information into a fixture.

For example, suppose a date appears on the wrong day:

const input = '2026-10-09';
const date = new Date(`${input}T00:00:00+08:00`);
console.log(date.toISOString());
// 2026-10-08T16:00:00.000Z

The UTC date being one day earlier is not itself a bug. Midnight in Malaysia is 16:00 UTC on the previous day. The question is which timezone the product promised to display.

Remove one layer at a time

Run the date conversion without the UI. Then run the formatter without the API. Each reduction asks whether a particular layer is necessary for the failure.

Do not change five things at once. A passing result is only informative if you know which change produced it.

Preserve the discovery

Turn the reproduction into an assertion:

import assert from 'node:assert/strict';

const instant = new Date('2026-10-09T00:00:00+08:00');
assert.equal(instant.toISOString(), '2026-10-08T16:00:00.000Z');

That small check explains the boundary more precisely than a comment saying “fix timezone.” When another developer changes the code, it also explains what must remain true.

Stop when the root cause is fixed

A reproduction is a tool for understanding, not permission to rewrite the surrounding application. Fix the shared boundary, run the relevant checks, and leave unrelated code alone.