You've just forked the main repository, you've set up a working branch and you're ready to start development. (Well, you should be if you've followed the git workflow)

The next thing you need to do is set up your dev environment in order to be able to view the web app and run tests. You're also going to have to get familiar with the architecture of the system in order to know where to go to add new functionality/fix bugs.

There are four main components that you'll have to familiarize yourself with:

1. The database
2. The backend
3. The frontend
4. Running tests

We recommend following the order in the document as each module in the list depends on the previous one. Whenever you're testing the backend, you're going to need to make sure that your database is up and running. When you're testing your frontend, you're going to need both the database and backend running.

You will need a MySQL (like) database to connect the application to, and to have a correctly configured database with tables and data.

For many, XAMPP is likely the easiest way to setup and manage the database. XAMPP is a easy to install package containing MariaDB (a FOSS version of MySQL), Apache (a web server) and PHYMyAdmin for configuring the database (a MySQL admin panel served via Apache).

1. Download XAMPP's installer from the XAMPP Home Page
2. Run the installer and follow prompts, you can leave the settings as default
3. Once the installation is complete, the XAMPP Control Panel should open, if not, open it from the start menu
4. Start the Apache and MySQL modules in the control panel
5. In your web-browser, navigate to http://localhost/phpmyadmin to view the PHPMyAdmin dashboard

From the PHPMyAdmin dashboard you can run the SQL script provided below (in Initializing the database with data) to create the appropriate database, tables and sample data.

By default, XAMPP will configure MySQL with a superuser root with no password (blank string), you can simply use 'localhost' as the DB_HOST, use these details to configure the application (below).

Note: For Mac OS X users, if XAMPP and phpmyadmin prove to be problematic go to Option 3.

This project uses MySql. MySql is a relational database management system, and can be downloaded here.

During development, we chose to use CloudSQL as it is free and easy to set up. Google has extensive documentation here but a general overview of the process looks like:

1. Create a MySQL instance via the Google Cloud console
2. Create a database called restaurant_db
3. Set up a user that the Express backend can use to connect to the database (Users tab -> Create user account. Set "Allow any host(%)".)
4. Add your computers IP address to the authorization whitelist (Connections tab -> Authorized Networks -> Add network)
5. From the Google Cloud Platform menu (top left), select storage in the storage tab
6. Create a bucket, which will be used to store the database set-up file, then go into the newly created bucket
7. From this bucket, select upload files, and upload 'restaurant_db.sql' found in git-brunching/backend
8. From the Google Cloud Platform menu, go back to SQL, and into the newly created MySQL instance
9. From the top menu, select import, and import the restaurant_db.sql from our newly created bucket. This will set up the database.

When configuring the application (below), use the IP address provided by Google for DB_HOST and the username and password configured in step 3.

If you already have a MySQL or MariaDB install, you can use that with the appropriate details below.

Otherwise, do the following:

1. Install MySQL or MariaDB and initialise a database.
2. Install MySQL Workbench (or a similar tool) to manage the database using a friendly user interface.
3. Connect to the MySQL/MariaDB server using MySQL Workbench.

In the ./backend directory, create a file named ".env" containing:

DB_HOST=<Database address>
DB_DATABASE=<database name>
DB_USER=<username>
DB_PASS=<password>

We've exported one of our testing databases into an sql script that sets up any tables, as well as creates some dummy data to use for testing the application. This can be found here

Navigate to the Import tab in the PHPMyAdmin dashboard. Upload the SQL script (from the link above) and execute it, following the instructions.

GCP has an option to allow you to run the SQL script (from the link above).

The backend of this application is developed in Javascript, so the primary tool that you'll need to install is npm.js, a dependency manager for JavaScript projects. We have included a link to npm (which comes with Node.js) at the bottom of this document. You can verify your npm installation by running $ npm -v in your chosen CLI.

To install all of the project dependencies you will need to run $ npm i in the /backend subfolder on your chosen CLI.

$ npm run dev

• This will build the project for development use.
• Nodemon will monitor the project files and automatically restart the server whenever new changes are saved.
• The connection address will be displayed in the console.
• This will also run the API swagger docs. To see them the URL is: http://localhost:3001/api-docs/

$ npm start

• This will build then run the project for production.
• The connection address will be displayed in the console.
• If you're a contributor, you probably won't need to use this!

$ npm run test

• Run all unit tests and display a report.

Note. Before running any tests:

