isolated-test-processes

name	isolated-test-processes
description	Guide for writing side-effect-free tests that spawn child processes, especially Deno commands. Use when adding or reviewing tests that call Deno.Command, run deno check/test/run/task/install, generate temporary deno.json files, update goldens, write build artifacts, or otherwise risk changing deno.lock or files in the repository workspace.

Isolated Test Processes

Tests that spawn Deno can update the repository even when the test only means to verify behavior. Deno commands resolve dependencies and may refresh deno.lock metadata. Generated configs, output files, and golden updates can also leave workspace files behind if cleanup is not tied to failure paths.

Repo Map

Use @commonfabric/test-support/isolated-deno for nested Deno commands that need lockfile isolation.

For nested Deno checks that need a generated config:

import {
  runDenoCheckWithTemporaryConfig,
} from "@commonfabric/test-support/isolated-deno";

That helper keeps the generated Deno workspace config in the repository root, where Deno requires workspace members to be nested under the config directory. It points Deno at a temporary copy of deno.lock, so dependency metadata writes do not touch the real lockfile. It also removes the generated root config in a finally block.

For nested Deno commands that do not need a generated config:

import {
  runDenoCommandWithTemporaryLock,
} from "@commonfabric/test-support/isolated-deno";

Pass an argument builder and place the temporary lock path in the child Deno command's --lock flag.

Values

• A verification test must not change deno.lock or repository files.
• If a test needs mutable inputs or outputs, put them under Deno.makeTempDir() or an explicit test fixture copy.
• If a generated file must briefly live in the repository root for tool semantics, give it a unique dot-prefixed name and remove it in finally.
• If a test intentionally updates fixtures or goldens, gate the write behind an explicit environment variable such as UPDATE_GOLDENS=1.
• Treat Deno.Command(Deno.execPath()) as a side-effect boundary. The child Deno process does not inherit the parent test runner's lockfile flags.

Common Tells

Risky tests often contain Deno.Command(Deno.execPath()), deno check, deno task, deno install, generated deno.json files, generated build outputs, or direct writes to paths under the repository root.