@shopify/loom-plugin-jest v1.0.2

@shopify/loom-plugin-jest

This package provides a loom plugin that runs the Jest test runner as part of the loom test command.

Installation

yarn add @shopify/loom-plugin-jest --dev

Usage

Add jest to your loom workspace plugins. Jest is a workspace plugin, however most of its configuration through hooks occurs on the per-project level.

import {createWorkspace} from '@shopify/loom';
import {jest} from '@shopify/loom-plugin-jest';

// `createWorkspace` may be `createPackage`, or `createWebApp` if your workspace
// consists of a single project
export default createWorkspace((workspace) => {
  workspace.use(jest());
});

Jest Test Setup Files

By default this plugin sets Jest's setupFiles to look for setup files in tests/setup/environment.* and setupFilesAfterEnv to look for setup files in tests/setup/tests.* at the root of your workspace, and at the root of each project you have configured (if you have only one loom config then this is the same directory). You can modify this list of files by adjusting the jestSetupFiles, jestSetupFilesAfterEnv project hooks (for per-project files) and the jestSetupFiles, jestSetupFilesAfterEnv workspace hooks (for all projects in the workspace).

Jest Environment

The default environment is node. If you need access to a browser-like environment (such as having access to window) then you will need to use the jsdom environment. You can set this on a per-project basis with the jestTestEnvironment hook, which sets Jest's testEnvironment option:

import {createPackage, createProjectPlugin} from '@shopify/loom';

export default createPackage((pkg) => {
  pkg.use(jestAdjustments());
});

function jestAdjustments() {
  return createProjectPlugin('JestAdjustments', ({tasks: {test}}) => {
    test.hook(({hooks}) => {
      hooks.configure.hook((configuration) => {
        configuration.jestTestEnvironment?.hook(() => 'jsdom');
      });
    });
  });
}

Jest Test Runner

The default test runner is jest-circus/runner. If need to use a different test runner - such as the legacy test runner from before Jest 27 jest-jasmine2 - you can set this on a per-project basis with the jestTestRunner hook, which sets Jest's testRunner option:

import {createPackage, createProjectPlugin} from '@shopify/loom';

export default createPackage((pkg) => {
  pkg.use(jestAdjustments());
});

function jestAdjustments() {
  return createProjectPlugin('JestAdjustments', ({tasks: {test}}) => {
    test.hook(({hooks}) => {
      hooks.configure.hook((configuration) => {
        configuration.jestTestRunner?.hook(() => 'jest-jasmine2');
      });
    });
  });
}

Custom Transforms

By default JavaScript and TypeScript is supported. If you need to support additional file types you can use custom transforms - you can set these on a per-project basis with the jestTransform hook, which sets Jest's transform option:

import {createPackage, createProjectPlugin} from '@shopify/loom';

export default createPackage((pkg) => {
  pkg.use(jestAdjustments());
});

function jestAdjustments() {
  return createProjectPlugin('JestAdjustments', ({tasks: {test}}) => {
    test.hook(({hooks}) => {
      hooks.configure.hook((configuration) => {
        configuration.jestTransform?.hook((transforms) => ({
          ...transforms,
          '\\.txt$': 'path-to-custom-transformer',
        }));
      });
    });
  });
}

Hooks

This plugin adds the following hooks to JestProjectHooks:

• jestModuleFileExtensions, jestModuleNameMapper, jestSetupFiles, jestSetupFilesAfterEnv, jestTestEnvironment, jestTestRunner, jestTransform, jestWatchPathIgnorePatterns: Convineince hooks that map to the Jest config options with the same name without the "jest" prefix (e.g. the jestTestEnvironment hook maps to the testEnvironment Jest option).

  Modifying one of these hooks is functionally identical to modifying the corresponding key in the object that is returned by the jestConfig project hook.

  import {createProjectPlugin} from '@shopify/loom';
  
  function demoPlugin() {
    return createProjectPlugin('Demo', ({tasks: {test}}) => {
      test.hook(({hooks}) => {
        hooks.configure.hook((configure) => {
          // Configure the test environment
          configuration.jestTestEnvironment?.hook(() => 'jsdom');
        });
      });
    });
  }

• jestConfig: The Jest per-project configuration for single project. Use this to manipulate the Jest config for options that are not exposed as convinience hooks.

  import {createProjectPlugin} from '@shopify/loom';
  
  function demoPlugin() {
    return createProjectPlugin('Demo', ({tasks: {test}}) => {
      test.hook(({hooks}) => {
        hooks.configure.hook((configure) => {
          // Increase the test timeout to 10 seconds
          configure.jestConfig?.hook((config) => ({
            ...config,
            testTimeout: 10000,
          }));
        });
      });
    });
  }

This plugin adds the following hooks to JestWorkspaceHooks:

• jestSetupFiles and jestSetupFilesAfterEnv: Arrays of files that shall be added to every project's setupFiles and setupFilesAfterEnv respectively. jestSetupFiles defaults to tests/setup/environment.* and jestSetupFilesAfterEnv defaults to tests/setup/tests.*. These paths are relative to the workspace root.

  import {createWorkspacePlugin} from '@shopify/loom';
  
  function demoPlugin() {
    return createWorkspacePlugin('Demo', ({tasks: {test}}) => {
      test.hook(({hooks}) => {
        hooks.configure.hook((configure) => {
          // Add ./path/to/my-custom-setup.ts to setupFiles
          configure.jestSetupFiles?.hook((files) => [
            ...files,
            './path/to/my-custom-setup.ts',
          ]);
          // Add ./path/to/my-custom-setup-after-env.ts to setupFiles
          configure.jestSetupFilesAfterEnv?.hook((files) => [
            ...files,
            './path/to/my-custom-setup-after-env.ts',
          ]);
        });
      });
    });
  }

• jestConfig: The final Jest configuration object that is executed. This contains all projects.

  import {createWorkspacePlugin} from '@shopify/loom';
  
  function demoPlugin() {
    return createWorkspacePlugin('Demo', ({tasks: {test}}) => {
      test.hook(({hooks}) => {
        hooks.configure.hook((configure) => {
          // Configure the coverage output directory
          configure.jestConfig?.hook((config) => ({
            ...config,
            coverageDirectory: './some-path',
          }));
        });
      });
    });
  }

• jestFlags: An object of options to convert into command line flags for the jest command. These options are camelcase versions of their CLI counterparts.

  import {createWorkspacePlugin} from '@shopify/loom';
  
  function demoPlugin() {
    return createWorkspacePlugin('Demo', ({tasks: {test}}) => {
      test.hook(({hooks}) => {
        hooks.configure.hook((configure) => {
          // Always diable watch mode
          configure.jestFlags?.hook((flags) => ({
            ...flags,
            watch: false,
          }));
        });
      });
    });
  }