Clarify documentation of runs_per_test and flaky_test_attempts
In discussing unknown commit, the behaviors of these flags were reverse engineered. Update the documentation to reflect what those behaviors actually are.
The documentation of flaky_test_attempts was re-templated to be closer to the documentation for runs_per_test.
PiperOrigin-RevId: 305689092
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/test/TestConfiguration.java b/src/main/java/com/google/devtools/build/lib/analysis/test/TestConfiguration.java
index 9418f63..8651357 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/test/TestConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/test/TestConfiguration.java
@@ -177,25 +177,23 @@
public boolean persistentTestRunner;
@Option(
- name = "runs_per_test",
- allowMultiple = true,
- defaultValue = "1",
- converter = RunsPerTestConverter.class,
- documentationCategory = OptionDocumentationCategory.TESTING,
- effectTags = {OptionEffectTag.UNKNOWN},
- help =
- "Specifies number of times to run each test. If any of those attempts "
- + "fail for any reason, the whole test would be considered failed. "
- + "Normally the value specified is just an integer. Example: --runs_per_test=3 "
- + "will run all tests 3 times. "
- + "Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for "
- + "an integer value and regex_filter stands "
- + "for a list of include and exclude regular expression patterns (Also see "
- + "--instrumentation_filter). Example: "
- + "--runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ "
- + "except those under foo/bar three times. "
- + "This option can be passed multiple times. "
- )
+ name = "runs_per_test",
+ allowMultiple = true,
+ defaultValue = "1",
+ converter = RunsPerTestConverter.class,
+ documentationCategory = OptionDocumentationCategory.TESTING,
+ effectTags = {OptionEffectTag.UNKNOWN},
+ help =
+ "Specifies number of times to run each test. If any of those attempts fail for any"
+ + " reason, the whole test is considered failed. Normally the value specified is"
+ + " just an integer. Example: --runs_per_test=3 will run all tests 3 times."
+ + " Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for"
+ + " an integer value and regex_filter stands for a list of include and exclude"
+ + " regular expression patterns (Also see --instrumentation_filter). Example:"
+ + " --runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ except those"
+ + " under foo/bar three times. This option can be passed multiple times. The most"
+ + " recently passed argument that matches takes precedence. If nothing matches,"
+ + " the test is only run once.")
public List<PerLabelOptions> runsPerTest;
@Option(
diff --git a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
index 4c2728d..36ef517 100644
--- a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
@@ -213,21 +213,26 @@
public boolean testKeepGoing;
@Option(
- name = "flaky_test_attempts",
- allowMultiple = true,
- defaultValue = "default",
- converter = TestAttemptsConverter.class,
- documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
- effectTags = {OptionEffectTag.UNKNOWN},
- help =
- "Each test will be retried up to the specified number of times in case of any test "
- + "failure. Tests that required more than one attempt to pass would be marked as "
- + "'FLAKY' in the test summary. If this option is set, it should specify an int N or "
- + "the string 'default'. If it's an int, then all tests will be run up to N times. "
- + "If it is not specified or its value is 'default', then only a single test attempt "
- + "will be made for regular tests and three for tests marked explicitly as flaky by "
- + "their rule (flaky=1 attribute)."
- )
+ name = "flaky_test_attempts",
+ allowMultiple = true,
+ defaultValue = "default",
+ converter = TestAttemptsConverter.class,
+ documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+ effectTags = {OptionEffectTag.UNKNOWN},
+ help =
+ "Each test will be retried up to the specified number of times in case of any test"
+ + " failure. Tests that required more than one attempt to pass are marked as 'FLAKY'"
+ + " in the test summary. Normally the value specified is just an integer or the"
+ + " string 'default'. If an integer, then all tests will be run up to N times. If"
+ + " 'default', then only a single test attempt will be made for regular tests and"
+ + " three for tests marked explicitly as flaky by their rule (flaky=1 attribute)."
+ + " Alternate syntax: regex_filter@flaky_test_attempts. Where flaky_test_attempts is"
+ + " as above and regex_filter stands for a list of include and exclude regular"
+ + " expression patterns (Also see --runs_per_test). Example:"
+ + " --flaky_test_attempts=//foo/.*,-//foo/bar/.*@3 deflakes all tests in //foo/"
+ + " except those under foo/bar three times. This option can be passed multiple"
+ + " times. The most recently passed argument that matches takes precedence. If"
+ + " nothing matches, behavior is as if 'default' above.")
public List<PerLabelOptions> testAttempts;
@Option(
