Configuring Typescript project with `ts-jest` & `jest-extended`

README.md

TS-JEST & JEST-EXTENDED SUPPORT

This gist is designed to explain how to configure a project where you have your test code separated from your codebase. The project file structure looks a bit like this:

project
├─┬ lib                    # could be src
│ ├── globals.d.ts         # source code specific type declarations
│ └── index.ts
├─┬ tests
│ ├── index.test.ts
│ └── jest-extended.d.ts   # could be globals.d.ts if you have other test declarations to add
├── .eslintignore
├── .eslintrc.js           # remember to set `env["jest/globals"] = true` for test files & load `eslint-plugin-jest`
├── jest.config.js
├── package.json
├── README.md
├── tsconfig.eslint.json
├── tsconfig.jest.json
└── tsconfig.json

There are 3 steps:

1. tsconfig.jest.json: Extend your Typescript configuration to include your tests directory for types & compilation
2. jest.config.js: Configure ts-jest to recognize your jest specific configuration & compilation directives. This also includes the jest-extended/all definition as an array entry for setupFilesAfterEnv.
3. jest-extended.d.ts: Add a types reference entry to declare jest-extended types for the Typescript compiler

Alternative Project structure

If you follow the jest recommendations for unit testing to have tests as "close to your source as possible", this likely means your test code is inside your src/ or lib/ folder under __tests__/. If so, your test files are already included by your tsconfig.json[include] definition. You can still follow these instructions but note you will want to place your jest-extended reference outside of your source code directory and make sure to include it explicitly in tsconfig.jest.json[include] array.

Troubleshooting

Make sure you have read all the embedded comments in the configuration files below! The jest.config.json#[projects] configuration can be problematic.

VSCode Typescript

It can act a bit funny with type declaration files that are not named globals.d.ts and not in your base tsconfig.json. This does not mean ts-jest will not work. If you open the declaration file while the file is open, it will magically resolve. This is a flaw in vscode since it take some time to cache types into its own directory for its real-time compiler.

jest-extended.d.ts

/// <reference types="jest-extended" />

jest.config.js

module.exports = {
    globals: {
        // See reference: https://kulshekhar.github.io/ts-jest/docs/getting-started/options/tsconfig
        "ts-jest": {
            tsconfig: "tsconfig.jest.json"
        }
    },
    preset: "ts-jest",
    setupFilesAfterEnv: ["jest-extended/all"], // Prevents the need to `import "jest-extended"` in any jest matched file
    testPathIgnorePatterns: ["<rootDir>/tests/fixtures/"],
    // -----------------------------------------
    // The following is an example if you use the projects configuration for jest
    // projects: [
    //     // Projects configs can be tricky, some properties seem to be inherited from the 
    //     //     global config and others are overrided. When in doubt, drop it from the top level
    //     //     and define it specifically for the project. This is more likely if a preset or
    //     //     a special runner is defined since it will have its own configs it sets.
    //     // Remember it is JS so you can use variable declarations and spread operators to minimize
    //     //     duplicate expressions
    //     {
    //         displayName: "UNIT",
    //         preset: "ts-jest",
    //         runner: "@codejedi365/jest-serial-runner",
    //         // setupFilesAfterEnv, Must be specified internal to the project, will be ignored if made higher
    //         setupFilesAfterEnv: ["jest-extended/all"],
    //         testMatch: ["<rootDir>/tests/**/*.spec.ts"]
    //     },
    //     {
    //         // 2nd project definition
    //     }
    // ]
};

tsconfig.jest.json

{
  // extends: Pulls in all configs from an external file
  //          Any new definitions overrwrite the previous key entirely, not merged.
  "extends": "./tsconfig.json",
  // include: Adds the 'tests' directory to folders for typescript to read
  //          Required to force TS to find jest-extended.d.ts declaration file
  //          Must include all directories from the base config since all of include is replaced, not extended
  "include": ["lib", "tests"]
}

tsconfig.json

// Base configuration for project, should be source code only
{
  "include": ["lib"],      // Only source code directories could be "src", "lib", etc.
  "compilerOptions": {
    "declaration": true,   // Generates corresponding '.d.ts' files
    "module": "umd",
    "strict": true,
    "target": "es5"
    // ...                 // additional TS configuration settings
  }
}