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(