Docs Developer Site
DeveloperDocsTypescript StarterStableTest

Testing

Contents

Setting up Jest, a JavaScript testing framework designed to ensure correctness of your JavaScript codebase.

If you are writing Typescript code, chances are you want to write tests for that code, and you want to write them in Typescript. Here’s how to configure test runs in your application.

Install

npm install --save-dev jest-environment-jsdom ts-node ts-jest

Configure

Jest

In our example we will configure processing of both client-side and server-side Typescript code.

Create a file called jest.config.js in the root of the project with the following content:

import type { Config } from '@jest/types';


const DIR_SRC = 'src/main/resources';
const DIR_SRC_JEST = 'src/jest';
const DIR_SRC_JEST_CLIENT = `${DIR_SRC_JEST}/client`;
const DIR_SRC_JEST_SERVER = `${DIR_SRC_JEST}/server`;
const AND_BELOW = '**';
const SOURCE_FILES = `*.{ts,tsx}`;
const TEST_EXT = `{spec,test}.{ts,tsx}`;
const TEST_FILES = `*.${TEST_EXT}`;


const commonConfig: Config.InitialProjectOptions = {
  collectCoverageFrom: [
    `${DIR_SRC}/${AND_BELOW}/${SOURCE_FILES}`,
  ],

  // Insert Jest's globals (expect, test, describe, beforeEach etc.) into the
  // global environment. If you set this to false, you should import from @jest/globals, e.g.
  // injectGlobals: true, // Doesn't seem to work?
};

const clientSideConfig: Config.InitialProjectOptions = {
  ...commonConfig,
  displayName: {
    color: 'white',
    name: 'CLIENT',
  },

  // A map from regular expressions to module names or to arrays of module
  // names that allow to stub out resources, like images or styles with a
  // single module.
  // Use <rootDir> string token to refer to rootDir value if you want to use
  // file paths.
  // Additionally, you can substitute captured regex groups using numbered
  // backreferences.
  moduleNameMapper: {
    '/assets/(.*)': `<rootDir>/${DIR_SRC}/assets/$1`,
  },

  // Run clientside tests with DOM globals such as document and window
  testEnvironment: 'jsdom',

  // The glob patterns Jest uses to detect test files. By default it looks for
  // .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any
  // files with a suffix of .test or .spec (e.g. Component.test.js or
  // Component.spec.js). It will also find files called test.js or spec.js.
  // (default: [
  //   "**/__tests__/**/*.[jt]s?(x)",
  //   "**/?(*.)+(spec|test).[jt]s?(x)"
  // ])
  testMatch: [
    `<rootDir>/${DIR_SRC_JEST_CLIENT}/${AND_BELOW}/${TEST_FILES}`,
  ],
  transform: {
    "^.+\\.(ts|js)x?$": [
      'ts-jest',
      {
        tsconfig: `${DIR_SRC_JEST_CLIENT}/tsconfig.json`
      }
    ]
  }
};

const serverSideConfig: Config.InitialProjectOptions = {
  ...commonConfig,
  displayName: {
    color: 'blue',
    name: 'SERVER',
  },

  // A set of global variables that need to be available in all test
  // environments.
  // If you specify a global reference value (like an object or array) here,
  // and some code mutates that value in the midst of running a test, that
  // mutation will not be persisted across test runs for other test files.
  // In addition, the globals object must be json-serializable, so it can't be
  // used to specify global functions. For that, you should use setupFiles.
  globals: {
    app: {
      name: 'com.example.myproject',
      config: {},
      version: '1.0.0'
    },
  },

  // A map from regular expressions to module names or to arrays of module
  // names that allow to stub out resources, like images or styles with a
  // single module.
  // Use <rootDir> string token to refer to rootDir value if you want to use
  // file paths.
  // Additionally, you can substitute captured regex groups using numbered
  // backreferences.
  moduleNameMapper: {
    '/lib/myproject/(.*)': `<rootDir>/${DIR_SRC}/lib/myproject/$1`,
  },

  // A list of paths to modules that run some code to configure or set up the
  // testing environment. Each setupFile will be run once per test file. Since
  // every test runs in its own environment, these scripts will be executed in
  // the testing environment before executing setupFilesAfterEnv and before
  // the test code itself.
  setupFiles: [
    `<rootDir>/${DIR_SRC_JEST_SERVER}/setupFile.ts`
  ],

  // Run serverside tests without DOM globals such as document and window
  testEnvironment: 'node',

  // The glob patterns Jest uses to detect test files. By default it looks for
  // .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any
  // files with a suffix of .test or .spec (e.g. Component.test.js or
  // Component.spec.js). It will also find files called test.js or spec.js.
  // (default: [
  //   "**/__tests__/**/*.[jt]s?(x)",
  //   "**/?(*.)+(spec|test).[jt]s?(x)"
  // ])
  testMatch: [
    `<rootDir>/${DIR_SRC_JEST_SERVER}/${AND_BELOW}/${TEST_FILES}`,
  ],

  transform: {
    "^.+\\.(ts|js)x?$": [
      'ts-jest',
      {
          tsconfig: `${DIR_SRC_JEST_SERVER}/tsconfig.json`
      }
    ]
  },
};

