Build & Test

Testing

The test task runs a bazel test target.

info

By default, the test task also builds all build-able targets.

The simplest configuration:

.aspect/workflows/config.yaml

tasks:
    - test:

This runs all tests in the workspace, for example bazel test //....

You can specify target with the targets attribute, which is a list of patterns:

.aspect/workflows/config.yaml

tasks:
  - test:
      name: "Test Foo"
      targets:
        - //foo/...

You can specify multiple test tasks:

.aspect/workflows/config.yaml

tasks:
  - test:
      name: "Test Foo"
      targets:
        - //foo/...
  - test:
      name: "Test Bar"
      targets:
        - //bar/...

note

Prefix the pattern with - to exclude targets.

.aspect/workflows/config.yaml

tasks:
    - test:
        targets:
            # All targets in project A
            - //projectA/...
            # But excluding this subpackage
            - -//projectA/excluded:all

You can also specify additional Bazel flags for the task.

Enabling coverage

Workflows doesn't run bazel coverage due to historical bugs with invalidating the analysis cache. Instead, bazel test runs with specific flags that have equivalent behavior.

To enable coverage on a test task, add coverage: true to the task configuration:

.aspect/workflows/config.yaml

tasks:
    - test:
        coverage: true

Building

A build task runs a bazel build task.

caution

By default, the test task also builds all build-able targets, so a typical configuration file does not use the build task.

There are a few cases where a build task is useful:

1. When the --build_tests_only flag is passed to Bazel, then the test task does not build targets which aren't a dependency of any tests.
2. Some test targets may be known to be broken. You can use a build task to only build the tests, but not run them.

A simple configuration looks like:

.aspect/workflows/config.yaml

tasks:
    - build:

This builds all targets in the workspace, for example bazel build //....

You can specify target with the targets attribute, which is a list of patterns:

.aspect/workflows/config.yaml

tasks:
  - build:
      name: "Build Fum"
      targets:
        - //fum/...

You can specify multiple build tasks:

.aspect/workflows/config.yaml

tasks:
  - build:
      name: "Build Fum"
      targets:
        - //fum/...
  - build:
      name: "Build Far"
      targets:
        - //far/...

note

Prefix the pattern with - to exclude targets.

.aspect/workflows/config.yaml

tasks:
    - build:
        targets:
            # All targets in project A
            - //projectA/...
            # But excluding this subpackage
            - -//projectA/excluded:all

Specifying Bazel flags

You should generally check Bazel flags into a .bazelrc file. Workflows looks for a .aspect/workflows/bazelrc file, and if it exists then Workflows passes --bazelrc=.aspect/workflows/bazelrc to every invocation of Bazel.

You can also place flags in the configuration file, at the top-level or under a task:

.aspect/workflows/config.yaml

bazel:
    flags:
        # Allow any actions to see the value of $HOME
        - --action_env=HOME
tasks:
    - test:
        bazel:
            flags:
                # Allow any actions to see the value of $HOME
                - --action_env=HOME
                # Allow tests to fetch private container images from Docker Hub
                - --test_env=DOCKER_USERNAME
                - --test_env=DOCKER_PASSWORD

caution

Workflows doesn't merge task level flags with top-level flags. Instead, Bazel flags specified for a task overrides the list of Bazel flags set at the top-level level.

info

Setting bes_backend

Bazel doesn't support multiple bes_backends and Workflows takes the default spot. You can set the value to another backend to let the Aspect CLI (running the Workflows runners) know that it should forward the BES onto that endpoint.

For an individual task:

tasks:
    - test:
      bazel:
        flags:
          - --bes_backend=grpcs://<url>

Or on the top level to apply to all tasks:

bazel:
  flags:
    - --bes_backend=grpcs://<url>
tasks:

Specifying Bazel start-up flags

You should generally check startup flags into a .bazelrc file, however, some startup flags such as --noworkspace_rc may only be specified as command line flags.

As with regular flags, you can also place startup flags in the configuration file, at the top-level or under a task:

.aspect/workflows/config.yaml

bazel:
    startup_flags:
        # Ignore the WORKSPACE .bazelrc file on CI
        - --noworkspace_rc
tasks:
    - test:
        bazel:
            startup_flags:
                # Ignore the WORKSPACE .bazelrc file on CI
                - --noworkspace_rc
                # Increase maximum JVM heap size for the bazel server
                - --host_jvm_args=-Xmx12g

caution

Task level startup flags are not merged with top-level startup flags. Instead, Bazel startup flags specified for a task overrides the list of Bazel startup flags set at the top-level level.

API doc

You can find the exhaustive list of attributes for the build task in build, and for the test task in test.