Executing programs
Bazel

Executing programs


Overview

These rules run the node binary with the given sources.

They support module mapping: any targets in the transitive dependencies with a module_name attribute can be required by that name.


nodejs_binary_macro

nodejs_binary_macro(name, data, args, visibility, tags, testonly, **kwargs)

This macro exists only to wrap the nodejs_binary as an .exe for Windows.

This is exposed in the public API at //:defs.bzl as nodejs_binary, so most users loading nodejs_binary are actually executing this macro.

Attributes

name

Name; Required

name of the label

data

List of strings; Optional

runtime dependencies

args

List of strings; Optional

applied to the wrapper binary

visibility

Unknown; Optional

applied to the wrapper binary

tags

List of strings; Optional

applied to the wrapper binary

testonly

Integer; Optional

applied to nodejs_binary and wrapper binary

**kwargs

Unknown; Optional

passed to the nodejs_binary


nodejs_test_macro

nodejs_test_macro(name, data, args, visibility, tags, **kwargs)

This macro exists only to wrap the nodejs_test as an .exe for Windows.

This is exposed in the public API at //:defs.bzl as nodejs_test, so most users loading nodejs_test are actually executing this macro.

Attributes

name

Name; Required

name of the label

data

List of strings; Optional

runtime dependencies

args

List of strings; Optional

applied to the wrapper binary

visibility

Unknown; Optional

applied to the wrapper binary

tags

List of strings; Optional

applied to the wrapper binary

**kwargs

Unknown; Optional

passed to the nodejs_test


nodejs_binary

nodejs_binary(name, data, bootstrap, configuration_env_vars, entry_point, install_source_map_support, node, node_modules, templated_args)

Runs some JavaScript code in NodeJS.

Attributes

name

Name; Required

A unique name for this rule.

data

List of labels; Optional; Default is []

Runtime dependencies which may be loaded during execution.

bootstrap

List of strings; Optional; Default is []

JavaScript modules to be loaded before the entry point. For example, Angular uses this to patch the Jasmine async primitives for zone.js before the first describe.

configuration_env_vars

List of strings; Optional; Default is []

Pass these configuration environment variables to the resulting binary. Chooses a subset of the configuration environment variables (taken from ctx.var), which also includes anything specified via the --define flag. Note, this can lead to different outputs produced by this rule.

entry_point

String; Required

The script which should be executed first, usually containing a main function. This attribute expects a string starting with the workspace name, so that it's not ambiguous in cases where a script with the same name appears in another directory or external workspace.

install_source_map_support

Boolean; Optional; Default is True

Install the source-map-support package. Enable this to get stack traces that point to original sources, e.g. if the program was written in TypeScript.

node

Label; Optional; Default is @nodejs//:node

The node entry point target.

node_modules

Label; Optional; Default is //:node_modules_none

