From a4a70eb81b7abe4bcf3eb2a739b071f3885c4df0 Mon Sep 17 00:00:00 2001
From: Michael Telatynski <7t3chguy@gmail.com>
Date: Wed, 12 Jul 2023 15:57:01 +0100
Subject: [PATCH] Document `@media only percy` (#11244)

---
 docs/cypress.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/cypress.md b/docs/cypress.md
index d66c9675cf..53c50877ea 100644
--- a/docs/cypress.md
+++ b/docs/cypress.md
@@ -230,3 +230,10 @@ having to figure it out later after the nightly build. If you don't have
 permission to add a label, please ask your reviewer to do it. Note: it's best to
 add this label when the change is nearly ready, because the screenshots will be
 re-created every time you make a change to your PR.
+
+Some UI elements render differently between test runs, such as BaseAvatar when
+there is no avatar set, choosing a colour from the theme palette based on the
+hash of the user/room's Matrix ID. To avoid this creating flaky tests we can use
+the `@media only percy` CSS query to override the variable colour into a fixed one
+for tests where it is not feasible to fix the underlying identifiers issued by the
+server. See https://docs.percy.io/docs/percy-specific-css#percy-css-media-query.