Merge pull request #1183 from FlowFuse/e2e-docs

Docs: Improve documentation on writing and running E2E tests locally

docs/contributing/widgets/testing.md

@@ -16,14 +16,65 @@ With Dashboard 2.0, we have the following commands which are used for testing:
 
 For our E2E testing we use [Cypress](https://www.cypress.io/). This provides a framework by which we can define automated tests that will click on and interact with relevant elements in our Dashboard, and check against expected behaviours.
 
+## Running Tests
+
+### Install Node-RED Testing Instance
+
+Cypress has been configured to run a local instance of Node-RED with the Dashboard 2.0 installed. You will need to install the dependencies for this instance:
+
+```bash
+cd ./cypress/fixtures/user-dir/
+npm install
+```
+
+### Running Test Server
+
+To run the test server, you will need to run the following command from the root of the repository:
+
+```bash
+npm run cy:server
+```
+
+The test server will run at `http://localhost:1881`, and any resulting Dashboard will be available at `http://localhost:1881/dashboard`.
+
+### Open Cypress
+
+To open the Cypress test runner, you will need to run the following command from the root of the repository:
+
+```bash
+npm run cy:open
+```
+
+Select "E2E Testing, and then the browser of your choice. Following this, you'll see a list of the available tests, which you can then run individually.
+
+![Screenshot showing the UI Button tests running in the Cypress Test Runner](../../assets/images/cypress-ui.png)
+_Screenshot showing the UI Button tests running in the Cypress Test Runner_
+
+
 ## Writing Tests
 
-With Node-RED and Dashboard 2.0, we want to be able to provide a complete `flow.json`, and then test the behaviour of the Dashboard that is deployed as a result of that flow. As such, each set of tests contains two key parts:
+With Node-RED and Dashboard 2.0, we want to be able to provide a complete `flow.json`, and then test the behaviour of the Dashboard that is deployed as a result of that flow.
+
+As such, each set of tests contains two key parts:
 
 1. `<widget>.json` - the `flows.json` that details the test flows to deploy, stored in `/cypress/fixtures/flows`
 2. `<widget>.spec.js` - the test suite that defines what elements to interact with and the states to test, stored in `/cypress/tests/`
 
-### Example `spec.js` file
+### 1. Building Test Flows
+
+Each test suite will have a corresponding `flows.json` file that details the flow to deploy to the local Node-RED instance. This will contain the necessary nodes to test the behaviour of the widget in question.
+
+The easiest way to build this `flow.json` is in Node-RED itself:
+
+1. Build the flow you want to test in a local Node-RED instance
+2. Export it as JSON
+3. Save the exported `json` into a `json` file within `/cypress/fixtures/flows`
+
+You may also want to make the most of the [Cypress Test Helpers](#cypress-test-helpers) too.
+
+### 2. Example `spec.js` file
+
+To reference your relevant `flow.json`, you can use the `cy.deployFixture` helper function which will load the flow into the local Node-RED instance.
 
 ```js
 describe('Node-RED Dashboard 2.0 - Button Groups', () => {
@@ -115,7 +166,7 @@ describe('Node-RED Dashboard 2.0 - Buttons', () => {
 })
 ```
 
-### Rest Context
+### Reset Context
 
 `cy.resetContext()`