Skip to content

Commit 9f1a113

Browse files
nicojsnicojs
committed
Replace old api docs with the new api using jest instance.
1 parent 65fe53f commit 9f1a113

File tree

1 file changed

+60
-97
lines changed

1 file changed

+60
-97
lines changed

‎docs/ProgrammaticApi.md‎

Lines changed: 60 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -14,91 +14,61 @@ This page documents Jest's programmable API that can be used to run jest from `n
1414
## Simple example
1515

1616
```js
17-
import jest from 'jest';
17+
import {createJest} from 'jest';
1818

19-
const {globalConfig, configs} = await jest.readConfigs(process.argv, ['.']);
20-
const {result} = await jest.runCore(globalConfig, configs);
19+
const jest = await createJest();
20+
jest.globalConfig = {
21+
collectCoverage: false,
22+
watch: false,
23+
...jest.globalConfig,
24+
};
25+
const {results} = await jest.run();
2126
console.log(`run success, ${result.numPassedTests} passed tests.`);
2227
```
2328

24-
This example runs Jest as the normal Jest command line interface (CLI) would.
25-
2629
## Programmatic API reference
2730

28-
### `getVersion` \[function]
31+
### `createJest(args: Partial<Config.Argv> = {}, projectPath = ['.']): Promise<Jest>` \[function]
2932

30-
Get the version number from the imported Jest.
33+
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.
3134

32-
Example:
35+
Examples:
3336

3437
```js
35-
import {getVersion} from 'jest';
36-
console.log(`jest version: ${getVersion()}`);
37-
```
38+
import {createJest} from 'jest';
3839

39-
### `readConfigs` \[function]
40-
41-
Async function that reads the config for a given jest project, as well as its [projects](./Configuration.md#projects-arraystring--projectconfig). If no `projects`, were configured, the current project will be provided as project config.
40+
const jest = await createJest();
41+
const jest2 = await createJest({config: 'jest.alternative.config.js'});
42+
```
4243

43-
It takes in in an array of command line arguments (for example, `process.argv`) and an array locations to search for config.
44+
### `jest.globalConfig` \[Readonly\<GlobalConfig>]
4445

45-
The configs that are returned are readonly and cannot be changed in-place. However, they can be used as a base to create new config objects from (see [Advanced use cases](#advanced-use-cases))
46+
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.
4647

4748
Example:
4849

4950
```js
50-
import {readConfigs} from 'jest';
51-
const {globalConfig, configs, hasDeprecationWarnings} = await readConfigs(
52-
process.argv,
53-
['.'],
54-
);
55-
56-
if (hasDeprecationWarnings) {
57-
console.warn('Deprecation warnings found!');
58-
}
59-
60-
console.log(`Global config: ${JSON.stringify(globalConfig, null, 2)}`);
61-
console.log(`Project specific configs: ${JSON.stringify(configs, null, 2)}`);
62-
```
63-
64-
### `readInitialOptions` \[function]
65-
66-
Async function that reads the jest configuration without reading its [projects](./Configuration.md#projects-arraystring--projectconfig), resolving its [preset](./Configuration.md#preset-string), filling in the default values or validating the options.
67-
68-
```js
69-
import {readInitialOptions} from 'jest';
70-
const {config, configPath} = await readInitialOptions();
71-
72-
console.log(
73-
`Read options from ${configPath}: ${JSON.stringify(config, null, 2)}`,
74-
);
51+
jest.globalConfig = {
52+
...jest.globalConfig,
53+
collectCoverage: false,
54+
watch: false,
55+
};
7556
```
7657

77-
### `runCLI` \[function]
78-
79-
Async function that mimics the CLI.
58+
### `jest.projectConfigs` \[Readonly\<ProjectConfig>\[]]
8059

81-
It takes in in an array of command line arguments (for example, `process.argv`) and an array locations to search for config.
60+
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.
8261

8362
```js
84-
import {runCLI} from 'jest';
85-
86-
const {results, globalConfig} = await runCLI(process.argv, ['.']);
87-
console.log(`run success, ${result.numPassedTests} passed tests.`);
63+
jest.projectConfigs = jest.projectConfigs.map(config => ({
64+
...config,
65+
setupFiles: ['custom-setup.js', ...config.setupFiles],
66+
}));
8867
```
8968

90-
### `runCore` \[function]
91-
92-
Async function that runs Jest either in watch mode or as a one-off. This is a lower-level API than `runCLI`.
69+
### `jest.run` \[function]
9370

94-
```js
95-
import {readConfigs, runCore} from 'jest';
96-
const {globalConfig, configs} = await readConfigs(process.argv, [
97-
process.cwd(),
98-
]);
99-
const {results} = await runCore(globalConfig, configs);
100-
console.log(results);
101-
```
71+
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.
10272

10373
## Advanced use cases
10474

@@ -109,54 +79,47 @@ These are more advanced use cases that demonstrate the power of the api.
10979
You can use `readInitialOptions` in combination with `runCLI` to run jest using the local config, while forcing some options. We're also always focussing our tests on the `foo.js` file.
11080

11181
```js
112-
import {readInitialOptions, runCLI} from 'jest';
113-
114-
const {config} = await readInitialOptions();
115-
116-
// Override initial options
117-
config.collectCoverage = false;
118-
config.reporters = [];
119-
config.verbose = false;
120-
config.testResultsProcessor = undefined;
121-
122-
// Only run tests related to foo.js
123-
const focussedFile = 'foo.js';
124-
const {results} = runCLI(
125-
{
126-
$0: 'my-custom-jest-script',
127-
_: [focussedFile],
82+
import {createJest} from 'jest';
83+
const jest = await createJest();
84+
85+
// Override global options
86+
jest.globalConfig = {
87+
...jest.globalConfig,
88+
collectCoverage: false,
89+
reporters: [],
90+
testResultsProcessor: undefined,
91+
watch: false,
92+
testPathPattern: 'my-test.spec.js',
93+
};
12894

129-
// Provide `findRelatedTests`
130-
findRelatedTests: true,
95+
// Override project options
96+
jest.projectConfigs = jest.projectConfigs.map(config => ({
97+
...config,
98+
setupFiles: ['custom-setup.js', ...config.setupFiles],
99+
}));
131100

132-
// Pass the initial options
133-
config: JSON.stringify(config),
134-
},
135-
['.'],
136-
);
137-
console.log(JSON.stringify(results));
101+
// Run
102+
const {results} = await jest.run();
103+
console.log(`run success, ${results.numPassedTests} passed tests.`);
138104
```
139105

140106
### Override options based on the configured options
141107

142108
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.
143109

144-
For that to work, the initial options is not enough, because the configured preset might override the test environment.
145-
146110
```js
147-
import {readConfigs, runCore} from 'jest';
111+
import {createJest} from 'jest';
148112

149-
// Run while overriding _some_ options
150-
const {globalConfig, configs} = await readConfigs(process.argv, [
151-
process.cwd(),
152-
]);
113+
const jest = await createJest();
153114

154-
const projectConfig = {
155-
...configs[0],
156-
// Change the test environment based on the configured test environment
157-
testEnvironment: overrideTestEnvironment(configs[0].testEnvironment),
158-
};
115+
jest.projectConfigs = [
116+
{
117+
...jest.projectConfigs[0],
118+
// Change the test environment based on the configured test environment
119+
testEnvironment: overrideTestEnvironment(configs[0].testEnvironment),
120+
},
121+
];
159122

160-
const {results} = await runCore(globalConfig, [projectConfig]);
123+
const {results} = await jest.run();
161124
console.log(results);
162125
```

0 commit comments

Comments
 (0)