From bbbc03c379898f572f4b859de2289d4b8e4882b9 Mon Sep 17 00:00:00 2001
From: "Luis H. Ball Jr" <luqven@gmail.com>
Date: Sat, 21 Nov 2020 13:04:13 -0500
Subject: [PATCH] docs(cypress): create how-to-add-cypress-tests doc (#40262)

Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>
---
 docs/_sidebar.md                   |  1 +
 docs/how-to-add-cypress-tests.md   | 43 ++++++++++++++++++++++++++++++
 docs/how-to-open-a-pull-request.md |  4 ++-
 3 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 docs/how-to-add-cypress-tests.md

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index a914bd49d7..c1470bc32b 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -11,6 +11,7 @@
 - **Optional Guides**
   - [Catch outgoing emails locally](how-to-catch-outgoing-emails-locally.md)
   - [Set up freeCodeCamp on WSL](how-to-setup-wsl.md)
+  - [Add Cypress tests](how-to-add-cypress-tests.md)
 
 ---
 
diff --git a/docs/how-to-add-cypress-tests.md b/docs/how-to-add-cypress-tests.md
new file mode 100644
index 0000000000..71350b0a08
--- /dev/null
+++ b/docs/how-to-add-cypress-tests.md
@@ -0,0 +1,43 @@
+# How to add Cypress tests
+
+When making changes to JavaScript, CSS, or HTML which could change the functionality or layout of a page, it's important to add corresponding [Cypress](https://docs.cypress.io) integration tests.
+
+To learn how to write Cypress tests, or 'specs', please see Cypress' official [documentation](https://docs.cypress.io/guides/getting-started/writing-your-first-test.html).
+
+> Note: When writing tests for freeCodeCamp, remember to add `/* global cy */` to the top of the file to avoid ESLint issues.
+
+### Where to add a test
+
+- Cypress tests are in the `./cypress` directory.
+
+- Cypress tests for a curriculum module are in the corresponding curriculum directory, i.e. `cypress/integration/learn/responsive-web-design/basic-css/index.js`.
+
+### How to run tests
+
+**1. Ensure that MongoDB and client applications are running**
+
+  - [Start MongoDB and seed the database](/how-to-setup-freecodecamp-locally#step-3-start-mongodb-and-seed-the-database)
+
+  - [Start the freeCodeCamp client application and API server](/how-to-setup-freecodecamp-locally#step-4-start-the-freecodecamp-client-application-and-api-server)
+ 
+**2. Run the cypress tests**
+
+  To run tests against production builds, replace `dev` with `prd` bellow.
+
+  - To run all tests in the `./cypress` directory:
+
+    ```console
+    npm run cypress:dev:run
+    ```
+
+  - To run a single test:
+
+    ```console 
+    npm run cypress:dev:run -- --spec=cypress/pathToYourSpec/youSpecFileName.js
+    ```
+
+  - To create a development build, start the development server, and run all existing cypress end-to-end tests:
+
+    ```console 
+    npm run e2e:dev:run
+    ```
diff --git a/docs/how-to-open-a-pull-request.md b/docs/how-to-open-a-pull-request.md
index 5b13d78720..802a7c2ff0 100644
--- a/docs/how-to-open-a-pull-request.md
+++ b/docs/how-to-open-a-pull-request.md
@@ -65,7 +65,9 @@ Some examples of good PRs titles would be:
 
 5. Indicate if you have tested on a local copy of the site or not.
 
-   This is very important when making changes that are not just edits to text content like documentation or a challenge description. Examples of changes that need local testing include JavaScript, CSS, or HTML which could change the functionality or layout of a page.
+   - This is very important when making changes that are not just edits to text content like documentation or a challenge description. Examples of changes that need local testing include JavaScript, CSS, or HTML which could change the functionality or layout of a page.
+
+   - If your PR affects the behaviour of a page it should be accompanied by corresponding [Cypress integration tests](/how-to-add-cypress-tests).
 
 ## Feedback on pull requests