fix(jest): escape parentheses and brackets in test file paths

[jasonwbarnett]

Summary

• Escape parentheses and brackets in test file paths before passing them to Jest
• Add test case for Next.js App Router style paths with special characters

Fixes #416

Problem

Jest interprets CLI arguments as regex patterns. When paths containing (main) or [catalogId] are passed to Jest, these characters are interpreted as regex metacharacters instead of literal characters, causing Jest to fail to match any test files.

This commonly affects Next.js App Router projects which use:

• (folderName) for route groups
• [param] for dynamic route segments

Solution

Added escapeJestPathPattern() function that escapes parentheses and brackets in file paths:

• src/app/(main)/test.tsx becomes src/app/\(main\)/test.tsx
• src/app/[id]/test.tsx becomes src/app/\[id\]/test.tsx

Other regex metacharacters (like dots) are intentionally not escaped because they work fine in practice and escaping them would break existing behavior.

Test plan

• Added unit test TestJestCommandNameAndArgs_WithSpecialCharactersInPath verifying correct escaping
• Existing TestJestCommandNameAndArgs_* tests continue to pass
• Manual verification that escaped paths match correctly in Jest

🤖 Generated with Claude Code

[jasonwbarnett]

Alternative Approach: --runTestsByPath

Jest has a CLI flag --runTestsByPath that treats arguments as literal file paths instead of regex patterns. This could be a cleaner alternative to escaping:

// Current default
j.TestCommand = "npx jest {{testExamples}} --json --testLocationInResults --outputFile {{resultPath}}"

// With --runTestsByPath
j.TestCommand = "npx jest --runTestsByPath {{testExamples}} --json --testLocationInResults --outputFile {{resultPath}}"

Trade-offs

Approach	Pros	Cons
Escaping (this PR)	Works with existing regex behavior, backwards compatible	More complex code, might miss edge cases
--runTestsByPath	Simpler, cleaner, better performance per Jest docs	Could be a breaking change if anyone relies on regex matching in paths

The --runTestsByPath approach is recommended by Jest for CI pipelines. Worth considering as an alternative or future improvement.

[malclocke]

@jasonwbarnett thanks for this PR, and for logging the related issue 🙇

At first glance it looks like the --runTestsByPath approach might be a more robust solution, and would avoid us having to potentially revisit the implementation shown here to add more regex characters to escape in future.

I need to double check but I believe we will only ever pass file names to the TestCommand for Jest, whereas I think only the RetryTestCommand receives regex arguments.

I'll do some experimenting and get back to you.

[jasonwbarnett]

Hey @malclocke, just wanted to follow up on this. It's been about 3 weeks since your last update - totally understand if the holidays got in the way (we just got back from Christmas and New Years ourselves).

Any updates on your experiments with the --runTestsByPath approach? Happy to pivot to that if it turns out to be more robust. Let me know if there's anything I can help with on my end.

[niceking]

Hey @jasonwbarnett! Yeah the team's still mostly on holidays and ramping back up. We'll try look at this this month, but for now you could compile your own bktec with these changes and run with that until we merge it to main?

[nprizal]

Hi @jasonwbarnett , I agree that the --runTestsByPath is the better solution for this. As @malclocke said, we always pass file names to the Jest command, and use regex only for retry which use different command. So adding --runTestsByPath CLI option to the TestCommand should not break the existing behavior. I've tested it locally and on our Jest suite it works correctly.

Also according to Jest documentation, the --runTestsByPath is more optimized when provided with multiple patterns which will be better for bktec as we are passing list of test files to Jest.

The default regex matching works fine on small runs, but becomes slow if provided with multiple patterns and/or against a lot of tests. This option replaces the regex matching logic and by that optimizes the time it takes Jest to filter specific test files.

Do you want to update the PR with the --runTestsByPath approach?

[jasonwbarnett]

Hello 👋

I can pivot to use the --runTestsByPath approach. It wasn't clear to me based on @malclocke whether or not any existing code depended on being able to pass regular expressions. I'll move forward assuming we're all good. I should have something posted by end of week.

[nprizal]

Hello @jasonwbarnett! Yes we are all good. We pass test name as regex when retrying failed test, but this command is configured under a separate config RetryCommand. So adding --runTestsByPath to the TestCommand won't cause any problems.