Buck: Document how to troubleshoot sporadic unit test failures
Change-Id: I137c8487aaab8142ac7cc581cc182b40f5621897
diff --git a/Documentation/dev-buck.txt b/Documentation/dev-buck.txt
index 42bd695..33c4e9f 100644
--- a/Documentation/dev-buck.txt
+++ b/Documentation/dev-buck.txt
@@ -478,6 +478,45 @@
EOF
----
+== Sporadic failures of unit tests
+
+In case unit tests are failing for non obvious reasons, failed tests may need
+to be repeated:
+
+----
+FAIL 32,0s 7 Passed 1 Failed com.google.gerrit.acceptance.rest.group.AddRemoveGroupMembersIT
+FAILURE includeRemoveGroup: verify: false
+com.jcraft.jsch.JSchException: verify: false
+----
+
+Because the test execution results are cached by Buck, they must be removed
+before retrying:
+
+----
+ $ rm -rf buck-out/bin/gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/rest/group/.AddRemoveGroupMembersIT/
+----
+
+After clearing the cache and repeating of the failed tests, they are successful:
+
+----
+ $ buck test //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/rest/group:AddRemoveGroupMembersIT
+ TESTING //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/rest/group:AddRemoveGroupMembersIT
+ PASS 14,9s 8 Passed 0 Failed com.google.gerrit.acceptance.rest.group.AddRemoveGroupMembersIT
+ TESTS PASSED
+----
+
+An alternative approach is to use a Buck feature:
+--test-selectors (-filters, -f) option:
+
+----
+ buck test --all -f 'com.google.gerrit.acceptance.rest.change.SubmitByMergeAlwaysIT'
+ TESTING SELECTED TESTS
+ PASS 14,5s 6 Passed 0 Failed com.google.gerrit.acceptance.rest.change.SubmitByMergeAlwaysIT
+ TESTS PASSED
+----
+
+When this option is used, cache is disabled per design and doesn't need to be deleted.
+
GERRIT
------
Part of link:index.html[Gerrit Code Review]
