Clarify test_suite behaviour in the Platforms docs

philsc · copybara-github · commit c71697cf33b0 · 2021-01-22T12:16:48.000-08:00
The current `test_suite` behaviour in regards to incompatible target skipping is subtle and not necessarily obvious. This patch aims to clear up some of the confusion. Closes bazelbuild#12870. PiperOrigin-RevId: 353293585
diff --git a/site/docs/platforms.md b/site/docs/platforms.md
@@ -156,6 +156,13 @@ $ bazel build --platforms=//:myplatform //...`
 $ bazel build --platforms=//:myplatform //:all`
 ```
 
+Incompatible tests in a [`test_suite`](be/general.html#test_suite) are
+similarly skipped if the `test_suite` is specified on the command line with
+[`--expand_test_suites`](command-line-reference.html#flag--expand_test_suites).
+In other words, `test_suite` targets on the command line behave like `:all` and
+`...`. Using `--noexpand_test_suites` prevents expansion and causes
+`test_suite` targets with incompatible tests to also be incompatible.
+
 Explicitly specifying an incompatible target on the command line results in an
 error message and a failed build.
 
