How to update an existing project in your Nx workspace to use Jest as a test runner instead of Karma

Nx v6.3 introduced the ability to use Jest as a unit test runner. When you generate a new library or application in your Nx workspace, Nx conveniently asks you whether you want to use Jest or Karma as a unit test runner. But what if you have an existing library that was previously configured to use Karma? How can you update your existing library to use Jest instead of Karma?

This article outlines the 3 steps it takes to update your existing library to use Jest as a unit test runner instead of Karma:

1. Remove your library's test configuration in angular.json.
2. Remove the Karma-related files in your library directory.
3. Generate the Jest configuration for your library.

Let's have a look at each of the steps in more detail.

For the sake of demonstration, let's assume that you have an Nx v6.3+ workspace with a library called existing-library that is located in libs/existing-library.

1. Remove your library's test configuration in angular.json

Open angular.json in the root of your Nx workspace.

Navigate to the property projects.existing-library.architect and delete its entire test property.

Before:

{
  "projects": {
    "existing-library": {
      "architect": {
        "lint": {
          ...
        },
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "main": "libs/existing-library/src/test.ts",
            "tsConfig": "libs/existing-library/tsconfig.spec.json",
            "karmaConfig": "libs/existing-library/karma.conf.js"
          }
        }
      }
    }
  }
}

After:

{
  "projects": {
    "existing-library": {
      "architect": {
        "lint": {
          ...
        }
        // "test" property completely removed
      }
    }
  }
}

2. Remove the Karma-related files in your library directory

Go to the libs/existing-library directory and delete the following files:

• src/test.js
• karma.conf.js
• tsconfig.spec.js

Before:

libs
├── existing-library
│   ├── karma.conf.js # delete this file
│   ├── src
│   │   ├── index.ts
│   │   ├── lib
│   │   └── test.js # delete this file
│   ├── tsconfig.lib.json
│   ├── tsconfig.spec.json # delete this file
│   └── tslint.json

After:

libs
├── existing-library
│   ├── src
│   │   ├── index.ts
│   │   ├── lib
│   ├── tsconfig.lib.json
│   └── tslint.json

3. Generate the Jest configuration for your library

Now that the Karma-related configuration and files have been removed, it's time to generate the Jest configuration. Luckily, Nx has us covered with a convenient CLI command.

From the root of your Nx workspace, run:

$ ng generate jest-project --project existing-library

This adds a new test configuration for your library in your angular.json file:

{
  "projects": {
    "existing-library": {
      "architect": {
        "lint": {
          ...
        },
        // Newly created test property
        "test": {
          "builder": "@nrwl/builders:jest",
          "options": {
            "jestConfig": "libs/existing-library/jest.config.js",
            "tsConfig": "libs/existing-library/tsconfig.spec.json",
            "setupFile": "libs/existing-library/src/test-setup.ts"
          }
        }
      }
    }
  }
}

and creates the Jest-related files in your library directory:

• src/test-setup.js
• jest.config.js
• tsconfig.spec.json

libs
├── existing-library
│   ├── jest.config.js # Newly created file
│   ├── src
│   │   ├── index.ts
│   │   ├── lib
│   │   └── test-setup.ts # Newly created file
│   ├── tsconfig.lib.json
│   ├── tsconfig.spec.json # Newly created file
│   └── tslint.json

To verify that your library's test runner has been successfully migrated from Karma to Jest, go to the root of your Nx workspace and run:

$ ng test existing-library

If all went well, your unit tests should now be run by Jest instead of Karma.

Summary

Migrating a library's test runner from Karma to Jest in an Nx v6.3+ workspace is easy. Just complete the 3 following steps:

1. Remove your library's test configuration in angular.json.
2. Remove the Karma-related files in your library directory.
3. Generate the Jest configuration for your library.

If anything is unclear or you need any help, don't hesitate to leave a comment below.

Happy testing!