From 66c22f896bb0880c6a415c14126614f76f4e0735 Mon Sep 17 00:00:00 2001
From: Maxime Beauchemin <maximebeauchemin@gmail.com>
Date: Fri, 17 Jan 2025 16:55:07 -0800
Subject: [PATCH] docs: clarify port configuration for Cypress (#31916)

---
 docs/docs/contributing/howtos.mdx | 37 +++++++++++++++++++------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/docs/docs/contributing/howtos.mdx b/docs/docs/contributing/howtos.mdx
index 3269da393..97626de0a 100644
--- a/docs/docs/contributing/howtos.mdx
+++ b/docs/docs/contributing/howtos.mdx
@@ -228,23 +228,35 @@ npm run test -- path/to/file.js
 For e2e testing, we recommend that you use a `docker compose` backend
 
 ```bash
-CYPRESS_CONFIG=true docker compose up
+CYPRESS_CONFIG=true docker compose up --build
+```
+`docker compose` will get to work and expose a Cypress-ready Superset app.
+This app uses a different database schema (`superset_cypress`) to keep it isolated from
+your other dev environmen(s)t, a specific set of examples, and a set of configurations that
+aligns with the expectations within the end-to-end tests.  Also note that it's served on a
+different port than the default port for the backend (`8088`).
+
+Now in another terminal, let's get ready to execute some Cypress commands. First, tell cypress
+to connect to the Cypress-ready Superset backend.
+
+```
+CYPRESS_BASE_URL=http://localhost:8081
 ```
 
-In another terminal, prepare the frontend and run Cypress tests:
-
 ```bash
-cd superset-frontend
-npm run build-instrumented
-
-cd cypress-base
+# superset-frontend/cypress-base is the base folder for everything Cypress-related
+# It's essentially its own npm app, with its own dependencies, configurations and utilities
+cd superset-frontend/cypress-base
 npm install
 
-# run tests via headless Chrome browser (requires Chrome 64+)
-npm run cypress-run-chrome
+# use interactive mode to run tests, while keeping memory usage contained
+# this will fire up an interactive Cypress UI
+# as you alter the code, the tests will re-run automatically, and you can visualize each
+# and every step for debugging purposes
+npx cypress open --config numTestsKeptInMemory=5
 
-# use interactive mode to run tests, while keeping memory usage contained (default is 50!)
-npx cypress open --config numTestsKeptInMemory=3
+# to run the test suite on the command line using chrome (same as CI)
+npm run cypress-run-chrome
 
 # run tests from a specific file
 npm run cypress-run-chrome -- --spec cypress/e2e/explore/link.test.ts
@@ -255,9 +267,6 @@ npm run cypress-run-chrome -- --spec cypress/e2e/dashboard/index.test.js --confi
 # to open the cypress ui
 npm run cypress-debug
 
-# to point cypress to a url other than the default (http://localhost:8088) set the environment variable before running the script
-# e.g., CYPRESS_BASE_URL="http://localhost:9000"
-CYPRESS_BASE_URL=<your url> npm run cypress open
 ```
 
 See [`superset-frontend/cypress_build.sh`](https://github.com/apache/superset/blob/master/superset-frontend/cypress_build.sh).