Update the README (#203)

* Add browser tests information * Add code block syntax highlighting * Put folder name in backticks * Reword sentence * Add environment variables note * Correct word Co-authored-by: Samuel Jones <[email protected]> --------- Co-authored-by: Samuel Jones <[email protected]>
fiaisis · Jul 9, 2024 · cbe5f3a · cbe5f3a
1 parent 07d7643
commit cbe5f3a
Showing 1 changed file with 22 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -1,16 +1,18 @@
 # Flexible Interactive Automation frontend
 
-This repository is for the frontend web application side of [FIA](https://github.com/fiaisis) that allows users to view and manage runs and reductions performed by ISIS instruments. The frontend acts as a plugin for the [SciGateway](https://github.com/ral-facilities/scigateway) application and was made using Yarn, React, Typescript, and Material-UI. The project is in the early stages of development and is continuously being worked on.
+This repository is for the frontend web application side of [FIA](https://github.com/fiaisis) which allows users to view and manage runs and reductions performed by ISIS instruments. The frontend acts as a plugin for the [SciGateway](https://github.com/ral-facilities/scigateway) application and was made using Yarn, React, Typescript, and Material-UI. The project is in the early stages of development and is continuously being worked on.
 
 ## Starting development
 
-### Downloading prerequisites
+### Downloading the code
 
-To get started developing for the frontend, first you will need to have [Node.js](https://nodejs.org/en/download/package-manager) and [Yarn](https://classic.yarnpkg.com/en/docs/install) installed on your machine. You will then want to clone the [SciGateway repository](https://github.com/ral-facilities/scigateway). From now on stick to SciGateway's `develop` branch (which is the default branch) and pull from it regularly to keep up to date with changes.
+To get started developing for the frontend, first you will need to have [Node.js](https://nodejs.org/en/download/package-manager) and [Yarn](https://classic.yarnpkg.com/en/docs/install) installed and set-up on your machine. When following the install wizards just keep to default settings. You will then want to clone the [SciGateway](https://github.com/ral-facilities/scigateway) repository. From now on stick to SciGateway's `develop` branch (which is the default branch) and pull from it regularly to keep up to date with changes.
 
-### Downloading the frontend
+With that done, you can now clone the FIA frontend repository.
 
-With that done, you can now clone the FIA frontend repository. The frontend works by building the project and then running it through SciGateway as a plugin. To get this set-up you will want to create a `settings.json` file in SciGateway's public folder. Do this by simply duplicating [`settings.example.json`](https://github.com/ral-facilities/scigateway/blob/develop/public/settings.example.json), renaming it, then adding FIA as a plugin with what port to listen on:
+### Setting up FIA as a plugin
+
+The frontend works by building the project and then running it through SciGateway as a plugin. To get this set-up you will want to create a `settings.json` file in SciGateway's `public` folder. Do this by simply duplicating [`settings.example.json`](https://github.com/ral-facilities/scigateway/blob/develop/public/settings.example.json), renaming it, then adding FIA as a plugin with what port to listen on:
 
 ```json
 // settings.json
@@ -28,18 +30,20 @@ A `dev-plugin-settings.json` file is also needed in SciGateway's `micro-frontend
 
 ```json
 // dev-plugin-settings.json
-{
-  "plugins": [
+"plugins": [
     {
       "type": "static",
       "location": "C:\\[path]\\[to]\\[frontend\\[build]\\[folder]",
       "port": 5001
     }
-  ]
-}
+]
 ```
 
-You will also want to delete the contents of SciGateway's [`res`](https://github.com/ral-facilities/scigateway/tree/develop/public/res) folder and copy over the contents from this repository's [`container`](https://github.com/fiaisis/frontend/tree/main/container) folder. This is mainly to overwrite [`default.json`](https://github.com/ral-facilities/scigateway/blob/develop/public/res/default.json) which deals with information within the footer and help page.
+You will also want to delete the contents of SciGateway's [`res`](https://github.com/ral-facilities/scigateway/tree/develop/public/res) folder and copy over the contents from this repository's [`container`](https://github.com/fiaisis/frontend/tree/main/container) folder. This is mainly to overwrite [`default.json`](https://github.com/ral-facilities/scigateway/blob/develop/public/res/default.json) which deals with information within wep applications footer and help page.
+
+### Specifying environment variables
+
+For local development it is recommended you adjust the URLs for the `REST_API` and `DATA_VIEWER` in [`.env`](https://github.com/fiaisis/frontend/blob/main/.env) to point to the staging `API` and `data viewer`.
 
 ## Available scripts
 
@@ -51,7 +55,7 @@ Installs the necessary dependencies for the project. You will need to run this c
 
 ### `yarn start`
 
-Runs the app in the development mode. Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
+Runs the app in the development mode. Open [http://localhost:3000/fia](http://localhost:3000/fia) to view it in the browser.
 
 The page will reload if you make edits. You will also see any lint errors in the console.
 
@@ -86,9 +90,15 @@ When adding new depencies to [`package.json`](https://github.com/fiaisis/fronten
 Occassionally there are issues with package conflicts that require `node_modules` and `yarn.lock` to be deleted and the cache cleared. You can do this with the following command:
 
 ```bash
-$ rm -rf node_modules && yarn cache clean && rm -f yarn.lock && yarn install
+rm -rf node_modules && yarn cache clean && rm -f yarn.lock && yarn install
 ```
 
+## Writing browser tests
+
+The FIA frontend makes use of [Cypress](https://www.cypress.io/) for conducting end-to-end and component testing. These tests will be ran by a [workflow](https://github.com/fiaisis/frontend/blob/main/.github/workflows/cypress_tests.yml) whenever a commit is pushed or a pull request merged. The tests can also be ran locally. 
+
+For writing your own tests, follow the guide [here](https://docs.cypress.io/guides/end-to-end-testing/writing-your-first-end-to-end-test). Alternatively you can replicate the methods used in pre-existing `.cy.tsx` files, like the [home page](https://github.com/fiaisis/frontend/blob/main/cypress/component/HomePage.cy.tsx).
+
 ## Learn More
 
 You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).