> ## 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_jasmine//jasmine:defs.bzl

> Bazel rules_jasmine public API: jasmine_test rule and jasmine_test_rule for running JavaScript unit tests with the Jasmine framework under Bazel.

<Callout icon="book">
  Documentation for [@aspect\_rules\_jasmine@v2.0.2](https://registry.bazel.build/modules/aspect_rules_jasmine/2.0.2) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_jasmine/blob/v2.0.2/jasmine/defs.bzl)
</Callout>

rules\_jasmine public API

## Rule: `jasmine_test_rule`

Runs tests in NodeJS using the Jasmine test runner.

**Kind:** Test rule

### Attributes

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

<ParamField body="chdir" type="string" default={`""`}>
  Working directory to run the binary or test in, relative to the workspace.

  By default, `js_binary` runs in the root of the output tree.

  To run in the directory containing the `js_binary` use

  chdir = package\_name()

  (or if you're in a macro, use `native.package_name()`)

  WARNING: this will affect other paths passed to the program, either as arguments or in configuration files,
  which are workspace-relative.

  You may need `../../` segments to re-relativize such paths to the new working directory.
  In a `BUILD` file you could do something like this to point to the output path:

  ```python theme={null}
  js_binary(
      ...
      chdir = package_name(),
      # ../.. segments to re-relative paths from the chdir back to workspace;
      # add an additional 3 segments to account for running js_binary running
      # in the root of the output tree
      args = ["/".join([".."] * len(package_name().split("/"))) + "$(rootpath //path/to/some:file)"],
  )
  ```
</ParamField>

<ParamField body="data" type="list of labels" default={`[]`}>
  Runtime dependencies of the program.

  The transitive closure of the `data` dependencies will be available in
  the .runfiles folder for this binary/test.

  NB: `data` files are copied to the Bazel output tree before being passed
  as inputs to runfiles. See `copy_data_to_bin` docstring for more info.
</ParamField>

<ParamField body="entry_point" type="label" required>
  The main script which is evaluated by node.js.

  This is the module referenced by the `require.main` property in the runtime.

  This must be a target that provides a single file or a `DirectoryPathInfo`
  from `@aspect_bazel_lib//lib::directory_path.bzl`.

  See [https://github.com/aspect-build/bazel-lib/blob/main/docs/directory\_path.md](https://github.com/aspect-build/bazel-lib/blob/main/docs/directory_path.md)
  for more info on creating a target that provides a `DirectoryPathInfo`.
</ParamField>

<ParamField body="enable_runfiles" type="boolean" required>
  Whether runfiles are enabled in the current build configuration.

  Typical usage of this rule is via a macro which automatically sets this
  attribute based on a `config_setting` rule.
</ParamField>

<ParamField body="env" type="dictionary: String → String" default={`{}`}>
  Environment variables of the action.

  Subject to [\$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables)
  and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution if `expand_env` is set to True.
</ParamField>

<ParamField body="expand_args" type="boolean" default={`True`}>
  Enables [\$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables)
  and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution for `fixed_args`.

  This comes at some analysis-time cost even for a set of args that does not have any expansions.
</ParamField>

<ParamField body="expand_env" type="boolean" default={`True`}>
  Enables [\$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables)
  and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution for `env`.

  This comes at some analysis-time cost even for a set of envs that does not have any expansions.
</ParamField>

<ParamField body="fixed_args" type="list of strings" default={`[]`}>
  Fixed command line arguments to pass to the Node.js when this
  binary target is executed.

  Subject to [\$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables)
  and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution if `expand_args` is set to True.

  Unlike the built-in `args`, which are only passed to the target when it is
  executed either by the `bazel run` command or as a test, `fixed_args` are baked
  into the generated launcher script so are always passed even when the binary
  target is run outside of Bazel directly from the launcher script.

  `fixed_args` are passed before the ones specified in `args` and before ones
  that are specified on the `bazel run` or `bazel test` command line.

  See [https://bazel.build/reference/be/common-definitions#common-attributes-binaries](https://bazel.build/reference/be/common-definitions#common-attributes-binaries)
  for more info on the built-in `args` attribute.
</ParamField>

<ParamField body="node_options" type="list of strings" default={`[]`}>
  Options to pass to the node invocation on the command line.

  [https://nodejs.org/api/cli.html](https://nodejs.org/api/cli.html)

  These options are passed directly to the node invocation on the command line.
  Options passed here will take precendence over options passed via
  the NODE\_OPTIONS environment variable. Options passed here are not added
  to the NODE\_OPTIONS environment variable so will not be automatically
  picked up by child processes that inherit that environment variable.
</ParamField>

<ParamField body="expected_exit_code" type="integer" default={`0`}>
  The expected exit code.

  Can be used to write tests that are expected to fail.
</ParamField>

<ParamField body="log_level" type="string" default={`error`}>
  Set the logging level.

  Log from are written to stderr. They will be suppressed on success when running as the tool
  of a js\_run\_binary when silent\_on\_success is True. In that case, they will be shown
  only on a build failure along with the stdout & stderr of the node tool being run.

  Log levels: fatal, error, warn, info, debug
</ParamField>

<ParamField body="patch_node_fs" type="boolean" default={`True`}>
  Patch the to Node.js `fs` API ([https://nodejs.org/api/fs.html](https://nodejs.org/api/fs.html)) for this node program
  to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.

  When enabled, `js_binary` patches the Node.js sync and async `fs` API functions `lstat`,
  `readlink`, `realpath`, `readdir` and `opendir` so that the node program being
  run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox,
  these patches prevent the program being run from resolving symlinks out of the sandbox.

  When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks
  which can lead to non-hermetic behavior.
</ParamField>

<ParamField body="include_sources" type="boolean" default={`True`}>
  When True, `sources` from `JsInfo` providers in `data` targets are included in the runfiles of the target.
</ParamField>

<ParamField body="include_transitive_sources" type="boolean" default={`True`}>
  When True, `transitive_sources` from `JsInfo` providers in `data` targets are included in the runfiles of the target.
</ParamField>

<ParamField body="include_types" type="boolean" default={`False`}>
  When True, `types` from `JsInfo` providers in `data` targets are included in the runfiles of the target.

  Defaults to False since types are generally not needed at runtime and introducing them could slow down developer round trip
  time due to having to generate typings on source file changes.

  NB: These are types from direct `data` dependencies only. You may also need to set `include_transitive_types` to True.
</ParamField>

<ParamField body="include_transitive_types" type="boolean" default={`False`}>
  When True, `transitive_types` from `JsInfo` providers in `data` targets are included in the runfiles of the target.

  Defaults to False since types are generally not needed at runtime and introducing them could slow down developer round trip
  time due to having to generate typings on source file changes.
</ParamField>

<ParamField body="include_npm_sources" type="boolean" default={`True`}>
  When True, files in `npm_sources` from `JsInfo` providers in `data` targets are included in the runfiles of the target.

  `transitive_files` from `NpmPackageStoreInfo` providers in `data` targets are also included in the runfiles of the target.
</ParamField>

<ParamField body="preserve_symlinks_main" type="boolean" default={`True`}>
  When True, the --preserve-symlinks-main flag is passed to node.

  This prevents node from following an ESM entry script out of runfiles and the sandbox. This can happen for `.mjs`
  ESM entry points where the fs node patches, which guard the runfiles and sandbox, are not applied.
  See [https://github.com/aspect-build/rules\_js/issues/362](https://github.com/aspect-build/rules_js/issues/362) for more information. Once #362 is resolved,
  the default for this attribute can be set to False.

  This flag was added in Node.js v10.2.0 (released 2018-05-23). If your node toolchain is configured to use a
  Node.js version older than this you'll need to set this attribute to False.

  See [https://nodejs.org/api/cli.html#--preserve-symlinks-main](https://nodejs.org/api/cli.html#--preserve-symlinks-main) for more information.
</ParamField>

<ParamField body="no_copy_to_bin" type="list of labels" default={`[]`}>
  List of files to not copy to the Bazel output tree when `copy_data_to_bin` is True.

  This is useful for exceptional cases where a `copy_to_bin` is not possible or not suitable for an input
  file such as a file in an external repository. In most cases, this option is not needed.
  See `copy_data_to_bin` docstring for more info.
</ParamField>

<ParamField body="copy_data_to_bin" type="boolean" default={`True`}>
  When True, `data` files and the `entry_point` file are copied to the Bazel output tree before being passed
  as inputs to runfiles.

  Defaults to True so that a `js_binary` with the default value is compatible with `js_run_binary` with
  `use_execroot_entry_point` set to True, the default there.

  Setting this to False is more optimal in terms of inputs, but there is a yet unresolved issue of ESM imports
  skirting the node fs patches and escaping the sandbox: [https://github.com/aspect-build/rules\_js/issues/362](https://github.com/aspect-build/rules_js/issues/362).
  This is hit in some popular test runners such as mocha, which use native `import()` statements
  ([https://github.com/aspect-build/rules\_js/pull/353](https://github.com/aspect-build/rules_js/pull/353)). When set to False, a program such as mocha that uses ESM
  imports may escape the execroot by following symlinks into the source tree. When set to True, such a program
  would escape the sandbox but will end up in the output tree where `node_modules` and other inputs required
  will be available.
</ParamField>

<ParamField body="include_npm" type="boolean" default={`False`}>
  When True, npm is included in the runfiles of the target.

  An npm binary is also added on the PATH so tools can spawn npm processes. This is a bash script
  on Linux and MacOS and a batch script on Windows.

  A minimum of rules\_nodejs version 5.7.0 is required which contains the Node.js toolchain changes
  to use npm.
</ParamField>

<ParamField body="node_toolchain" type="label" default={`None`}>
  The Node.js toolchain to use for this target.

  See [https://bazelbuild.github.io/rules\_nodejs/Toolchains.html](https://bazelbuild.github.io/rules_nodejs/Toolchains.html)

  Typically this is left unset so that Bazel automatically selects the right Node.js toolchain
  for the target platform. See [https://bazel.build/extending/toolchains#toolchain-resolution](https://bazel.build/extending/toolchains#toolchain-resolution)
  for more information.
</ParamField>

<ParamField body="junit_reporter" type="label" default={`None`} />

<ParamField body="config" type="label" default={`None`} />

## Function: `jasmine_test`

Runs jasmine under `bazel test`

### 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 jasmine is linked, e.g. `//:node_modules`.

  `jasmine` must be linked into the node\_modules supplied.
  `jasmine-reporters` is also required by default when jasmine\_reporters is True
  `jasmine-core` is required when using sharding.
</ParamField>

<ParamField body="jasmine_reporters" type="unknown" default={`True`}>
  Whether `jasmine-reporters` is present in the supplied node\_modules tree.

  When enabled, adds a custom reporter to output junit XML to the path where Bazel expects to find it.
</ParamField>

<ParamField body="config" type="unknown" default={`None`}>
  jasmine config file. See: [https://jasmine.github.io/setup/nodejs.html#configuration](https://jasmine.github.io/setup/nodejs.html#configuration)
</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="data" type="unknown" default={`[]`}>
  Runtime dependencies that Jasmine should be able to read.

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

<ParamField body="kwargs" type="unknown">
  Additional named parameters from `js_test`.
  See [js\_test docs](https://github.com/aspect-build/rules_js/blob/main/docs/js_binary.md#js_test)
</ParamField>