Skip to content

Development Setup

Jump to bottom
kurteulau edited this page Jan 12, 2022 · 9 revisions

Setting up locally

AIP is developed using Node JS and React. To get started, ensure you have Node JS installed on your computer. We recommend using nvm to manage multiple versions of Node.

  1. Setup nvm and Node
  • Setup nvm, follow the guide here
  • Clone this repo git clone https://github.com/developmentseed/catalyst-aip.git. Do not use the URL provided by clicking the green Code button then selecting HTTPS link under the Clone menu (aka standard git clone link).
  • Change directory into the repo. cd catalyst-aip
  • Setup the appropriate node version by running nvm install
  1. Install dependencies
  • yarn install
  1. Add the environment variables
  • The .env.example file is a sample for the environment variable necessary to run the application.
  • cp .env.example .env.development to use with yarn develop
  • cp .env.example .env.production to use with yarn build — see the Deploying section.
  • Note: You'll need the MAPBOX_ACCESS_TOKEN which is available on https://account.mapbox.com/
  1. Start the application
  • yarn develop and visit http://localhost:8000
  • Use git pull origin develop and git push origin develop to pull latest version and push updates.

Deploying

Currently, the application is automatically deployed to a service called Vercel. Vercel is a simple way to publish websites directly with a single command or in a CI/CD flow.

Quality Assurance

We use a set of rigorous rules and tests for QA of the code base. This include unit tests and linters.

Formatting

This project uses Prettier to standardise code formatting. This eliminates the need to discuss style in code review. The rules applied are configured in the .prettierrc file. It is recommended to allow your editor to format on save. You can run yarn format to apply the formatting rules to all files.

Linting

This project uses ESLint for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs. The rules applied are configured in the .eslintrc.js file.

You can run yarn lint to check for linting errors in all javascript files, or run yarn lint:fix to apply automatic fixes to the code.

Testing

Our testing setup uses jest and cypress. You can run the test suits with yarn test and yarn cy:run, respectively.

Unit testing

jest is set up and ready to write and run unit tests. The test suit can be run with yarn test. In order to run the tests in watch mode for test driven development, run yarn tdd.

yarn test

# alternatively, to run tests in watch mode:
yarn tdd

Integration testing

The more your tests resemble the way your software is used, the more confidence they can give you. https://twitter.com/kentcdodds/status/977018512689455106

The recent advice is towards a more integrated approach in testing. You want your tests to avoid including implementation details so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down. For React components, this means to avoid shallow rendering. And in general, to stop mocking so much stuff.

Read more here: https://kentcdodds.com/blog/write-tests or https://testingjavascript.com/

End-to-end testing

End-to-end (e2e) tests are functional tests for automated click-testing of critical paths. It is better to automate this rather than relying on the users to do the testing. This project is using Cypress as end-to-end testing framework. cypress-axe is used to uncover accessibility issues.

To run the tests locally, start the development server and run yarn cy:open, which opens the interactive test runner.

yarn cy:open

You can watch tests run in real time as you develop your applications. TDD FTW 🤩!

It is also possible to run the tests and get the results in the command line only with yarn cy:run.

Some testing strategies with Cypress:

  • write specs that will solely test a single behavior
  • each spec should be written in isolation and avoid coupling
  • avoid brittle selectors, use data-* attributes instead (e.g. data-cy="my-div")
  • set state directly/programmatically before testing (e.g. use the endpoint to request a login token instead of making cypress click the login button)

Read more on best practices here: https://docs.cypress.io/guides/references/best-practices.html

Clone this wiki locally