Public API for Jest rules

Macros and Functions

jest_test

jest_test rule

Supports Bazel sharding. See https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding.

Supports updating snapshots with bazel run {name}_update_snapshots if snapshots are specified.

Example usage (generated):

load("@aspect_rules_jest//jest:defs.bzl", "jest_test")

jest_test(
    # A unique name for this target.
    name = "",
    # Label pointing to the linked node_modules target where jest is linked, e.g
    node_modules = None,
)

name

Required.

A unique name for this target.

node_modules

Required.

Label pointing to the linked node_modules target where jest is linked, e.g. //:node_modules. jest-cli must be linked into the node_modules supplied. jest-junit is also required by default when auto_configure_reporters is True.

NB: Only the required npm packages are included in data from //:node_modules. Other npm packages are not included as inputs.

config

Optional. Default: None

"Optional Jest config file. See https://jestjs.io/docs/configuration.

Supported config file types are ".js", ".cjs", ".mjs", ".json" which come from https://jestjs.io/docs/configuration minus TypeScript since we this rule extends from the configuration. TypeScript jest configs should be transpiled before being passed to jest_test with rules_ts.

data

Optional. Default: []

Runtime dependencies of the Jest test.

This should include all test files, configuration files & files under test.

snapshots

Optional. Default: False

If True, a {name}_update_snapshots binary target is generated that will update all existing __snapshots__ directories when bazel run. This is the equivalent to running jest -u or jest --updateSnapshot outside of Bazel, except that new __snapshots__ will not automatically be created on update. To bootstrap a new __snapshots__ directory, you can create an empty one and then run the {name}_update_snapshots target to populate it.

If the name of the snapshot directory is not the default __snapshots__ because of a custom snapshot resolver, you can specify customize the snapshot directories with a glob or a static list. For example,

jest_test(
    name = "test",
    node_modules = "//:node_modules",
    config = "jest.config.js",
    data = [
        "greetings/greetings.js",
        "greetings/greetings.test.js",
        "link/link.js",
        "link/link.test.js",
    ],
    snapshots = glob(["**/__snaps__"], exclude_directories = 0),
)

or with a static list,

    snapshots = [
        "greetings/__greetings_snaps__",
        "link/__link_snaps__",
    ]

Snapshots directories must not contain any files except for snapshots. There must also be no BUILD files in the snapshots directories since they must be part of the same Bazel package that the jest_test target is in.

If snapshots are not configured to output to a directory that contains only snapshots, you may alternately set snapshots to a list of snapshot files expected to be generated by this jest_test target. These must be source files and all snapshots that are generated must be explicitly listed. You may use a glob such as glob(["**/*.snap"]) to generate this list, in which case all snapshots must already be on disk so they are discovered by glob.

run_in_band

Optional. Default: True

When True, the --runInBand argument is passed to the Jest CLI so that all tests are run serially in the current process, rather than creating a worker pool of child processes that run tests. See https://jestjs.io/docs/cli#--runinband for more info.

This is the desired default behavior under Bazel since Bazel expect each test process to use up one CPU core. To parallelize a single jest_test across many cores, use shard_count instead which is supported by jest_test. See https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding.

colors

Optional. Default: True

When True, the --colors argument is passed to the Jest CLI. See https://jestjs.io/docs/cli#--colors.

auto_configure_reporters

Optional. Default: True

Let jest_test configure reporters for Bazel test and xml test logs.

When enabled, jest-junit must be linked to the supplied node_modules tree.

The default reporter is used for the standard test log and jest-junit is used for the xml log. These reporters are appended to the list of reporters from the user Jest config only if they are not already set.

The JEST_JUNIT_OUTPUT_FILE environment variable is always set to where Bazel expects a test runner to write its xml test log so that if jest-junit is configured in the user Jest config it will output the junit xml file where Bazel expects by default.

auto_configure_test_sequencer

Optional. Default: True

Let jest_test configure a custom test sequencer for Bazel test that support Bazel sharding.

Any custom testSequencer value in a user Jest config will be overridden.

See https://jestjs.io/docs/configuration#testsequencer-string for more information on Jest testSequencer config option.

snapshots_ext

Optional. Default: ".snap"

The expected extensions for snapshot files. Defaults to .snap, the Jest default.

quiet_snapshot_updates

Optional. Default: False

When True, snapshot update stdout & stderr is hidden when the snapshot update is successful.

On a snapshot update failure, its stdout & stderr will always be shown.

timeout

Optional. Default: None

standard attribute for tests. Defaults to "short" if both timeout and size are unspecified.

size

Optional. Default: None

standard attribute for tests

kwargs

Optional.

Additional named parameters passed to both js_test and js_binary. See https://github.com/aspect-build/rules_js/blob/main/docs/js_binary.md