When adding or updating tests, prefer realistic behavior checks over brittle mocks, keep them deterministic, and assert meaningful invariants.
Guidelines
- Avoid fragile/platform-breaking plumbing: If a mock would require shell wrappers or breaks on Windows, use the real underlying behavior (or an integration/smoke setup) instead.
- Isolate the environment for “real” checks: Run binaries with a temp HOME/data dir and explicitly set discovery/ports so parent-process config can’t affect results.
- Reuse exported constants as source-of-truth: Don’t hardcode values like package names/versions when the module already exports them; test should fail when the export changes.
- Stub the right layer to prevent async leaks: Ensure stubs don’t leave never-ending streams/listeners running past the test boundary.
- Make helpers enforce real invariants: Don’t write permissive utilities that let invalid data pass (e.g., stripping plural suffixes without validating required CLDR categories).
- Assert behavior, not incidental internals: Don’t write tests that tightly couple to log payload shape/field names unless you truly need that contract; rely on existing regression coverage for functional paths.
Example pattern (isolated smoke test)
const smokeHome = mkdtempSync(join(tmpdir(), "app-smoke-"));
const smokeEnv = {
...process.env,
HOME: smokeHome,
USERPROFILE: smokeHome,
APP_DIR: join(smokeHome, ".app"),
APP_DATA_DIR: join(smokeHome, "data"),
APP_PORT: String(await findFreePort()),
};
// start the real binary and probe health using only smokeEnv