[Docs] Confusing (and possible misleading / wrong) documentation around `local` test rule attribute
- 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
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