feat(transformers): add path-mapping custom AST transformer (#1927)

Usage detail see https://kulshekhar.github.io/ts-jest/user/config/astTransformers

Author: ahnpnl

.eslintrc.js

@@ -41,6 +41,8 @@ module.exports = {
     'getter-return': 'warn',
     'guard-for-in': 'error',
     'id-match': 'error',
+    'jest/valid-title': 'off',
+    'jest/no-conditional-expect': 'off',
     'jsdoc/check-alignment': 'error',
     'jsdoc/check-indentation': 'error',
     'jsdoc/newline-after-description': 'warn',

docs/user/config/astTransformers.md

@@ -50,6 +50,54 @@ module.exports = {
 
 </div></div>
 
+### Public transformers
+
+`ts-jest` is able to expose transformers for public usage to provide the possibility to opt-in/out for users. Currently
+the exposed transformers are:
+
+- `path-mapping` convert alias import/export to relative import/export path base on `paths` in `tsconfig`. 
+This transformer works similar to `moduleNameMapper` in `jest.config.js`. When using this transformer, one might not need
+`moduleNameMapper` anymore.
+
+#### Example of opt-in transformers
+
+<div class="row"><div class="col-md-6" markdown="block">
+
+```js
+// jest.config.js
+module.exports = {
+  // [...]
+  globals: {
+    'ts-jest': {
+      astTransformers: {
+        before: ['ts-jest/dist/transformers/path-mapping'],
+      },
+    }
+  }
+};
+```
+
+</div><div class="col-md-6" markdown="block">
+
+```js
+// OR package.json
+{
+  // [...]
+  "jest": {
+    "globals": {
+      "ts-jest": {
+        astTransformers: {
+          "before": ["ts-jest/dist/transformers/path-mapping"]
+        }
+      }
+    }
+  }
+}
+```
+
+</div></div>
+
+
 ### Writing custom TypeScript AST transformers
 
 To write a custom TypeScript AST transformers, one can take a look at [the one](https://github.com/kulshekhar/ts-jest/tree/master/src/transformers) that `ts-jest` is using.

e2e/__cases__/path-mapping/direct-import.spec.ts

@@ -0,0 +1,7 @@
+import { getWelcomeMessage } from '@share/foo'
+
+test('should return welcome message', () => {
+  const userName = 'github-user'
+
+  expect(getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/dynamic-import.spec.ts

@@ -0,0 +1,6 @@
+test('should return welcome message', async () => {
+  const userName = 'github-user'
+  const foo = await import('@share/foo')
+
+  expect(foo.getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/export.spec.ts

@@ -0,0 +1,7 @@
+import { getWelcomeMessage } from '@share/export'
+
+test('should return welcome message', async () => {
+  const userName = ''
+
+  expect(getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/import-default.spec.ts

@@ -0,0 +1,7 @@
+import foo from '@share/foo'
+
+test('should return welcome message', () => {
+  const userName = 'github-user'
+
+  expect(foo(userName)).toBe(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/import-legacy.spec.ts

@@ -0,0 +1,7 @@
+import foo = require('@share/foo')
+
+test('should return welcome message', () => {
+  const userName = 'github-user'
+
+  expect(foo.getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/import-require.spec.ts

@@ -0,0 +1,7 @@
+const foo = require('@share/foo')
+
+test('should return welcome message', () => {
+  const userName = 'github-user'
+
+  expect(foo.getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/import-star.spec.ts

@@ -0,0 +1,7 @@
+import * as foo from '@share/foo'
+
+test('should return welcome message', () => {
+  const userName = 'github-user'
+
+  expect(foo.getWelcomeMessage(userName)).toEqual(`yolo ${userName}`)
+})

e2e/__cases__/path-mapping/import-type.spec.ts

@@ -0,0 +1,9 @@
+import type { Foo } from '@share/foo'
+
+test('should work', () => {
+  const a: Foo = {
+    bar: 1,
+  }
+
+  expect(a).toBeTruthy()
+})