> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# @aspect_rules_jest//jest:defs.bzl

> Bazel rules_jest public API: jest_test rule for running Jest JavaScript and TypeScript unit tests with sharding, filtering, and snapshot updates.

<Callout icon="book">
  Documentation for [@aspect\_rules\_jest@v0.25.0](https://registry.bazel.build/modules/aspect_rules_jest/0.25.0) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_jest/blob/v0.25.0/jest/defs.bzl)
</Callout>

# Public API for Jest rules

## Function: `jest_test`

jest\_test rule

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

Supports filtering tests with `--test_filter` flag. The filter is matched against test file paths using Jest's `testRegex` config option. For example: `bazel test --test_filter="user" //my:test`.

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

### Parameters

<ParamField body="name" type="unknown" required>
  A unique name for this target.
</ParamField>

<ParamField body="node_modules" type="unknown" 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.
</ParamField>

<ParamField body="config" type="unknown" default={`None`}>
  "Optional Jest config file. See [https://jestjs.io/docs/configuration](https://jestjs.io/docs/configuration).

  Supported config file types are ".js", ".cjs", ".mjs", ".json" which come from [https://jestjs.io/docs/configuration](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](https://github.com/aspect-build/rules_ts).
</ParamField>

<ParamField body="data" type="unknown" default={`[]`}>
  Runtime dependencies of the Jest test.

  This should include all test files, configuration files & files under test.
</ParamField>

<ParamField body="snapshots" type="unknown" 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`.
</ParamField>

<ParamField body="run_in_band" type="unknown" 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](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](https://docs.bazel.build/versions/main/test-encyclopedia.html#test-sharding).
</ParamField>

<ParamField body="colors" type="unknown" default={`True`}>
  When True, the `--colors` argument is passed to the Jest CLI. See [https://jestjs.io/docs/cli#--colors](https://jestjs.io/docs/cli#--colors).
</ParamField>

<ParamField body="auto_configure_reporters" type="unknown" 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.
</ParamField>

<ParamField body="auto_configure_test_sequencer" type="unknown" 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](https://jestjs.io/docs/configuration#testsequencer-string) for more information on Jest testSequencer config option.
</ParamField>

<ParamField body="snapshots_ext" type="unknown" default={`.snap`}>
  The expected extensions for snapshot files. Defaults to `.snap`, the Jest default.
</ParamField>

<ParamField body="quiet_snapshot_updates" type="unknown" 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.
</ParamField>

<ParamField body="timeout" type="unknown" default={`None`}>
  standard attribute for tests. Defaults to "short" if both timeout and size are unspecified.
</ParamField>

<ParamField body="size" type="unknown" default={`None`}>
  standard attribute for tests
</ParamField>

<ParamField body="kwargs" type="unknown">
  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](https://github.com/aspect-build/rules_js/blob/main/docs/js_binary.md)
</ParamField>