Skip to content

Commit 1bd1a97

Browse files
huafuhuafu
committed
docs(config): completes the documentation about config
1 parent c07096a commit 1bd1a97

4 files changed

Lines changed: 311 additions & 4 deletions

File tree

‎docs/user/config/babelConfig.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Babel Config option
3+
---
4+
5+
TSJest by default does **NOT** use Babel. But you may want to use it, especially if your code rely on Babel plugins to make some transformations. TSJest can call the BabelJest processor once TypeScript has transformed the source into JavaScript.
6+
7+
The option is `babelConfig` and it works pretty much as the `tsConfig` option, except that it is disabled by default. Here is the possible values it can take:
8+
- `false`: the default, disables the use of Babel
9+
- `true`: enables Babel processing. TSJest will try to find a `.babelrc`, `.babelrc.js` file or a `babel` section in the `package.json` file of your project and use it as the config to pass to `babel-jest` processor
10+
- `{ ... }`: inline [Babel options](https://babeljs.io/docs/en/next/options). You can also set this to an empty object (`{}`) so that the default Babel config file is not used.
11+
12+
### Examples
13+
14+
#### Use default `babelrc` file:
15+
16+
<div class="row"><div class="col-md-6" markdown="block">
17+
```js
18+
// jest.config.js
19+
module.exports = {
20+
// [...]
21+
globals: {
22+
'ts-jest': {
23+
babelConfig: true
24+
}
25+
}
26+
};
27+
```
28+
</div><div class="col-md-6" markdown="block">
29+
```js
30+
// OR package.json
31+
{
32+
// [...]
33+
"jest": {
34+
"globals": {
35+
"ts-jest": {
36+
"babelConfig": true
37+
}
38+
}
39+
}
40+
}
41+
```
42+
</div></div>
43+
44+
#### Path to a `balelrc` file:
45+
46+
The path should be relative to the current working directory where you start Jest from. You can also use `<rootDir>` in the path, or use an absolute path (this last one is strongly not recommanded).
47+
48+
<div class="row"><div class="col-md-6" markdown="block">
49+
```js
50+
// jest.config.js
51+
module.exports = {
52+
// [...]
53+
globals: {
54+
'ts-jest': {
55+
babelConfig: 'babelrc.test.js'
56+
}
57+
}
58+
};
59+
```
60+
</div><div class="col-md-6" markdown="block">
61+
```js
62+
// OR package.json
63+
{
64+
// [...]
65+
"jest": {
66+
"globals": {
67+
"ts-jest": {
68+
"babelConfig": "babelrc.test.js"
69+
}
70+
}
71+
}
72+
}
73+
```
74+
</div></div>
75+
76+
#### Inline compiler options:
77+
78+
Refer to the [Babel options](https://babeljs.io/docs/en/next/options) to know what can be used there.
79+
80+
<div class="row"><div class="col-md-6" markdown="block">
81+
```js
82+
// jest.config.js
83+
module.exports = {
84+
// [...]
85+
globals: {
86+
'ts-jest': {
87+
babelConfig: {
88+
comments: false,
89+
plugins: ['@babel/plugin-transform-for-of']
90+
}
91+
}
92+
}
93+
};
94+
```
95+
</div><div class="col-md-6" markdown="block">
96+
```js
97+
// OR package.json
98+
{
99+
// [...]
100+
"jest": {
101+
"globals": {
102+
"ts-jest": {
103+
"babelConfig": {
104+
"comments": false,
105+
"plugins": ["@babel/plugin-transform-for-of"]
106+
}
107+
}
108+
}
109+
}
110+
}
111+
```
112+
</div></div>

‎docs/user/config/diagnostics.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
title: Diagnostics option
3+
---
4+
5+
The `diagnostics` option allows to enable/disable the error reporting. But it can also be used to filter which one should throw during tests, as well from which file it should be reported or not.
6+
7+
A diagnostic can be:
8+
- an error in your TypeScript config (whether it's a file or inline)
9+
- syntax errors in some of your TypeScript files (source or tests)
10+
- type/semantic errors, what TypeScript has actually been made for 😁
11+
12+
If a diagnostic is not filtered out, it'll fail the compilatin within TSJest, and so will your related test.
13+
14+
### Disabling/enabling
15+
16+
By default all diagnostic are enabled. This is the same as setting the `diagnostics` option to `true`. To disable all diagnostics, set `diagnostics` to `false` (you might experience slightly better performence as well, especially if you disabled Jest cache).
17+
18+
### Advanced configuration
19+
20+
The option's value can also accpet an object for more advanced configuration. Each config. key is optional:
21+
22+
- **`pretty`**: Enables/disable colorful and pretty output of errors (default: _enabled_).
23+
- **`ignoreCodes`**: List of TypeScript error codes to ignore. Complete list can be found [there](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json). By default here are the ones ignored:
24+
- `6059`: _'rootDir' is expected to contain all source files._
25+
- `18002`: _The 'files' list in config file is empty._ (it is strongly recommanded to include this one)
26+
- `18003`: _No inputs were found in config file._
27+
- **`pathRegex`**: If specified, diagnostics of source files which path does **not** match will be ignored.
28+
29+
### Examples
30+
31+
#### Disabling diagnostics:
32+
33+
<div class="row"><div class="col-md-6" markdown="block">
34+
```js
35+
// jest.config.js
36+
module.exports = {
37+
// [...]
38+
globals: {
39+
'ts-jest': {
40+
diagnostics: false
41+
}
42+
}
43+
};
44+
```
45+
</div><div class="col-md-6" markdown="block">
46+
```js
47+
// OR package.json
48+
{
49+
// [...]
50+
"jest": {
51+
"globals": {
52+
"ts-jest": {
53+
"diagnostics": false
54+
}
55+
}
56+
}
57+
}
58+
```
59+
</div></div>
60+
61+
#### Advanced options:
62+
63+
##### Enabling diagnostics for test files only
64+
65+
Assuming all your test files ends with `.spec.ts` or `.test.ts`, using the following config will enable error reporting only for those files:
66+
67+
<div class="row"><div class="col-md-6" markdown="block">
68+
```js
69+
// jest.config.js
70+
module.exports = {
71+
// [...]
72+
globals: {
73+
'ts-jest': {
74+
diagnostics: {
75+
pathRegex: /\.(spec|test).ts$/
76+
}
77+
}
78+
}
79+
};
80+
```
81+
</div><div class="col-md-6" markdown="block">
82+
```js
83+
// OR package.json
84+
{
85+
// [...]
86+
"jest": {
87+
"globals": {
88+
"ts-jest": {
89+
"diagnostics": {
90+
"pathRegex": "\\.(spec|test)\\.ts$"
91+
}
92+
}
93+
}
94+
}
95+
}
96+
```
97+
</div></div>
98+
99+
##### Ignoring some error codes:
100+
101+
All TypeScript error codes can be found [there](https://github.com/Microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json). The `ignoreCodes` option accepts this values:
102+
1. A single `number` (example: `1009`): unique error code to ignore
103+
2. A `string`, can be:
104+
1. Unique code (example `"1009"`, `"TS1009"` or `"ts1009"`)
105+
2. List of the above (example: `"1009, TS2571, 4072 ,ts6031 "`)
106+
3. An `array` of one or more from `1` or `2.1` (example: `[1009, "TS2571", "6031"]`)
107+
108+
It's advised to use concise types along the list of course:
109+
110+
<div class="row"><div class="col-md-6" markdown="block">
111+
```js
112+
// jest.config.js
113+
module.exports = {
114+
// [...]
115+
globals: {
116+
'ts-jest': {
117+
diagnostics: {
118+
ignoreCodes: [2571, 6031, 18003]
119+
}
120+
}
121+
}
122+
};
123+
```
124+
</div><div class="col-md-6" markdown="block">
125+
```js
126+
// OR package.json
127+
{
128+
// [...]
129+
"jest": {
130+
"globals": {
131+
"ts-jest": {
132+
"diagnostics": {
133+
"ignoreCodes": [2571, 6031, 18003]
134+
}
135+
}
136+
}
137+
}
138+
}
139+
```
140+
</div></div>

‎docs/user/config/stringifyContentPathRegex.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Stringify content option
3+
---
4+
5+
The `stringifyContentPathRegex` option has been kept for backward compatibility of `__HTML_TRANSFORM__`, and should actually be another simple Jest processor. It's a regular expression pattern used to match the path of file to be transformed. If it matches, the file will be exported as a module exporting its content.
6+
7+
Let's say for example that you have a file `foo.ts` which contains `export default "bar"`, and your `stringifyContentPathRegex` is set to `foo\\.ts$`, the resulting module won't be the result of compiling `foo.ts` source, but instead it'll be a module which exports the string `"export default \"bar\""`.
8+
9+
**CAUTION**: Whatever file(s) you want to match with `stringifyContentPathRegex` pattern, you must ensure the Jest `transform` option pointing to `ts-jest` matches them. You may also have to add the extendson(s) of this/those file(s) to `moduleFileExtensions` Jest option.
10+
11+
### Example:
12+
13+
In the `jest.config.js` version, you could do as in the `package.json` version of the config, but extending from the preset will ensure more compatiblity without any changes when updating.
14+
15+
<div class="row"><div class="col-md-6" markdown="block">
16+
```js
17+
// jest.config.js
18+
const { jestPreset } = require('ts-jest');
19+
20+
module.exports = {
21+
// [...]
22+
moduleFileExtensions: [
23+
...jestPreset.moduleFileExtensions,
24+
'html'
25+
],
26+
transform: {
27+
...jestPreset.transform,
28+
'\\.html$': 'ts-jest'
29+
}
30+
globals: {
31+
'ts-jest': {
32+
stringifyContentPathRegex: /\.html$/
33+
}
34+
}
35+
};
36+
```
37+
</div><div class="col-md-6" markdown="block">
38+
```js
39+
// OR package.json
40+
{
41+
// [...]
42+
"jest": {
43+
"moduleFileExtensions": ["js", "ts", "html"]
44+
"transform": {
45+
"\\.(html|ts|js)$": "ts-jest"
46+
}
47+
"globals": {
48+
"ts-jest": {
49+
"stringifyContentPathRegex": "\\.html$"
50+
}
51+
}
52+
}
53+
}
54+
```
55+
</div></div>

‎docs/user/config/tsConfig.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ By default, TSJest will do like `tsc` and use the project's `tsconfig.json` file
88

99
If you need to use defaults and force TSJest to use the defaults even if there is a `tsconfig.json`, you can set this option to `false`.
1010

11-
#### Examples
11+
### Examples
1212

13-
### Path to a `tsconfig` file:
13+
#### Path to a `tsconfig` file:
1414

1515
The path should be relative to the current working directory where you start Jest from. You can also use `<rootDir>` in the path, or use an absolute path (this last one is strongly not recommanded).
1616

@@ -42,7 +42,7 @@ module.exports = {
4242
```
4343
</div></div>
4444

45-
### Inline compiler options:
45+
#### Inline compiler options:
4646

4747
Refer to the [TypeScript compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to know what can be used. It's basically the same that you'd put in your `tsconfig.json`'s `compilerOptions`.
4848

@@ -78,7 +78,7 @@ module.exports = {
7878
```
7979
</div></div>
8080

81-
### Disable auto-lookup:
81+
#### Disable auto-lookup:
8282

8383
By default TSJest will try to find the `tsconfig.json` in your project. But you may want to not use it at all and keep TypeScript default options. You can achieve this by setting `tsConfig` to `false`.
8484

0 commit comments

Comments
 (0)
⚡