From 1e350aebee2bf3bd5b134e189d5fe42227c8dcee Mon Sep 17 00:00:00 2001 From: Richard Osborne Date: Wed, 18 Feb 2026 17:22:21 +0100 Subject: [PATCH] docs(infra): document Jest/webpack test runner gotchas --- dev-docs/reference/COMMON-ISSUES.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/dev-docs/reference/COMMON-ISSUES.md b/dev-docs/reference/COMMON-ISSUES.md index ff11034..f50ddaa 100644 --- a/dev-docs/reference/COMMON-ISSUES.md +++ b/dev-docs/reference/COMMON-ISSUES.md @@ -412,3 +412,17 @@ Found a solution not listed here? Add it! 2. Follow the format: Symptom → Solutions 3. Include specific commands when helpful 4. Submit PR with your addition + +--- + +## Jest / Test Runner Hangs on Webpack Build + +**Symptom**: `npm run test:editor -- --testPathPattern=Foo` hangs indefinitely. + +**Root cause**: `scripts/test-editor.ts` runs a full webpack compile before Jest. Can appear hung but is just slow (30-90s). + +**Rules**: +- Always put test files in `tests/models/` not `tests/services/` (transform config only covers models/ path) +- Never use `npx jest` directly - Babel cannot parse TypeScript `type` keyword without the full transform setup +- Use `npm run test:editor` from root — it will eventually complete +- Never use heredoc (`cat << EOF`) in terminal commands — use printf or write_to_file instead