Build & Test

Building

A build task runs bazel build.

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

There are a few cases where a build task can be useful:

1. When the --build_tests_only flag is passed to Bazel, then the test task will not build targets which aren't a dependency of any tests.
2. Some test targets may be known to be broken. A build task can be used 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 //.... Specific targets may be selected with the targets attribute, which is a list of patterns:

.aspect/workflows/config.yaml

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

Testing

The test task runs bazel test.

The simplest configuration:

.aspect/workflows/config.yaml

tasks:
    - test:

This will run all tests in the workspace, for example bazel test //.... As for build, specific targets may be selected with the targets attribute.

.aspect/workflows/config.yaml

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

Setting flags for the test task is the same as for build, see Specifying flags.

Enabling coverage

Workflows doesn't run bazel coverage due to some historical bugs with invalidating the analysis cache. Instead, bazel test is run 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

Specifying Bazel flags

Bazel flags should generally be checked 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.

Flags can also be placed in the configuration file. They may go at the top-level and also 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

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

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

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

As with regular flags, startup flags can also be placed in the configuration file. They may go at the top-level and also 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

The exhaustive list of attributes for the build task are found at build, and for the test task at test.