Add testNamePattern to Project.Config

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Features
 
+- `[jest-runner, jest-circus, jest-jasmine2, jest-types]` Added support for `testNamePattern` in the `Project.Config`. This enables custom Jest runners to specify which test cases are ran in each test file (by setting the `testNamePattern` config on each `JestTest.context.config`). The `GlobalConfig.testNamePattern` was also exposed to custom Jest runners.
+
 ### Fixes
 
 ### Chore & Maintenance
@@ -76,8 +78,7 @@
 
 - `[expect]` Match symbols and bigints in `any()` ([#10223](https://github.com/facebook/jest/pull/10223))
 - `[jest-changed-files]` Use `git diff` instead of `git log` for `--changedSince` ([#10155](https://github.com/facebook/jest/pull/10155))
-- `[jest-console]` Add missing `console.timeLog` for compatibility with Node ([#10209](https://github.com/facebook/jest/pull/10209))
-- `[jest-haste-map]` Check `find` binary supports the `-iname` parameter ([#10308](https://github.com/facebook/jest/pull/10308))
+- `[jest-console]` Add missing console.timeLog for compatability with Node ([#10209](https://github.com/facebook/jest/pull/10209))
 - `[jest-snapshot]` Strip added indentation for inline error snapshots ([#10217](https://github.com/facebook/jest/pull/10217))
 
 ### Chore & Maintenance
@@ -88,7 +89,8 @@
 - `[jest-jasmine2]` Remove usage of `Function` type ([#10216](https://github.com/facebook/jest/pull/10216))
 - `[jest-resolve]` Improve types ([#10239](https://github.com/facebook/jest/pull/10239))
 - `[docs]` Clarify the [`jest.requireActual(moduleName)`](https://jestjs.io/docs/en/jest-object#jestrequireactualmodulename) example
-- `[jest-types]` Refine typings of `coverageReporters` ([#10275](https://github.com/facebook/jest/pull/10275))
+
+### Performance
 
 ## 26.1.0
 

packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapterInit.ts

@@ -82,7 +82,7 @@ export const initialize = async ({
       timeout?: number,
     ) => {
       // For concurrent tests we first run the function that returns promise, and then register a
-      // nomral test that will be waiting on the returned promise (when we start the test, the promise
+      // normal test that will be waiting on the returned promise (when we start the test, the promise
       // will already be in the process of execution).
       // Unfortunately at this stage there's no way to know if there are any `.only` tests in the suite
       // that will result in this test to be skipped, so we'll be executing the promise function anyway,
@@ -120,7 +120,7 @@ export const initialize = async ({
   await dispatch({
     name: 'setup',
     parentProcess,
-    testNamePattern: globalConfig.testNamePattern,
+    testNamePattern: config.testNamePattern ?? globalConfig.testNamePattern,
   });
 
   if (config.testLocationInResults) {

packages/jest-jasmine2/src/index.ts

@@ -175,8 +175,13 @@ async function jasmine2(
         globalConfig.enabledTestsMap[spec.result.testPath];
       return (suiteMap && suiteMap[spec.result.fullName]) || false;
     };
-  } else if (globalConfig.testNamePattern) {
-    const testNameRegex = new RegExp(globalConfig.testNamePattern, 'i');
+  }
+
+  const testNamePattern =
+    config.testNamePattern ?? globalConfig.testNamePattern;
+
+  if (testNamePattern) {
+    const testNameRegex = new RegExp(testNamePattern, 'i');
     env.specFilter = (spec: Spec) => testNameRegex.test(spec.getFullName());
   }
 

packages/jest-runner/README.md

@@ -0,0 +1,79 @@
+# jest-runner
+
+`jest-runner` is a package that can be used to create custom Jest runners. Runners are used to control which tests run.
+
+```js
+const TestRunner = require('jest-runner');
+
+class myCustomJestRunner extends TestRunner {
+  constructor(globalConfig, context) {
+    super(globalConfig, context);
+  }
+
+  async runTests(tests, watcher, onStart, onResult, onFailure, options) {
+    const filteredTests = tests.filter(test => test.path.includes('e2e'));
+
+    super(filteredTests, watcher, onStart, onResult, onFailure, options);
+  }
+}
+```
+
+`jest-runner` can:
+
+- Intercept test collections before they are ran.
+- Modify the Jest-Config per test file. This includes controlling the `testNamePattern` of each test file.
+
+## Installation
+
+```sh
+# with yarn
+$ yarn add jest-runner
+# with npm
+$ npm install jest-runner
+```
+
+<!-- ⚠️ TODO ⚠️
+
+- Add config example.
+
+## Usage
+
+```js
+const TestRunner = require('jest-runner');
+
+const docblock = extract(code);
+console.log(docblock); // "/**\n * Everything is awesome!\n * \n * @everything is:awesome\n * @flow\n */"
+
+const stripped = strip(code);
+console.log(stripped); // "export const everything = Object.create(null);\n export default function isAwesome(something) {\n return something === everything;\n }"
+
+const pragmas = parse(docblock);
+console.log(pragmas); // { everything: "is:awesome", flow: "" }
+
+const parsed = parseWithComments(docblock);
+console.log(parsed); // { comments: "Everything is awesome!", pragmas: { everything: "is:awesome", flow: "" } }
+
+console.log(print({pragmas, comments: 'hi!'})); // /**\n * hi!\n *\n * @everything is:awesome\n * @flow\n */;
+```
+
+## API Documentation
+
+### `extract(contents: string): string`
+
+Extracts a docblock from some file contents. Returns the docblock contained in `contents`. If `contents` did not contain a docblock, it will return the empty string (`""`).
+
+### `strip(contents: string): string`
+
+Strips the top docblock from a file and return the result. If a file does not have a docblock at the top, then return the file unchanged.
+
+### `parse(docblock: string): {[key: string]: string | string[] }`
+
+Parses the pragmas in a docblock string into an object whose keys are the pragma tags and whose values are the arguments to those pragmas.
+
+### `parseWithComments(docblock: string): { comments: string, pragmas: {[key: string]: string | string[]} }`
+
+Similar to `parse` except this method also returns the comments from the docblock. Useful when used with `print()`.
+
+### `print({ comments?: string, pragmas?: {[key: string]: string | string[]} }): string`
+
+Prints an object of key-value pairs back into a docblock. If `comments` are provided, they will be positioned on the top of the docblock. -->

packages/jest-types/src/Config.ts

@@ -354,6 +354,7 @@ export type ProjectConfig = {
   testEnvironment: string;
   testEnvironmentOptions: Record<string, any>;
   testMatch: Array<Glob>;
+  testNamePattern?: string;
   testLocationInResults: boolean;
   testPathIgnorePatterns: Array<string>;
   testRegex: Array<string | RegExp>;

website/versioned_docs/version-26.0/Configuration.md

@@ -978,6 +978,14 @@ See the [micromatch](https://github.com/jonschlinkert/micromatch) package for de
 
 See also [`testRegex` [string | array\<string>]](#testregex-string--arraystring), but note that you cannot specify both options.
 
+### `testNamePattern` [string]
+
+Default: `undefined`
+
+Run only tests with a name that matches the regex. For example, suppose you want to run only tests related to authorization which will have names like "GET /api/posts with auth", then you can use jest -t=auth.
+
+Note: The regex is matched against the full name, which is a combination of the test name and all its surrounding describe blocks.
+
 ### `testPathIgnorePatterns` [array\<string>]
 
 Default: `["/node_modules/"]`