1. Change the mock flag in config.js to true.
2. In another terminal, start an instance of the API for the tests to connect to.
   • This can be done using either $ npm start or $ npm run dev.
3. Start the tests using $ npm run test

$ npm run lint

• This will inspect all files and report any linting issues.
• This project follows the popular Airbnb style guide.

$ npm run lintfix

• Attempts to autofix any linting violations.
  *Note. This may not be able to fix everything. Which means you will need to manually fix them.

Before making a pull request. Please ensure your code passes all tests and linting.
Prettier is an optional extension for most common IDE's. This will help with formatting/linting as you code.

• Error: listen EADDRINUSE: address already in use <address> - This is likely due to a nodemon leaving a background instance of node running.
  A guide to killing background node instances can be found here
• Error connecting: Error: connect ECONNNREFUSED 127.0.0.1:3306 at TCPConnectWrap.afterConnect [as oncomplete](net.js:1137:16) ..... - You haven't set up the database, or you haven't given your IP permission to access it.

• Create a new file in the 'routes' folder. The file name should reflect the endpoint.

• All routes should start with:

  import express from 'express';
  
  const router = express.Router();

• Keep all GET, POST, PATCH and DELETE methods inside this one folder

• Export the new route with:

  export default router;

• There is an example 'exampleEndpoint.js' to refer to.

• Import your new endpoint into app.js. This should be done under the // Routes comment by using:

  import <endpointName> from './routes/<endpointFileName>';

• Under the // Inject all routes comment, add your new endpoint to the app.

  app.use('/<url/path/to/call/endpoint>', <endpointName>);

Like the backend, the front end is coded in Javascript. We'll use $ npm i in the /frontend directory to once again install all necessary libraries.

$ npm run start

• This will build the project for development use.
• A page will be opened in your default browser, displaying the react app.

$ npm run lint

• This will inspect all files and report any linting issues.
• This project follows the popular Airbnb style guide.

$ npm run lintfix

• Attempts to autofix any linting violations.
  *Note. This may not be able to fix everything. Which means you will need to manually fix them.

Before making a pull request. Please ensure your code passes all tests and linting.
Prettier is an optional extension for most common IDE's. This will help with formatting/linting as you code.

To add a new page to the front-end, you must first go into 'App.js' and import the newly created page.

import PageName from "./path/to/page.js";

Next, go under the 'switch' tag and follow this format to give that new page a path in the application:

       <Route
            path="/[path]"
            component={() => (
              <[PageName]/>
            )}
        />

Once this is done, the page will now be accessible via the application

Use $ npm i in both the /frontend and /backend directories to set up the necessary dependencies.

Testing is done using Cypress. In the /frontend folder we'll run $ npm install cypress to download install the latest cypress.

Firstly, run $ npm run start in /frontend which, like above, will build the project for development use.

Then in a new CLI we'll navigate to /testing and run $ npx cypress opento launch the Cypress test runner.

From the test runner we can click on any of the integration tests. These will open in a new browser window fully automated by cypress. Browser can be changed in the top right of the test runner.

For further usage of the test runner, see the Cypress Documentation

All test files are located in /testing/cypress/integration. When creating a file, use an appropriate name <testname>.spec.js

Documentation for the commands you can use is found on the Cypress website.

• Make sure to reference the webpage with localhost:3000 and not your local ip as this will break it for other users
• Separate tests where needed and give them appropriate names to make debugging with the test runner easier

1. Install Docker Desktop (For Windows 10 Professional, Mac) or Docker Toolbox (For Windows 10 Home)
2. npm install in ./backend
3. change mock in ./backend/config/index.js to true
4. in ./backend run npm run mockTest
5. If you want to add more tests to be run, add the relevant paths to ./backend/tests/tests.js

• With Docker Toolbox, there may be some potential path errors in test.sh. To fix these, remove the colon from line 25 so the line instead says docker run --name=mysqltest -p 3306:3306 -dit -v "$homePath"/gitBrunching jacoballen4534/mysqltest:git-brunching-latest
• If you receive a docker daemon error, also try the fix above
• If none of the following work, try killing the current docker container with docker -ps, and then docker stop <container_id>

Cypress is a desktop application that is installed on your computer.

Installing Cypress via npm:

• cd /your/project/path
• npm install cypress --save-dev

Opening Cypress and Start testing APP

• ./node_modules/.bin/cypress open
• After launch cypress, you will be able to see the application as below:

• Downloading Node - https://nodejs.org/en/
• Cypress - https://www.cypress.io/