bazelbuild / bazelbuild/bazel

[Docs] Confusing (and possible misleading / wrong) documentation around `local` test rule attribute

Open
#30,180 0 comments 0 reactions 0 assignees View on GitHub
P3 team-Documentation team-Local-Exec type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

### Page link:

_No response_

### Problem description (include actual vs expected text, if applicable):

According to `https://bazel.build/reference/be/common-definitions#common-attributes-tests`:

> **local**
> Boolean; nonconfigurable; default is `False`
>
> Forces the test to be run locally, without sandboxing.
>
> Setting this to True is equivalent to providing "local" as a tag (`tags=["local"]`).

and then `https://bazel.build/reference/be/common-definitions#common-attributes`:

> **tags**
> List of strings; [nonconfigurable](https://bazel.build/reference/be/common-definitions#configurable-attributes); default is []
>
> Tags can be used on any rule. Tags on test and test_suite rules are useful for categorizing the tests. Tags on non-test targets are used to control sandboxed execution of genrules and [Starlark](https://bazel.build/rules/concepts) actions, and for parsing by humans and/or external tools.
>
> ...
> **local** keyword precludes the action or test from being remotely cached, remotely executed, or run inside the sandbox. For genrules and tests, marking the rule with the `local = True` attribute has the same effect.
> ...

Maybe this is true for `genrule`s, but I don't think this holds more generally? Specifically, in the case of `java_test`, I believe there's a crucial semantic difference between `local = True` and `tags = ["local"]`:

- `tags = ["local"]` - the `java_test` will build and run locally; specifically, compiling and building the JAR will not be cached or use a remote executor
- `local = True` - the `java_test` will run locally, but may still build remotely or be cached.

I assume that the observed behaviour here is correct (at least, I _hope_ it is because it'd be really annoying to not have the granularity of building tests remotely and running them locally!) but it feels like the documentation should make this distinction clear?

### Where do you see this issue? (include link to specific section of the page, if applicable)

https://bazel.build/reference/be/common-definitions

### Any other information you'd like to share?

I assume this applies to more than just `java_test` but I've not tested any other type of rule that has both a "build" and a "test" phase for the test target.

Contributor guide

Open the contributing guide

Research direction

Start with the two linked sections of the Bazel common-attributes documentation and compare the descriptions of the local attribute and local tag. Verify the reported behavior for java_test, then update the documentation so the distinction between building and running tests, including caching and remote execution, is explicit and its scope is clear.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
build-system, documentation, testing-qa
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.