The npm packages which should be available to require() during execution.

    This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
    to npm dependencies is to use fine grained npm dependencies which are setup
    with the `yarn_install` or `npm_install` rules. For example, in targets
    that used a `//:node_modules` filegroup,

    ```
    nodejs_binary(
      name = "my_binary",
      ...
      node_modules = "//:node_modules",
    )
    ```

    which specifies all files within the `//:node_modules` filegroup
    to be inputs to the `my_binary`. Using fine grained npm dependencies,
    `my_binary` is defined with only the npm dependencies that are
    needed:

    ```
    nodejs_binary(
      name = "my_binary",
      ...
      data = [
          "@npm//foo",
          "@npm//bar",
          ...
      ],
    )
    ```

    In this case, only the `foo` and `bar` npm packages and their
    transitive deps are includes as inputs to the `my_binary` target
    which reduces the time required to setup the runfiles for this
    target (see https://github.com/bazelbuild/bazel/issues/5153).

    The @npm external repository and the fine grained npm package
    targets are setup using the `yarn_install` or `npm_install` rule
    in your WORKSPACE file:

    yarn_install(
      name = "npm",
      package_json = "//:package.json",
      yarn_lock = "//:yarn.lock",
    )

    For other rules such as `jasmine_node_test`, fine grained
    npm dependencies are specified in the `deps` attribute:

    ```
    jasmine_node_test(
        name = "my_test",
        ...
        deps = [
            "@npm//jasmine",
            "@npm//foo",
            "@npm//bar",
            ...
        ],
    )
    ```
templated_args

List of strings; Optional; Default is []

Arguments which are passed to every execution of the program. To pass a node startup option, prepend it with --node_options=, e.g. --node_options=--preserve-symlinks


nodejs_test

nodejs_test(name, data, bootstrap, configuration_env_vars, entry_point, expected_exit_code, install_source_map_support, node, node_modules, templated_args)

Identical to nodejs_binary, except this can be used with bazel test as well. When the binary returns zero exit code, the test passes; otherwise it fails.

nodejs_test is a convenient way to write a novel kind of test based on running your own test runner. For example, the ts-api-guardian library has a way to assert the public API of a TypeScript program, and uses nodejs_test here: https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl

If you just want to run a standard test using a test runner like Karma or Jasmine, use the specific rules for those test runners, e.g. jasmine_node_test.

To debug a Node.js test, we recommend saving a group of flags together in a "config". Put this in your tools/bazel.rc so it's shared with your team:

# Enable debugging tests with --config=debug
test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results

Now you can add --config=debug to any bazel test command line. The runtime will pause before executing the program, allowing you to connect a remote debugger.

Attributes

name

Name; Required

A unique name for this rule.

data

List of labels; Optional; Default is []

Runtime dependencies which may be loaded during execution.

bootstrap

List of strings; Optional; Default is []

JavaScript modules to be loaded before the entry point. For example, Angular uses this to patch the Jasmine async primitives for zone.js before the first describe.

configuration_env_vars

List of strings; Optional; Default is []

Pass these configuration environment variables to the resulting binary. Chooses a subset of the configuration environment variables (taken from ctx.var), which also includes anything specified via the --define flag. Note, this can lead to different outputs produced by this rule.

entry_point

String; Required

The script which should be executed first, usually containing a main function. This attribute expects a string starting with the workspace name, so that it's not ambiguous in cases where a script with the same name appears in another directory or external workspace.

expected_exit_code

Integer; Optional; Default is 0

The expected exit code for the test. Defaults to 0.

install_source_map_support

Boolean; Optional; Default is True

Install the source-map-support package. Enable this to get stack traces that point to original sources, e.g. if the program was written in TypeScript.

node

Label; Optional; Default is @nodejs//:node

The node entry point target.

node_modules

Label; Optional; Default is //:node_modules_none

The npm packages which should be available to require() during execution.

    This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
    to npm dependencies is to use fine grained npm dependencies which are setup
    with the `yarn_install` or `npm_install` rules. For example, in targets
    that used a `//:node_modules` filegroup,

    ```
    nodejs_binary(
      name = "my_binary",
      ...
      node_modules = "//:node_modules",
    )
    ```

    which specifies all files within the `//:node_modules` filegroup
    to be inputs to the `my_binary`. Using fine grained npm dependencies,
    `my_binary` is defined with only the npm dependencies that are
    needed:

    ```
    nodejs_binary(
      name = "my_binary",
      ...
      data = [
          "@npm//foo",
          "@npm//bar",
          ...
      ],
    )
    ```

    In this case, only the `foo` and `bar` npm packages and their
    transitive deps are includes as inputs to the `my_binary` target
    which reduces the time required to setup the runfiles for this
    target (see https://github.com/bazelbuild/bazel/issues/5153).

    The @npm external repository and the fine grained npm package
    targets are setup using the `yarn_install` or `npm_install` rule
    in your WORKSPACE file:

    yarn_install(
      name = "npm",
      package_json = "//:package.json",
      yarn_lock = "//:yarn.lock",
    )

    For other rules such as `jasmine_node_test`, fine grained
    npm dependencies are specified in the `deps` attribute:

    ```
    jasmine_node_test(
        name = "my_test",
        ...
        deps = [
            "@npm//jasmine",
            "@npm//foo",
            "@npm//bar",
            ...
        ],
    )
    ```
templated_args

List of strings; Optional; Default is []

Arguments which are passed to every execution of the program. To pass a node startup option, prepend it with --node_options=, e.g. --node_options=--preserve-symlinks