Match the runner to the execution environment
Inspect the existing package scripts, module format, and transform configuration before adding tests. CommonJS, ES modules, TypeScript, and bundler aliases can require different setup. A test that resolves imports differently from the application can pass while missing a packaging problem, so keep the intended runtime boundary clear in the test plan.
Use a direct function test for a normalization or pricing rule. Keep DOM setup out of that test unless the behavior depends on document APIs. This reduces unrelated environment work and makes the failure point more local, while separate component or browser checks can verify the way the interface calls the rule.
Make asynchronous failures part of the result
Return or await the promise under test so the runner observes its completion. Assert rejection explicitly when an error is expected. A test that starts asynchronous work and then exits may pass before the relevant assertion runs, leaving an apparently green result with no evidence about the eventual outcome.
Use fake clocks only when the timer boundary matters and restore them after the case. Control network dependencies through a narrow seam or a documented interception setup. Do not let a unit check depend on a real endpoint whose changing data or availability can hide the local behavior you intended to verify.
Use assertions that survive refactoring
Compare meaningful values and public state instead of private call sequences. For a parser, assert the resulting fields and defined errors. For a collection transformation, include ordering only if the contract promises it. These choices keep the check strict about requirements while avoiding unnecessary coupling to an implementation detail that may change safely.
Run the important cases in the repository's normal environment and review coverage as a map of executed code, not proof of correctness. Add boundary cases and verify a plausible wrong output is rejected. Keep integration checks for module packaging, real service contracts, and browser behavior that the isolated unit runner does not exercise.
Working sheet
| Pitfall | Correction | Evidence gained |
|---|---|---|
| Unawaited promise | Await or return it | Failure observed |
| Leaked fake clock | Restore in cleanup | Independent cases |
| Truthiness assertion | Exact result comparison | Wrong content rejected |
| DOM assumption | Browser check where needed | Real runtime behavior |
Questions about javaScript unit testing: boundaries and test doubles
Do all JavaScript tests need a DOM?
No. Test pure logic without a document environment and add rendered checks for interface behavior.
Does TypeScript remove the need for runtime tests?
No. Types do not establish business rules, external data validity, or runtime effects.
How should I use the working sheet?
Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.
Sources and further reading
Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.
