diff --git a/README.md b/README.md index 2694a60..31f18c5 100644 --- 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).