feat(Programmatic API): Add programmatic API

docs/ProgrammaticApi.md

@@ -0,0 +1,125 @@
+---
+id: programmatic-api
+title: Programmatic API
+---
+
+:::caution
+
+The programmatic API is currently **experimental**. It is useful for advanced use cases only. You normally don't need to use it if you just want to run your tests.
+
+:::
+
+This page documents Jest's programmable API that can be used to run jest from `node`. TypeScript types are provided.
+
+## Simple example
+
+```js
+import {createJest} from 'jest';
+
+const jest = await createJest();
+jest.globalConfig = {
+  collectCoverage: false,
+  watch: false,
+  ...jest.globalConfig,
+};
+const {results} = await jest.run();
+console.log(`run success, ${result.numPassedTests} passed tests.`);
+```
+
+## Programmatic API reference
+
+### `createJest(args: Partial<Config.Argv> = {}, projectPath = ['.']): Promise<Jest>` \[function]
+
+Create a Jest instance asynchronously. You can provide command line arguments (for example, `process.argv`) as first argument and a list of custom [projects](./Configuration.md#projects-arraystring--projectconfig) as the second argument. If no `projects`, were configured, the current project will be provided as project config.
+
+Examples:
+
+```js
+import {createJest} from 'jest';
+
+const jest = await createJest();
+const jest2 = await createJest({config: 'jest.alternative.config.js'});
+```
+
+### `jest.globalConfig` \[Readonly\<GlobalConfig>]
+
+The global config associated with this jest instance. It is `readonly`, so it cannot be changed in-place. In order to change it, you will need to create a new object.
+
+Example:
+
+```js
+jest.globalConfig = {
+  ...jest.globalConfig,
+  collectCoverage: false,
+  watch: false,
+};
+```
+
+### `jest.projectConfigs` \[Readonly\<ProjectConfig>\[]]
+
+A list of project configurations associated with this jest instance. They are `readonly`, so it cannot be changed in-place. In order to change it, you will need to create a new object.
+
+```js
+jest.projectConfigs = jest.projectConfigs.map(config => ({
+  ...config,
+  setupFiles: ['custom-setup.js', ...config.setupFiles],
+}));
+```
+
+### `jest.run` \[function]
+
+Async function that performs the run. It returns a promise that resolves in a `JestRunResult` object. This object has a `results` property that contains the actual results.
+
+## Advanced use cases
+
+These are more advanced use cases that demonstrate the power of the api.
+
+### Overriding config options
+
+You can use `createJest` to create a Jest instance, and alter some of the options using `globalConfig` adn `projectConfigs`.
+
+```js
+import {createJest} from 'jest';
+const jest = await createJest();
+
+// Override global options
+jest.globalConfig = {
+  ...jest.globalConfig,
+  collectCoverage: false,
+  reporters: [],
+  testResultsProcessor: undefined,
+  watch: false,
+  testPathPattern: 'my-test.spec.js',
+};
+
+// Override project options
+jest.projectConfigs = jest.projectConfigs.map(config => ({
+  ...config,
+  setupFiles: ['custom-setup.js', ...config.setupFiles],
+}));
+
+// Run
+const {results} = await jest.run();
+console.log(`run success, ${results.numPassedTests} passed tests.`);
+```
+
+### Override options based on the configured options
+
+You might want to override options based on other options. For example, you might want to provide your own version of the `jsdom` or `node` test environment.
+
+```js
+import {createJest} from 'jest';
+
+const jest = await createJest();
+
+jest.projectConfigs = [
+  {
+    ...jest.projectConfigs[0],
+    // Change the test environment based on the configured test environment
+    testEnvironment: overrideTestEnvironment(configs[0].testEnvironment),
+  },
+];
+
+const {results} = await jest.run();
+console.log(results);
+```

e2e/__tests__/__snapshots__/runProgrammatically.test.ts.snap

@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`createJest run programmatically: stdout 1`] = `"run success, 1 passed tests."`;
+
+exports[`createJest run programmatically: summary 1`] = `
+"Test Suites: 1 passed, 1 total
+Tests:       1 passed, 1 total
+Snapshots:   0 total
+Time:        <<REPLACED>>
+Ran all test suites."
+`;

e2e/__tests__/__snapshots__/runProgrammaticallyMultipleProjects.test.ts.snap

@@ -1,6 +1,14 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`run programmatically with multiple projects: summary 1`] = `
+exports[`run jest programmatically with multiple projects: summary 1`] = `
+"Test Suites: 2 passed, 2 total
+Tests:       2 passed, 2 total
+Snapshots:   0 total
+Time:        <<REPLACED>>
+Ran all test suites in 2 projects."
+`;
+
+exports[`runCLI programmatically with multiple projects: summary 1`] = `
 "Test Suites: 2 passed, 2 total
 Tests:       2 passed, 2 total
 Snapshots:   0 total

e2e/__tests__/runProgrammatically.test.ts

@@ -6,7 +6,8 @@
  */
 
 import {resolve} from 'path';
