feat(jest-circus): support literal string match in testNamePattern with "@:" prefix

[kweonsikyung]

Summary

The existing -t / --testNamePattern option in Jest filters test names using regular expressions. This becomes inconvenient when test names include regex-special characters like () or *, which must be manually escaped to run a specific test.

This PR introduces support for literal string matching by allowing a "@:" prefix in testNamePattern. When this prefix is used, the input string is treated as a plain literal rather than a regex. This improves the developer experience by allowing test names to be copied and pasted directly into the CLI without needing to escape special characters.

And, this PR resolves issue #15574

Examples:

# Before (escaping required)
node ./jest.js -t "check value \\(important\\)"

# After (no escaping necessary)
node ./jest.js -t "@:check value (important)"

Test plan

An end-to-end test suite was added under e2e/literal-pattern to verify the new literal matching behavior. The tests include:

• literal match: exact string match
• check * literal asterisk: includes a * character
• special (characters): includes parentheses

The following commands were run to confirm expected behavior:

node ./packages/jest/bin/jest.js --config=e2e/literal-pattern/jest.config.js -t "literal match"
node ./packages/jest/bin/jest.js --config=e2e/literal-pattern/jest.config.js -t "@:check * literal asterisk"
node ./packages/jest/bin/jest.js --config=e2e/literal-pattern/jest.config.js -t "@:special (characters)"

All tests passed, and the literal filtering behavior worked as intended. Regex-based filtering remains unaffected and continues to function normally.

[linux-foundation-easycla[bot]]

The committers listed above are authorized under a signed CLA.

• :white_check_mark: login: kweonsikyung / name: Sikyung Kweon (4b0d8924ef99c6bee06f9d999e1d2ba623345862, 975daa3328b997b50cb733162471c84b638bcb84, 3207280c35c7938462a62779a8b40e8903c25fd8, 358cffae29c9a685ff5b03f9e1cb529cc8cdd574)

[netlify[bot]]

✅ Deploy Preview for jestjs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	4b0d8924ef99c6bee06f9d999e1d2ba623345862
🔍 Latest deploy log	https://app.netlify.com/projects/jestjs/deploys/684891bc8d8c82000865e0bd
😎 Deploy Preview	https://deploy-preview-15667--jestjs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new[bot]]

Open in StackBlitz

babel-jest

npm i https://pkg.pr.new/babel-jest@15667

babel-plugin-jest-hoist

npm i https://pkg.pr.new/babel-plugin-jest-hoist@15667

babel-preset-jest

npm i https://pkg.pr.new/babel-preset-jest@15667

create-jest

npm i https://pkg.pr.new/create-jest@15667

@jest/diff-sequences

npm i https://pkg.pr.new/@jest/diff-sequences@15667

expect

npm i https://pkg.pr.new/expect@15667

@jest/expect-utils

npm i https://pkg.pr.new/@jest/expect-utils@15667

jest

npm i https://pkg.pr.new/jest@15667

jest-changed-files

npm i https://pkg.pr.new/jest-changed-files@15667

jest-circus

npm i https://pkg.pr.new/jest-circus@15667

jest-cli

npm i https://pkg.pr.new/jest-cli@15667

jest-config

npm i https://pkg.pr.new/jest-config@15667

@jest/console

npm i https://pkg.pr.new/@jest/console@15667

@jest/core

npm i https://pkg.pr.new/@jest/core@15667

@jest/create-cache-key-function

npm i https://pkg.pr.new/@jest/create-cache-key-function@15667

jest-diff

npm i https://pkg.pr.new/jest-diff@15667

jest-docblock

npm i https://pkg.pr.new/jest-docblock@15667

jest-each

npm i https://pkg.pr.new/jest-each@15667

@jest/environment

npm i https://pkg.pr.new/@jest/environment@15667

jest-environment-jsdom

npm i https://pkg.pr.new/jest-environment-jsdom@15667

@jest/environment-jsdom-abstract

npm i https://pkg.pr.new/@jest/environment-jsdom-abstract@15667

jest-environment-node

npm i https://pkg.pr.new/jest-environment-node@15667

