From db50b5e3198071eb9836b4ff9b2ac6263cbea1dc Mon Sep 17 00:00:00 2001
From: Paul Draper
Date: Wed, 2 May 2018 23:25:47 -0700
Subject: Document test sharding and --test_filter for test runners
Learnings gathered from JunitRunner (in implementing https://github.com/andyscott/rules_scala_annex/pull/38)
Closes #5041.
PiperOrigin-RevId: 195206493
---
site/docs/test-encyclopedia.html | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
(limited to 'site/docs/test-encyclopedia.html')
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
index 1c2c126eda..ddfcd4fd2c 100644
--- a/site/docs/test-encyclopedia.html
+++ b/site/docs/test-encyclopedia.html
@@ -162,6 +162,23 @@ tests whose specified size is too big.
Any test that does not specify a recognized size will default to being a medium
test.
+Tests can be parallelized via test sharding. See
+--test_sharding_strategy
+and
+shard_count
+to enable test sharding. When sharding is enabled, the test runner is launched
+once per shard. The environment variable
+TEST_TOTAL_SHARDS
is the number
+of shards, and
+TEST_SHARD_INDEX
is the shard
+index, beginning at 1. Runners use this information to select which tests to
+run - for example, using a round-robin strategy. Not all test runners support sharding.
+If a runner supports sharding, it must create or update the last modified date
+of the file specified by
+TEST_SHARD_STATUS_FILE
.
+Otherwise, Bazel assumes it does not support sharding and will not launch
+additional runners.
+
If the main process of a test exits, but some of its children are still
running, the test runner should consider the run complete and count it as a
success or failure based on the exit code observed from the main process. The
@@ -216,13 +233,17 @@ test unless the user explicitly requests it.
TEST_TARGET | The name of the target being tested | optional |
TEST_SIZE | The test size | optional |
TEST_TIMEOUT | The test timeout | optional |
+ TEST_SHARD_INDEX | shard index, if sharding is used | optional |
+ TEST_SHARD_STATUS_FILE | path to file to touch to indicate support for sharding | optional |
TEST_SRCDIR | absolute path to the base of the runfiles tree | required |
+ TEST_TOTAL_SHARDS | total shard count, if sharding is used | optional |
TEST_TMPDIR | absolute path to a private writable directory | required |
TEST_UNDECLARED_OUTPUTS_DIR | absolute path to a private writable directory (used to write undeclared test outputs) | optional |
TEST_UNDECLARED_OUTPUTS_ANNOTATIONS_DIR | absolute path to a private writable directory (used to write undeclared test output annotation .part files).
| optional |
TEST_WARNINGS_OUTPUT_FILE | absolute path to a private file in a writable directory (used to write test target warnings) | optional |
+ TESTBRIDGE_TEST_ONLY | value of --test_filter , if specified | optional |
TZ | UTC | required |
USER | value of getpwuid(getuid())->pw_name | required |
--
cgit v1.2.3