test: choose --test-timeout by Node major (per file on Node 22) - #271

Closes #267

What changes

On Node 22, --test-timeout limits each test file and sets no limit per test. On Node 24 and later it limits each test and not the file (nodejs/node#57672, first released in 24.0.0). The package scripts passed 30 s and 120 s as per-test limits, so on Node 22 the runner ended a file that ran longer, even when every test in it passed.

One correction to the issue text: on Node 22 the flag does not "also" limit the file. It limits only the file, and no test gets a limit from it.

• scripts/node-test.ts starts node --test with the --test-timeout value for the running Node major: the per-test limit on Node 24 and later, a file budget on Node 22. It exits with the runner's code and passes SIGINT and SIGTERM on to it.
• test:unit and test:integration in the four packages call it.

• test/scripts/node-test.test.ts (added to the root test script) runs fixture files with limits of a few seconds:
  • a file of five passing 500 ms tests, with a 2 s per-test limit, passes on every version;
  • a slow test is cancelled at the per-test limit on Node 24 and later, and on Node 22 its file is cancelled at the budget;
  • the script exits 0 on a pass, 1 on a failing test and 2 on an unknown kind of test, and after SIGTERM it ends with the runner's code within 15 s.
• docs/contributor/testing.md has a new section, "Test time limits": the two meanings, the budgets, the Node pull request, and what to delete when the Node floor moves to 24. docs/contributor/tooling.md names the script.
• The comments in packages/hardhat-kms/test/helpers/hardhat-cli.ts and tutorial-return-funds.test.ts match the new numbers.

On Node 22 a hung test is now reported as a cancelled file after up to 10 minutes, not as a failed test. The same tests run on Node 24 and 26, where the runner cancels the hung test by name at its limit.

Not in scope: the localstack, examples, live and coverage scripts and scripts/test-hardhat-versions.ts (CI runs the localstack, examples, coverage and Hardhat-versions jobs on Node 24; the live scripts run locally), and splitting test files.

Test plan

Ran locally on macOS:

• node --test test/scripts/node-test.test.ts on Node 22.13.0 (with NODE_OPTIONS='--import tsx'), 22.23.3, 24.16.0 and 26.0.0, and on 26.0.0 with the scripts/fail-on-deprecation.mjs preload: 10 of 10 pass on each.
• Four temporary edits to scripts/node-test.ts, each reverted, to check that the test fails:
  • the per-test limit on every version: fails on Node 22.13.0 (the passing file is cancelled);
  • > in place of >= in the version rule: fails on Node 24.16.0 (the slow test is no longer cancelled at 1 s);
  • no exit-code forwarding: fails on Node 24.16.0;
  • no signal forwarding: fails on Node 22.13.0 and 24.16.0.
• pnpm --filter @hardhat-kms/gcp run test:unit through the script on Node 22.13.0 (--import tsx) and 24.16.0: 93 of 93 pass on each.
• pnpm run test:unit for the four packages on Node 24.16.0 (the pre-push hook): passes.
• pnpm run check, pnpm run docs:check and knip on Node 24.16.0: pass.

Not run locally:

• The full pnpm test, and test:integration through the script on any version. The three CI legs (Node 22.13.0, 24.0.0, 26.0.0) run both.
• macOS and Windows CI (ci-all-os.yml). The script has not run on Windows.
• A hang probe in a real integration file (a test that never settles, to see the 600 s file budget end the file on Node 22). The slow-test fixture covers the same path with a 3 s budget.
• Ctrl-C in a terminal. SIGTERM forwarding has a test; SIGINT uses the same handler and has none.

🤖 Generated with Claude Code