@jest/expect

npm i https://pkg.pr.new/@jest/expect@15667

@jest/fake-timers

npm i https://pkg.pr.new/@jest/fake-timers@15667

@jest/get-type

npm i https://pkg.pr.new/@jest/get-type@15667

@jest/globals

npm i https://pkg.pr.new/@jest/globals@15667

jest-haste-map

npm i https://pkg.pr.new/jest-haste-map@15667

jest-jasmine2

npm i https://pkg.pr.new/jest-jasmine2@15667

jest-leak-detector

npm i https://pkg.pr.new/jest-leak-detector@15667

jest-matcher-utils

npm i https://pkg.pr.new/jest-matcher-utils@15667

jest-message-util

npm i https://pkg.pr.new/jest-message-util@15667

jest-mock

npm i https://pkg.pr.new/jest-mock@15667

@jest/pattern

npm i https://pkg.pr.new/@jest/pattern@15667

jest-phabricator

npm i https://pkg.pr.new/jest-phabricator@15667

jest-regex-util

npm i https://pkg.pr.new/jest-regex-util@15667

jest-repl

npm i https://pkg.pr.new/jest-repl@15667

@jest/reporters

npm i https://pkg.pr.new/@jest/reporters@15667

jest-resolve

npm i https://pkg.pr.new/jest-resolve@15667

jest-resolve-dependencies

npm i https://pkg.pr.new/jest-resolve-dependencies@15667

jest-runner

npm i https://pkg.pr.new/jest-runner@15667

jest-runtime

npm i https://pkg.pr.new/jest-runtime@15667

@jest/schemas

npm i https://pkg.pr.new/@jest/schemas@15667

jest-snapshot

npm i https://pkg.pr.new/jest-snapshot@15667

@jest/snapshot-utils

npm i https://pkg.pr.new/@jest/snapshot-utils@15667

@jest/source-map

npm i https://pkg.pr.new/@jest/source-map@15667

@jest/test-result

npm i https://pkg.pr.new/@jest/test-result@15667

@jest/test-sequencer

npm i https://pkg.pr.new/@jest/test-sequencer@15667

@jest/transform

npm i https://pkg.pr.new/@jest/transform@15667

@jest/types

npm i https://pkg.pr.new/@jest/types@15667

jest-util

npm i https://pkg.pr.new/jest-util@15667

jest-validate

npm i https://pkg.pr.new/jest-validate@15667

jest-watcher

npm i https://pkg.pr.new/jest-watcher@15667

jest-worker

npm i https://pkg.pr.new/jest-worker@15667

pretty-format

npm i https://pkg.pr.new/pretty-format@15667

commit: 4b0d892

[cpojer]

I'm not interested in supporting magic syntax like this. If we want a direct string match, it should be without any magic, and just the quoted string.

[kweonsikyung]

I'm not interested in supporting magic syntax like this. If we want a direct string match, it should be without any magic, and just the quoted string.

@cpojer Hi! I understand that quoting a test name without using -t already performs a literal match, but I believe there's still a strong case for supporting literal matching explicitly within the -t option.

According to the official documentation, --testNamePattern (or -t) is the standard and documented entry point for filtering tests by name:

Run tests that match this spec name (match against the name in describe or test, basically). jest -t name-of-spec

In practice, users overwhelmingly rely on -t for test filtering — both in local workflows and especially in CI environments. Meanwhile, invoking Jest with a quoted string like jest "some test name" is undocumented, nonstandard, and rarely used or known.

As a result, -t is effectively the official and only entry point for name-based filtering. Given this, it’s important that -t itself provides an explicit way to distinguish between regex-based and literal string matching. Introducing a clear and opt-in prefix for literal matching (like @:) serves that need without breaking backward compatibility or existing behavior.

This approach acknowledges how people already use Jest, and it keeps filtering behavior discoverable, explicit, and robust within the CLI’s primary filtering interface.

I would sincerely appreciate it if you could kindly reconsider this proposal. Thank you.

[cpojer]

Maybe we should update the docs, then.

[github-actions[bot]]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.