const customJestConfig: Config.InitialOptions = {
  coverageProvider: 'v8', // To get correct line numbers under jsdom
  passWithNoTests: true,
  projects: [clientSideConfig, serverSideConfig],
};

export default customJestConfig;

With this config Jest will find and execute test files in the 'src/jest/client' and 'src/jest/server' folders called .test.ts (or .tsx) or .spec.ts (or .tsx).

Set up src/jest folder structure with thess files inside:

src/jest/client/tsconfig.json 
{
  "extends": "../../main/resources/assets/tsconfig.json",

  "include": [
    "./**/*.spec.ts",
    "./**/*.spec.tsx",
    "./**/*.test.ts",
    "./**/*.test.tsx",
  ],

  "compilerOptions": {
    // "baseUrl": ".",

    // A series of entries which re-map imports to lookup locations relative
    // to the baseUrl if set, or to the tsconfig file itself otherwise.
    "paths": {
      "/assets/*": ["../../main/resources/assets/*"],
    },

    "sourceMap": true, // Important to get correct line numbers when running coverage tests

    // By default all visible ”@types” packages are included in your
    // compilation. Packages in node_modules/@types of any enclosing folder
    // are considered visible. For example, that means packages within
    // ./node_modules/@types/, ../node_modules/@types/,
    // ../../node_modules/@types/, and so on.
    // If types is specified, only packages listed will be included in the
    // global scope.
    // This feature differs from typeRoots in that it is about specifying
    // only the exact types you want included, whereas typeRoots supports
    // saying you want particular folders.
    // "types": [
      // "jest", // Doesn't even work for test files in this folder?
    // ],

  }, // compilerOptions

}
src/jest/server/global.d.ts 
/// <reference types="@enonic-types/global" />

export declare type App = typeof app;
export declare type Log = typeof log;
export declare type DoubleUnderscore = typeof __;
export declare type Require = typeof require;
export declare type Resolve = typeof resolve;

This Jest setupFile is used to mock the XP Framework, injecting standard Globals into the server-side test environment:

src/jest/server/setupFile.ts 
import type {App, Log} from './global.d';


// Avoid type errors
declare module globalThis {
    var app: App
    var log: Log
}


// In order for console to exist in the global scope when running tests in
// testEnvironment: 'node' the @types/node package must be installed and
// potentially listed under types in tsconfig.json.
globalThis.log = {
    debug: console.debug,
    info: console.info,
    error: console.error,
    warning: console.warn
}
src/jest/server/tsconfig.json 
{
  "extends": "../../main/resources/tsconfig.json",

  // Specifies an array of filenames or patterns to include in the program.
  // These filenames are resolved relative to the directory containing the
  // tsconfig.json file.
  "include": [
    "./**/*.spec.ts",
    "./**/*.spec.tsx",
    "./**/*.test.ts",
    "./**/*.test.tsx",
  ],

  "compilerOptions": {
    // A series of entries which re-map imports to lookup locations relative
    // to the baseUrl if set, or to the tsconfig file itself otherwise.
    "paths": {
      "/lib/xp/*": ["../../../node_modules/@enonic-types/lib-*"],
      "/*": ["../../main/resources/*"],
    },
    "sourceMap": true, // Important to get correct line numbers when running coverage tests
    "types": [
      "@enonic-types/global",
      // "jest", // Doesn't even work for test files in this folder?
      "node", // console
    ],
  }, // compilerOptions
}

package.json

Add the following scripts to the package.json file:

{
  "scripts": {
    "cov": "jest --no-cache --coverage",
    "test": "jest --no-cache"
  }
}

test command starts execution of tests. cov command does exactly the same, but also generates coverage report.

build.gradle

Add the following task to the build.gradle file:

build.gradle 
tasks.register('npmTest', NpmTask) {
	args = [
		'run',
		'test'
	]
	dependsOn npmInstall
	environment = [
		'FORCE_COLOR': 'true',
	]
  inputs.dir 'src/jest'
  outputs.dir 'coverage'
}

test.dependsOn npmTest

With this setup tests will be executed on every build, but you can also run them separately with the following command:

./gradlew test
If you want to learn more about writing tests for your Enonic project, check out the Testing with Jest and Mock-XP tutorial.

Summary

With testing enabled, you have reached the end of this tutorial.

The TypeScript Starter is basically the end result of this tutorial, so when creating your next project - simply run enonic project create -r starter-ts to get a best practice development setup, just like that!

Enjoy!

- With ♥ from the Enonic team

Contents

Contents