chore(release): 27.1.0 (#3112)

CHANGELOG.md

@@ -1,3 +1,28 @@
+# [27.1.0](https://github.com/kulshekhar/ts-jest/compare/v27.0.7...v27.1.0) (2021-11-30)
+
+
+### Features
+
+* allow subclasses to extend `processAsync` and `getCacheKeyAsync` ([#3047](https://github.com/kulshekhar/ts-jest/issues/3047)) ([571a880](https://github.com/kulshekhar/ts-jest/commit/571a880007642c9dcbcd7bf109c5392e7eb78cc4))
+* **config:** support custom AST transformers written in TypeScript ([#3063](https://github.com/kulshekhar/ts-jest/issues/3063)) ([340a305](https://github.com/kulshekhar/ts-jest/commit/340a30573e5ff92df77c94af51c371ce4bf956e7)), closes [#2831](https://github.com/kulshekhar/ts-jest/issues/2831)
+* export `ts-jest` public apis from `index.js` ([#3080](https://github.com/kulshekhar/ts-jest/issues/3080)) ([53175dd](https://github.com/kulshekhar/ts-jest/commit/53175dd04218bf22ead464e30aa01b258c87e7af)), closes [#3045](https://github.com/kulshekhar/ts-jest/issues/3045)
+
+
+### Code Refactoring
+
+* **utils:** deprecate `mocked` util function ([#3102](https://github.com/kulshekhar/ts-jest/issues/3102)) ([55e69f1](https://github.com/kulshekhar/ts-jest/commit/55e69f12f65d678962c3087fca7673992f5f1b26))
+* define clear type for `compiler` option ([#3087](https://github.com/kulshekhar/ts-jest/issues/3087)) ([cc42daf](https://github.com/kulshekhar/ts-jest/commit/cc42daf795585887664be59956d2c52244237bda))
+* **transformers**: deprecate `path-mapping` AST transformer ([#3088](https://github.com/kulshekhar/ts-jest/issues/3088)) ([d8f6b96](https://github.com/kulshekhar/ts-jest/commit/d8f6b9624ee76a164aa7003720cd3f83fc6c4865))
+* **transformers**: use ts `factory` API for `hoisting` AST transformer ([#3058](https://github.com/kulshekhar/ts-jest/issues/3058)) ([a72f51d](https://github.com/kulshekhar/ts-jest/commit/a72f51d9b7c4ea2866e486c0aac4f4706c3ed542))
+
+
+## DEPRECATIONS
+
+* **transformers**: `path-mapping` AST transformer is deprecated and will be removed in **v28.0.0**. One should use an alternative one like https://github.com/LeDDGroup/typescript-transform-paths instead.
+* **utils**: `mocked` function is deprecated and will be removed in **v28.0.0**. The function has been integrated into `jest-mock` package as a part of Jest **27.4.0**, see https://github.com/facebook/jest/pull/12089. One should use the one from Jest instead
+
+
+
 ## [27.0.7](https://github.com/kulshekhar/ts-jest/compare/v27.0.6...v27.0.7) (2021-10-16)
 
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-jest",
-  "version": "27.0.7",
+  "version": "27.1.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {

website/docs/getting-started/options/astTransformers.md

@@ -97,6 +97,12 @@ the exposed transformers are:
   This transformer works similar to `moduleNameMapper` in `jest.config.js`. When using this transformer, one might not need
   `moduleNameMapper` anymore.
 
+:::warning
+
+`path-mapping` AST transformer is now deprecated. Please should use an alternative one like https://github.com/LeDDGroup/typescript-transform-paths instead.
+
+:::
+
 #### Example of opt-in transformers
 
 ```js

website/docs/guides/test-helpers.md

@@ -3,6 +3,13 @@ id: test-helpers
 title: Test helpers
 ---
 
+:::warning
+
+This function is now deprecated and will be removed in **28.0.0**. The function has been integrated into `jest-mock` package
+as a part of Jest **27.4.0**, see https://github.com/facebook/jest/pull/12089. Please use the one from `jest-mock` instead.
+
+:::
+
 `ts-jest` provides some test utilities to be used in your test, related to TypeScript.
 
 ## `mocked<T>(item: T, deep = false)`

website/versioned_docs/version-27.1/babel7-or-ts.md

@@ -0,0 +1,76 @@
+---
+id: babel7-or-ts
+title: Babel7 or TypeScript
+---
+
+In Sept. 2018 Babel7 got released with an interesting preset: `@babel/preset-typescript`.
+
+The goal is to make it easy for users using Babel to try TypeScript without moving out from Babel, just by adding a preset in their Babel config (here is the [MSDN blog post](https://blogs.msdn.microsoft.com/typescript/2018/08/27/typescript-and-babel-7/) about TypeScript and Babel 7).
+
+## Limitations
+
+While `@babel/preset-typescript` is a great preset, you must know the limitation of it. Here is what is possible with TypeScript (and `ts-jest`), which is not with Babel7 and `@babel/preset-typescript`:
+
+#### No type-checking
+
+This is the big **PRO** of using TypeScript vs Babel, you have type-checking out of the box.
+
+You'll get a more fluent TDD experience (when using `ts-jest`) since files will be type-checked at the same time they're compiled and ran.
+
+Here TypeScript will throw while Babel won't:
+
+```ts
+const str: string = 42
+```
+
+With Babel, files are transpiled as isolated modules, there is no notion of "project". With TypeScript, files are part of a project and are compiled in that scope.
+
+---
+
+#### No `namespace`
+
+```ts
+namespace app {
+  export const VERSION = '1.0.0'
+  export class App {
+    /* ... */
+  }
+}
+```
+
+---
+
+#### No `const enum`
+
+```ts
+const enum Directions {
+  Up,
+  Down,
+  Left,
+  Right,
+}
+```
+
+---
+
+#### No declaration merging (`enum`, `namespace`, ...)
+
+You won't be able to do [declaration merging](https://www.typescriptlang.org/docs/handbook/declaration-merging.html).
+
+---
+
+#### No legacy `import`/`export`
+
+```ts
+import lib = require('lib')
+// ...
+export = myVar
+```
+
+---
+
+#### No caret type-casting with JSX enabled
+
+```ts
+const val = <string>input
+```

website/versioned_docs/version-27.1/contributing.md

@@ -0,0 +1,174 @@
+---
+id: contributing
+title: Contributing
+---
+
+When contributing to this repository, please first discuss the change you wish to make via [`ts-jest` GitHub discussion](https://github.com/kulshekhar/ts-jest/discussions) or [issue](https://github.com/kulshekhar/ts-jest/issues) with the owners of this repository before making a change.
+
+Please note we have a code of conduct, please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Ensure the tests are passing and that you have latest `main` branch merged in.
+2. Update the `docs/` with details of your changes if required.
+3. If possible, squash your commits. There must be only one commit in your PR (until a review). Then after each review requesting changes, DO NOT squash your commits with the one before the review, so that we can see intermediate modifications.
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
+
+_These are internal technical documents. If you're not a contributor to `ts-jest`, but simply trying to use the library you'll find nothing of value here_
+
+## E2E Testing
+
+### Preparing
+
+The preparation of E2E test directory is done in `scripts/e2e.js`. Here is the process:
+
+```plantuml
+start
+
+:bundle ts-jest;
+note right
+will build ts-jest before creating the bundle
+end note
+
+:create temp work dir;
+note right
+`e2e/~__workdir_symlink__` links to it
+except on CI environments
+end note
+
+while (for each template)
+note right
+templates are in `e2e/~__templates__/`
+end note
+
+if (template's build directory) then (exists)
+:wipe but `node_modules` dir;
+else (not exists)
+:create;
+endif
+
+:copy files from template's dir to its build dir;
+
+if (package lock file) then (exists)
+:read metadata;
+
+    if (package lock file) then (has changed)
+      :remove `node_modules` dir;
+
+      :npm install (or ci);
+
+      :npm install ts-jest bundle;
+
+    else if (ts-jest bundle) then (has changed)
+      :npm install ts-jest bundle;
+
+    else (hasn't changed)
+    endif
+    :write updated metadata;
+
+else (not exists)
+endif
+
+endwhile (done)
+
+:all templates ready;
+
+stop
+```
+
+### Running
+
+When a test-case needs to be run with a given template within tests, here is what's happening (in `e2e/__helpers__/test-case/runtime.ts`):
+
+```plantuml
+start
+
+:create work dir;
+note right
+It'll be different per test-case
+and per template basis.
+end note
+-> e2e/~__workdir_symlink__/{template}/{test-case};
+
+if (has a node_modules dir?) then (yes)
+:symlink node_modules;
+note left
+avoid re-running npm install
+for each test case and template;
+end note
+else (no)
+endif
+
+:copy files from template;
+note right
+all files in template dir are
+copied to test case work dir
+except `node_modules` and
+`package-lock.json`
+end note
+
+while (for each file in test case dir)
+if (is snapshot dir) then (yes)
+:symlink dir;
+note left
+snapshots directories are symlinked
+to test case source dir so that
+updating them would update in the
+source folder
+end note
+
+else if (is jest.config.js) then (yes)
+if (jest.config.js is function?) then (yes)
+:call with parent content;
+note left
+allows for
+extending
+end note
+else (no)
+endif
+
+else (others)
+:copy;
+note right
+all files in test case source
+dir are copied to the work dir
+except `node_modules` and
+`package-lock.json`
+end note
+
+endif
+endwhile
+
+:create special files;
+note right
+some special files are created
+to handle hooks for example and
+grab `process()` IO for later
+expectations
+end note
+
+:update package.json;
+note right
+set a custom but fixed name
+and version in package.json
+which is specific to the
+test case + template
+end note
+
+#tomato:run tests;
+
+while (for each snapshot) is (missing in test case)
+:copy;
+note right
+while we symlinked each snapshots
+directory, newly created snapshots
+in non existing dir will need to
+be copied over into
+e2e/~__cases__/{test-case}
+end note
+endwhile
+
+:return results;
+
+stop
+```

website/versioned_docs/version-27.1/debugging.md

@@ -0,0 +1,22 @@
+---
+id: debugging
+title: Debugging ts-jest
+---
+
+You can activate the debug logger by setting the environment variable `TS_JEST_LOG` before running tests.
+The output of the logger will be in **ts-jest.log** in current working directory.
+
+The debug logger contains some useful information about how internal `ts-jest` works, including which files are processed,
+which Jest config or TypeScript config is used etc.
+
+**Linux/MacOS**
+
+```
+export TS_JEST_LOG=ts-jest.log
+```
+
+**Windows**
+
+```
+set TS_JEST_LOG=ts-jest.log
+```

website/versioned_docs/version-27.1/getting-started/installation.md

@@ -0,0 +1,58 @@
+---
+id: installation
+title: Installation
+---
+
+### Dependencies
+
+You can install `ts-jest` and dependencies all at once with one of the following commands.
+
+#### NPM
+
+```sh
+npm install --save-dev jest typescript ts-jest @types/jest
+```
+
+#### Yarn
+
+```sh
+yarn add --dev jest typescript ts-jest @types/jest
+```
+
+:::tip
+
+Tip: If you get an error with the following `npm` commands such as `npx: command not found`, you can replace `npx XXX` with `node node_modules/.bin/XXX` from the root of your project.
+
+:::
+
+### Jest config file
+
+#### Creating
+
+By default, Jest can run without any config files, but it will not compile `.ts` files.
+To make it transpile TypeScript with `ts-jest`, we will need to create a configuration file that will tell Jest to use a `ts-jest` preset.
+
+`ts-jest` can create the configuration file for you automatically:
+
+#### NPM
+
+```sh
+npx ts-jest config:init
+```
+
+#### Yarn
+
+```sh
+yarn ts-jest config:init
+```
+
+This will create a basic Jest configuration file which will inform Jest about how to handle `.ts` files correctly.
+
+You can also use the `jest --init` command (prefixed with either `npx` or `yarn` depending on what you're using) to have more options related to Jest.
+However, answer `no` to the Jest question about whether or not to enable TypeScript. Instead, add the line: `preset: "ts-jest"` to the `jest.config.js` file afterwards.
+
+#### Customizing
+
+For customizing jest, please follow their [official guide online](https://jestjs.io/docs/en/configuration.html).
+
+`ts-jest` specific options can be found [here](options).