-import {run} from '../Utils';
+import stripAnsi = require('strip-ansi');
+import {extractSummary, run} from '../Utils';
 
 const dir = resolve(__dirname, '..', 'run-programmatically');
 
@@ -19,3 +20,11 @@ test('run Jest programmatically esm', () => {
   const {stdout} = run('node index.js --version', dir);
   expect(stdout).toMatch(/\d{2}\.\d{1,2}\.\d{1,2}[-\S]*-dev$/);
 });
+
+test('createJest run programmatically', () => {
+  const {stderr, stdout} = run('node jest.mjs', dir);
+  const {summary} = extractSummary(stripAnsi(stderr));
+
+  expect(summary).toMatchSnapshot('summary');
+  expect(stdout).toMatchSnapshot('stdout');
+});

e2e/__tests__/runProgrammaticallyMultipleProjects.test.ts

@@ -11,7 +11,14 @@ import {extractSummary, run} from '../Utils';
 
 const dir = resolve(__dirname, '../run-programmatically-multiple-projects');
 
-test('run programmatically with multiple projects', () => {
+test('runCLI programmatically with multiple projects', () => {
+  const {stderr, exitCode} = run('node run-cli.js', dir);
+  const {summary} = extractSummary(stripAnsi(stderr));
+  expect(exitCode).toBe(0);
+  expect(summary).toMatchSnapshot('summary');
+});
+
+test('run jest programmatically with multiple projects', () => {
   const {stderr, exitCode} = run('node run-jest.js', dir);
   const {summary} = extractSummary(stripAnsi(stderr));
   expect(exitCode).toBe(0);

e2e/run-programmatically-multiple-projects/client/client.test.js

@@ -6,5 +6,7 @@
  */
 
 describe('client', () => {
-  it('should work', () => {});
+  it('should work', () => {
+    expect(typeof document).toBe('object');
+  });
 });

e2e/run-programmatically-multiple-projects/client/jest.config.json

@@ -0,0 +1,4 @@
+{
+  "testMatch": ["**/*.test.js"],
+  "testEnvironment": "jsdom"
+}

e2e/run-programmatically-multiple-projects/package.json

@@ -2,5 +2,11 @@
   "name": "runcli-multiple-projects",
   "version": "1.0.0",
   "dependencies": {},
-  "jest": {}
+  "jest": {
+    "maxWorkers": 1,
+    "projects": [
+      "<rootDir>/server",
+      "<rootDir>/client"
+    ]
+  }
 }

e2e/run-programmatically-multiple-projects/run-cli.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const {runCLI} = require('jest');
+
+const config = {
+  projects: [
+    {testEnvironment: 'jsdom', testMatch: ['<rootDir>/client/**/*.test.js']},
+    {testEnvironment: 'node', testMatch: ['<rootDir>/server/**/*.test.js']},
+  ],
+};
+
+runCLI({config: JSON.stringify(config)}, [process.cwd()])
+  .then(() =>
+    console.log('run-programmatically-cli-multiple-projects completed'),
+  )
+  .catch(err => {
+    console.error(err);
+    process.exitCode = 1;
+  });

e2e/run-programmatically-multiple-projects/run-jest.js

@@ -5,18 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const {runCLI} = require('@jest/core');
+const {createJest} = require('jest');
 
-const config = {
-  projects: [
-    {testMatch: ['<rootDir>/client/**/*.test.js']},
-    {testMatch: ['<rootDir>/server/**/*.test.js']},
-  ],
-};
+async function main() {
+  const jest = await createJest();
+  jest.globalConfig = {
+    collectCoverage: false,
+    watch: false,
+    ...jest.globalConfig,
+  };
+  await jest.run();
+  console.log('run-programmatically-core-multiple-projects completed');
+}
 
-runCLI({config: JSON.stringify(config)}, [process.cwd()])
-  .then(() => console.log('run-programmatically-mutiple-projects completed'))
-  .catch(err => {
-    console.error(err);
-    process.exitCode = 1;
-  });
+main().catch(err => {
+  console.error(err);
+  process.exitCode = 1;
+});

e2e/run-programmatically-multiple-projects/server/jest.config.json

@@ -0,0 +1,4 @@
+{
+  "testMatch": ["**/*.test.js"],
+  "testEnvironment": "node"
+}

e2e/run-programmatically-multiple-projects/server/server.test.js

@@ -6,5 +6,7 @@
  */
 
 describe('server', () => {
-  it('should work', () => {});
+  it('should work', () => {
+    expect(typeof document).toBe('undefined');
+  });
 });

e2e/run-programmatically/jest.mjs

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import {createJest} from 'jest';
+
+const jest = await createJest();
+jest.globalConfig = {
+  collectCoverage: false,
+  watch: false,
+  ...jest.globalConfig,
+};
+const {results} = await jest.run();
+console.log(`run success, ${results.numPassedTests} passed tests.`);

e2e/run-programmatically/src/app.spec.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/* eslint-disable no-undef */
+
+describe('jest-core', () => {
+  it('should run this test', () => {});
+});