From c853257d54c2056bb2dd08ba5d3798300daaaf61 Mon Sep 17 00:00:00 2001
From: Andy Balaam <andy.balaam@matrix.org>
Date: Tue, 5 Sep 2023 12:55:53 +0100
Subject: [PATCH] Document how to match the CI config for Cypress (#11531)

* Document how to match the CI config for Cypress

* Clarify language about needing Chrome

* Move Cypress info into the Cypress-specific docs
---
 README.md       |  6 ++----
 docs/cypress.md | 29 ++++++++++++++++++++++++-----
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 9916bcb928..716a084efd 100644
--- a/README.md
+++ b/README.md
@@ -209,7 +209,5 @@ Now the yarn commands should work as normal.
 
 ### End-to-End tests
 
-Make sure you've got your Element development server running (by doing `yarn
-start` in element-web), and then in this project, run `yarn run test:cypress`. See
-[`docs/cypress.md`](https://github.com/matrix-org/matrix-react-sdk/blob/develop/docs/cypress.md)
-for more information.
+We use Cypress and Element Web for end-to-end tests. See
+[`docs/cypress.md`](docs/cypress.md) for more information.
diff --git a/docs/cypress.md b/docs/cypress.md
index 53c50877ea..3ef251e9a9 100644
--- a/docs/cypress.md
+++ b/docs/cypress.md
@@ -1,11 +1,8 @@
 # Cypress in Element Web
 
-## Scope of this Document
+## Contents
 
-This doc is about our Cypress tests in Element Web and how we use Cypress to write tests.
-It aims to cover:
-
--   How to run the tests yourself
+-   How to run the tests
 -   How the tests work
 -   How to write great Cypress tests
 -   Visual testing
@@ -45,6 +42,28 @@ To launch it:
 yarn run test:cypress:open
 ```
 
+### Matching the CI environment
+
+In our Continuous Integration environment, we run the Cypress tests in the
+Chrome browser.
+
+In some rare cases, tests behave differently between different browsers, so if
+you see CI failures for the Cypress tests, but those tests work OK on your local
+machine, try running them in Chrome like this:
+
+```bash
+yarn run test:cypress --browser=chrome
+```
+
+(Use `--browser=chromium` if you'd prefer to use Chromium.)
+
+If you launch the interactive UI you can choose the browser you want to use. To
+match the CI setup, choose Chrome.
+
+Note that you will need to have Chrome installed on your system to run the tests
+inside those browsers, whereas the default is to use Electron, which is included
+within the Cypress dependency.
+
 ### Running with Rust cryptography
 
 `matrix-js-sdk` is currently in the