feat: Adds better debugging support

[scalvert]

Better debugging for bin-tester: zero-config inspector + replay

• Enables stepping into the bin under test (execa child process) with Node’s inspector.
• Zero code changes needed: toggle with an env var.
• Dynamic ports avoid conflicts; attach from IDE or DevTools.

How to try it

• Zero-change debugging (attach without breaking)

BIN_TESTER_DEBUG=attach pnpm test:watch

Then attach your debugger:

• VS Code: “Attach to Node Process”

• DevTools: chrome://inspect → “Open dedicated DevTools for Node”

• Break on the first line

BIN_TESTER_DEBUG=1 pnpm test:watch
# or
BIN_TESTER_DEBUG=true pnpm test:watch

One-off in test code

import { createBinTester } from '@scalvert/bin-tester';

const { setupProject, runBinDebug } = createBinTester({
  binPath: 'node_modules/.bin/your-cli'
});

await setupProject();
await runBinDebug({});

Replay the last run (with debugging)

After tests run, you’ll see:

Replay with: bin-tester replay '/absolute/path/to/fixture/.bin-tester/last-run.json'

Run:

bin-tester replay '/absolute/path/to/fixture' --inspect
# or
bin-tester replay '/absolute/path/to/fixture' --inspect-brk --stdio inherit

Notes

• Parent tests and the bin process are separate sessions. Attach to the child to step into bin code.
• To see the “Debugger listening …” URL, inherit stdio (e.g., --stdio inherit for replay).

[Copilot]

Pull Request Overview

This PR adds comprehensive debugging support for bin-tester, enabling developers to debug the bins they're testing with Node's inspector. Key features include zero-config debugging via environment variables, replay functionality for re-running previous invocations, and a CLI tool for enhanced workflow.

• Zero-config debugging using BIN_TESTER_DEBUG environment variable to attach inspector to child processes
• Replay system that persists execution artifacts and allows re-running with debugging capabilities
• New CLI tool for replaying and inspecting previous test runs

Reviewed Changes

Copilot reviewed 10 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/index-test.ts	Adds comprehensive test coverage for debugging features, replay functionality, and environment variable behaviors
tests/fixtures/print-exec-argv.js	Test fixture that outputs process.execArgv for validating inspector flags
src/replay.ts	Core replay functionality for reading and re-executing persisted run artifacts
src/create-bin-tester.ts	Enhanced runBin with debug support, artifact persistence, and new runBinDebug method
src/cli.ts	New CLI tool for replay and info commands with inspector options
package.json	Updated build config, added CLI binary, new dependency, and Node version requirement
eslint.config.js	Disabled unicorn rule for top-level await
README.md	Comprehensive documentation for debugging and replay features
CHANGELOG.md	Cleaned up duplicate changelog entries
.github/workflows/ci-build.yml	Updated CI to test only Node 22 and 24

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Console.log should not be used in library code as it creates unwanted output during tests and library usage. Consider using a debug utility or making this logging configurable.

[Copilot]

Modifying process.env in runBinDebug creates a race condition in concurrent test environments. The environment variable could be modified by another test between setting and unsetting it.

Suggested change

	const previous = process.env.BIN_TESTER_DEBUG;
	if (!previous) {
	process.env.BIN_TESTER_DEBUG = 'attach';
	}
	const result = runBin(...args);
	if (!previous) {
	delete process.env.BIN_TESTER_DEBUG;
	}
	return result;
	// Find if the last argument is an execa.Options object
	let options: execa.Options<string> | undefined;
	if (args.length > 0 && typeof args[args.length - 1] === 'object' && !Array.isArray(args[args.length - 1])) {
	options = args[args.length - 1] as execa.Options<string>;
	}
	// Clone the options and its env, or create new if not present
	const newOptions: execa.Options<string> = {
	...(options || {}),
	env: {
	...(options && options.env ? options.env : process.env),
	BIN_TESTER_DEBUG: 'attach',
	},
	};
	let newArgs: RunBinArgs;
	if (options) {
	// Replace the last argument with the new options
	newArgs = [...args.slice(0, -1), newOptions] as RunBinArgs;
	} else {
	// Add the new options as the last argument
	newArgs = [...args, newOptions] as RunBinArgs;
	}
	return runBin(...newArgs);

[Copilot]

Requiring Node >=22 is a breaking change that should be documented more prominently. Many projects still use Node 18 or 20, and this requirement significantly limits adoption.

Suggested change

	"node": ">=22"
	"node": "^18.0.0 || ^20.0.0 || >=22.0.0"