test(firestore): retry failed system tests

handwritten/firestore/.mocharc.js

@@ -15,7 +15,11 @@ const config = {
   "enable-source-maps": true,
   "throw-deprecation": true,
   "timeout": 10000,
-  "recursive": true
+  "recursive": true,
+  // Number of times to retry a failed test.
+  "retries": Number(process.env.TEST_RETRIES) || 0,
+  // Logs retried tests.
+  "require": [require.resolve('./scripts/mocha-retry.js')]
 }
 if (process.env.MOCHA_THROW_DEPRECATION === 'false') {
   delete config['throw-deprecation'];

handwritten/firestore/cloudbuild.yaml

@@ -28,6 +28,8 @@ steps:
   env:
   - 'GCLOUD_PROJECT=${_GCP_PROJECT_ID}' # Pass project ID via build variable
   - 'FIRESTORE_DATABASE_ID=firestore-standard'
+  # Retry failing tests up to 3 times.
+  - 'TEST_RETRIES=3'
   id: 'run-system-tests'
   waitFor: ['install-dependencies']
   # For Secret Manager, uncomment these (adjust secret name and volume path as needed):

handwritten/firestore/scripts/mocha-retry.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Mocha root hook plugin, loaded by .mocharc.js when TEST_RETRIES is set. Mocha
+// reports a test that passes on a retry as a plain pass, so log the retries to
+// keep flaky tests visible.
+
+exports.mochaHooks = {
+  beforeEach() {
+    const test = this.currentTest;
+    // 0 on a test's first attempt, so anything higher means this is a retry.
+    const retry = test.currentRetry();
+    if (retry > 0) {
+      console.log(
+        `  [retry] attempt ${retry + 1}/${test.retries() + 1}: ${test.fullTitle()}`,
+      );
+    }
+  },
+};