From d6a123f7d15bb4391796b0fe1950e3b47839e707 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Mon, 8 Dec 2025 13:45:06 -0500
Subject: [PATCH] docs(testing): add a note on flaky tests to usage
 instructions

---
 docs/core/testing/usage-instructions.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/docs/core/testing/usage-instructions.md b/docs/core/testing/usage-instructions.md
index 66564468a44..cccac3b8a55 100644
--- a/docs/core/testing/usage-instructions.md
+++ b/docs/core/testing/usage-instructions.md
@@ -186,7 +186,21 @@ test.describe.only('group of tests', () => {
 > [!IMPORTANT]
 > After debugging, make sure to remove the `.only` suffix to ensure all tests run again during normal execution.
 
-#### 3. Pausing Test Execution
+#### 3. Repeating Tests to Reproduce Flaky Failures
+
+Flaky tests may not fail consistently. To help reproduce intermittent failures locally, you can use Playwright's `--repeat-each` flag to run the same test multiple times in a row.
+
+This is especially useful when CI reports a failure you cannot reproduce on your first local run.
+
+**Example:**
+
+```shell
+npm run test.e2e.docker.update-snapshots src/components/radio/test/a11y/radio.e2e.ts -- --repeat-each=10
+```
+
+This runs the test 10 times, increasing the chance of catching the flaky behavior.
+
+#### 4. Pausing Test Execution
 
 Additionally, you can pause execution of a test by using the `page.pause()` method. This pauses the script execution and allows you to manually inspect the page in the browser.