test-triage

Test triage

Use this skill when you are asked to:

• Fix a failing test (local or CI).
• Investigate a hanging test run (“tests pass but the process never exits”).
• Identify what’s keeping Node alive (timers, sockets, handles).

Principles

1. Logs first: capture the failing command + error output before proposing changes.
2. Minimize the reproduction: run the smallest scope that reproduces the failure.
3. Fix the root cause (common culprits: long timers without .unref(), open sockets, background watchers).

Canonical workflows

Backend test runs

Use the wrapper script to run a targeted backend test scope:

• scripts/run-backend-tests.mjs

Default is unit tests (fast). Use --scope integration or --scope all when required.

“Node won’t exit” / hanging tests

Preferred workflow:

1. Re-run the smallest test scope.
2. If the process hangs, run the hang-diagnose wrapper:
   • scripts/diagnose-backend-hang.mjs
3. If you confirm a long-lived timer is the culprit, apply the repo rule:
   • Any long setTimeout / setInterval must use .unref() unless explicitly required to keep the process alive.

Last reviewed: 2026-01-15