diff --git a/README.md b/README.md index 8666b6ee..441c2a90 100644 --- a/README.md +++ b/README.md @@ -3,43 +3,46 @@ - [Treetracker Web Map Beta](#treetracker-web-map-beta) - [Project Description](#project-description) - [Development Environment Quick Start](#development-environment-quick-start) - - [Workflow with Github](#workflow-with-github) - [Test Driven Development](#test-driven-development) - [Glossary](#glossary) - [Test File Naming Conventions](#test-file-naming-conventions) - [How to Build Components](#how-to-build-components) + - [What's needed to test in a component unit test](#whats-needed-to-test-in-a-component-unit-test) - [Adding Material UI Theme to Component Tests](#adding-material-ui-theme-to-component-tests) - [Our Theme System](#our-theme-system) - [Using Correct Link Component](#using-correct-link-component) + - [CSS/Material-UI Guideline](#cssmaterial-ui-guideline) - [Material UI styles](#material-ui-styles) - - [Mocking NextJs Router in Component Tests](#mocking-nextjs-router-in-component-tests) + - [Mocking Next.js Router in Component Tests](#mocking-nextjs-router-in-component-tests) - [Mocking Static Images](#mocking-static-images) - [How to Build Pages/Routes](#how-to-build-pagesroutes) - [Integration Tests](#integration-tests) - [How to mock the API](#how-to-mock-the-api) - - [Mocking API calls in NextJs SSR functions](#mocking-api-calls-in-nextjs-ssr-functions) + - [Mocking API calls in cypress tests](#mocking-api-calls-in-cypress-tests) - [The API](#the-api) - [The current map API](#the-current-map-api) - - [The in-progress API](#the-in-progress-api) - - [Using our mock API server](#using-our-mock-api-server) - - [Config](#config) + - [Mocking the API in development](#mocking-the-api-in-development) - [The route/URL spec](#the-routeurl-spec) - [UI design resource](#ui-design-resource) + - [Design Sandbox](#design-sandbox) - [Code style guide](#code-style-guide) - [Prettier](#prettier) - [Eslint](#eslint) - - [husky](#husky) + - [Husky](#husky) - [Lint-Staged](#lint-staged) - [Commit Message and PR Title Format](#commit-message-and-pr-title-format) - [Troubleshooting](#troubleshooting) - - [Can not install Cypress in some area.](#can-not-install-cypress-in-some-area) - - [Other resource from Greenstand](#other-resource-from-greenstand) + - [Cannot install Cypress in some areas](#cannot-install-cypress-in-some-areas) + - [Other resources from Greenstand](#other-resources-from-greenstand) + - [Workflow with Github](#workflow-with-github) +- [MISC](#misc) + - [How to connect to production data locally](#how-to-connect-to-production-data-locally) # Treetracker Web Map Beta ## Project Description -Displays location and details of all trees that have been tracked in [Greenstand](http://greenstand.org). +Displays the location and details of all trees that have been tracked by [Greenstand](http://greenstand.org). Live site is at [www.treetracker.org](https://www.treetracker.org) @@ -47,11 +50,11 @@ Live dev env site for the new beta version is at: https://dev-k8s.treetracker.or **NOTE** -For the new web map beta development, we are working on the branch: beta, now we have set it as default branch. +For the new web map beta development, we are working on the `beta` branch. We have set it as the default branch. -The current version online is still deployed from master. +The current version online is still deployed from `master`. -So, for issues, the issue for the new web map beta, should use the branch: `beta`, the issue for the current version online, like fix bug, add tiny features, should use `master`, generally, we will freeze new big features on the `master` branch. +So for issues, the issue for the new web map beta should use the branch: `beta`. The issue for the current version online, like fix bug, add tiny features, should use `master`. Generally, we will freeze new big features on the `master` branch. ## Development Environment Quick Start @@ -59,13 +62,13 @@ This project must be installed and used with Node v16. [Node Version Manager](ht 1. Make sure all npm modules are installed for client. - ``` + ```bash npm i ``` 2. Start the client - ``` + ```bash npm run dev ``` @@ -73,7 +76,7 @@ This project must be installed and used with Node v16. [Node Version Manager](ht **Setup for WSL users** -In order to launch Cypress in WSL you will need to have an X-Server running on Windows. [This guide](https://dev.to/nickymeuleman/using-graphical-user-interfaces-like-cypress-in-wsl2-249j) outlines the steps necessary to configure your WSL shell to work with an X-server. If this still isn't working try launching vcxsrv.exe from the command line like this: +In order to launch Cypress in WSL you will need to have an X-Server running on Windows. [This guide](https://dev.to/nickymeuleman/using-graphical-user-interfaces-like-cypress-in-wsl2-249j) outlines the steps necessary to configure your WSL shell to work with an X-server. If this still isn't working try launching `vcxsrv.exe` from the command line like this: WSL 1 @@ -89,15 +92,15 @@ start "" "C:\Program Files\VcXsrv\vcxsrv.exe" :0 -multiwindow -clipboard -wgl -a ## Test Driven Development -We encourage Test Driven Development, with tool like Cypress, especially the component tool of Cypress, and the [intercept](https://docs.cypress.io/api/commands/intercept) API, it's been pretty easy to mock and build the case for tests, so we can write the test case first, let the case fail and then implement the real code. +We encourage Test Driven Development with tools like Cypress, especially the component tool of Cypress, and the [intercept](https://docs.cypress.io/api/commands/intercept) API. It's been pretty easy to mock and build the case for tests, so we can write the test case first, let the case fail and then implement the real code. ### Glossary -- Unit test: tests against a single class, object, function or file, covering the most small unit in codebase. It's good practice to code in TDD, but we don't enforce writing a unit test for every unit. Use Cypress component-testing to cover component units and Jest test to cover model file and utility functions. +- **Unit test**: tests against a single class, object, function or file, covering the most small unit in codebase. It's good practice to code in TDD, but we don't enforce writing a unit test for every unit. Use Cypress component-testing to cover component units and Jest test to cover model file and utility functions. -- Integration test: test a single piece of functionality in the app, like: a page, a module, an API endpoint. We require an integration test for every page. Use Cypress for page integration tests +- **Integration test**: test a single piece of functionality in the app, like a page, module, or an API endpoint. We require an integration test for every page. Use Cypress for page integration tests. -- End to End test: test the real app like a human being, against real app/environment. We will implement few a E2E tests to cover the most basic workflow, like: visit the root of the website, then jump into the detailed pages. Use Cypress to cover E2E tests. +- **End to End test**: test the real app like a human being, against real app/environment. We will implement few a E2E tests to cover the most basic workflow, like: visit the root of the website, then jump into the detailed pages. Use Cypress to cover E2E tests. ### Test File Naming Conventions @@ -105,9 +108,9 @@ We encourage Test Driven Development, with tool like Cypress, especially the com - Unit test files should be in the same directory as the test target and have the same name as the test target file with the suffix: `.test.js`. -- Put all integration tests into `/cypress/tests/integration` directory with suffix: `.cy.js`; +- Put all integration tests into `/cypress/tests/integration` directory with suffix: `.cy.js`. -- Put all e2e tests into `/cypress/tests/e2e/` directory with suffix: `.cy.js`; +- Put all e2e tests into `/cypress/tests/e2e/` directory with suffix: `.cy.js`. ## How to Build Components @@ -115,7 +118,7 @@ We recommend using Cypress's component testing tool to build components in isola **To run Cypress unit/component tests:** -``` +```bash npm run cyu ``` @@ -123,27 +126,27 @@ npm run cyu **NOTE** if you met : `not test found` problem, check this issue for fixing: [issue229](https://github.com/Greenstand/treetracker-web-map-client/issues/229) -### What's need to test in a component unit test +### What's needed to test in a component unit test -1. We require that the component should be correctly mount and present in there there enviroments: +1. We require that the component should be correctly mounted and present in the following environments: - Normal, the default desktop enviroments. - The mobile viewer enviroments with screen size: 390\*844 - The dark theme enviroment on descktop -2. We require to take a picture for every three seneriors above. ( `cy.screenshot()` ) +2. We require a picture to be taken for each of the three scenarios above. ( `cy.screenshot()` ) ### Adding Material UI Theme to Component Tests -When developing component tests use the custom `mountWithTheme` function found in `src/models/test-utils.js` instead of the mount function in the `@cypress/react` library. This will include the material-ui theme configuration when rendering your test component in cypress. +When developing component tests use the custom `mountWithTheme` function found in `src/models/test-utils.js` instead of the mount function in the `@cypress/react` library. This will include the Material UI theme configuration when rendering your test component in Cypress. ### Our Theme System -We heavely use the MaterialUI theme as the source of style, including: color, font, background. And the theme dynamically change when changing the dark/light mode. +We heavily use the Material UI theme as the source of style, including: color, font, and background. The theme dynamically changes when changing the dark/light mode. -The color system defined several named color as the brand color on Greenstand, check code in the theme file and in the pallete section, these color is also defined in our Figma file, check link below to find the design file. +The color system defines several named colors as the brand colors for Greenstand. Check the code in the theme file and in the pallete section. These colors are also defined in our [Figma file](https://www.figma.com/file/XdYFdjlsHvxehlrkPVYq0l/Greenstand-Webmap?node-id=2497%3A9322). -For convenience, run `npm run cyu` and find the page of `DesignSandbox`, you can directly check the theme settings, and pick appropriate ones for your coding. +For convenience, run `npm run cyu` and find the page of `DesignSandbox`. You can directly check the theme settings and pick appropriate ones for your coding. image @@ -159,7 +162,7 @@ https://greenstand.gitbook.io/wallet-web-app/css-and-materialui-guideline Use Material UI's [sx prop](https://mui.com/system/the-sx-prop/) to style your components. `tss-react` is included for maintaining backwards compatibility with the legacy code base. -### Mocking NextJs Router in Component Tests +### Mocking Next.js Router in Component Tests Use the custom `mountWithThemeAndRouter` function found in `src/models/test-utils.js` instead of the `mountWithTheme` function. This will include a basic router context mock to allow component tests to pass. @@ -191,31 +194,31 @@ Also, integration tests bring some benefits for the development workflow - by mo Open cypress test viewer -``` +```bash npm run cypress:open ``` -Nextjs dev server + Cypress test viewer + nock +Next.js dev server + Cypress test viewer + nock -``` +```bash npm run cy ``` -Nextjs dev server + Cypress test viewer without nock +Next.js dev server + Cypress test viewer without nock -``` +```bash npm run cy:nockless ``` Run cypress tests headless -``` +```bash npm run cypress:run ``` -Nextjs dev server + Cypress run headless + nock + skip video recording +Next.js dev server + Cypress run headless + nock + skip video recording -``` +```bash npm run cypress:run:fast ``` @@ -229,7 +232,7 @@ Cypress Integration testing also includes the `cypress-watch-and-reload` plugin ### Mocking API calls in cypress tests -NextJS deploys with a nodejs server and API calls can be made from this server or from the client viewing the webpage. Client-side API calls can be mocked by Cypress normally with the `cy.intercept()` method like this: +Next.js deploys with a Node.js server and API calls can be made from this server or from the client viewing the webpage. Client-side API calls can be mocked by Cypress normally with the `cy.intercept()` method like this: ```js cy.intercept('GET', '**/countries/**', { @@ -238,11 +241,11 @@ cy.intercept('GET', '**/countries/**', { }); ``` -Server-side API calls in NextJs must occur within a `getServerSideProps()` page function or from files in the `pages/api/` folder. These API calls can be mocked with the nock task we have added to cypress. The following example provides a mock response at the address being fetched during SSR. +Server-side API calls in Next.js must occur within a `getServerSideProps()` page function or from files in the `pages/api/` folder. These API calls can be mocked with the nock task we have added to Cypress. The following example provides a mock response at the address being fetched during SSR. **Note** -Cypress must start a custom Nextjs server to mock SSR functions. Use `cypress open --env nock=true` or `npm run cy:nock` to start cypress with a Nextjs server (this means you do not need to use `npm run dev` or `npm start`). You can use `Cypress.env('nock')` in your test files to check if the cypress nextjs server is active. +Cypress must start a custom Next.js server to mock SSR functions. Use `cypress open --env nock=true` or `npm run cy:nock` to start Cypress with a Next.js server (this means you do not need to use `npm run dev` or `npm start`). You can use `Cypress.env('nock')` in your test files to check if the Cypress Next.js server is active. ```js import tree from '../../fixtures/tree186734.json'; @@ -279,7 +282,7 @@ https://github.com/Greenstand/treetracker-query-api Start the dev server with msw enabled: -``` +```bash npm run dev:mock ``` @@ -303,13 +306,13 @@ Make sure you are logged in to Figma so that you can inspect the style details i To access the projects design sandbox, please run Cypress unit/component tests: -``` +```bash npm run cyu ``` -Open DesignSandbox.cy.js test file in the component test browser. located in the DesignSandbox folder. This component will have a color swatch, background swatch, and all the necessary typography information that matches the project's design file. +Open DesignSandbox.cy.js test file in the component test browser, located in the DesignSandbox folder. This component will have a color swatch, background swatch, and all the necessary typography information that matches the project's design file. -As we now have a dark theme, when working with text colors use the correct ones. We have colors that are dynamic based on the theme, and we have colors that are NOT dynamic that can be used for components with a background that does not change based on the theme. +As we now have a dark theme, when working with text colors make sure to use the correct ones. We have colors that are dynamic based on the theme, and we have colors that are NOT dynamic that can be used for components with a background that does not change based on the theme. Please use colors from MUI's theme when working on the style of the project for better maintainability, at readability. DO NOT write colors manually! @@ -319,7 +322,7 @@ We use [Prettier](https://prettier.io/), [Eslint](https://eslint.org/) along wit ### Prettier -Prettier reformats the code, but does not do code rule checking. If you are using VSCode as your IDE, please follow [this guide](https://www.digitalocean.com/community/tutorials/how-to-format-code-with-prettier-in-visual-studio-code) to set up Prettier and automatically format your code on file save. +Prettier formats the code, but it does not perform code rule checking. If you are using VSCode as your IDE, please follow [this guide](https://www.digitalocean.com/community/tutorials/how-to-format-code-with-prettier-in-visual-studio-code) to set up Prettier and automatically format your code on file save. You can find the Prettier rules in the .prettierrc file. @@ -327,85 +330,85 @@ You can find the Prettier rules in the .prettierrc file. To check the coding rules we use Eslint. To validate the rules manually, you must run: -``` +```bash npm run lint ``` To fix automatic rules run: -``` +```bash npm run lint:fix ``` -In .eslintrc.js, there is a set of rules with status **off or warn**. Whenever you are developing a new file or an existing file try to correct some warnings, because in the future the rules will be activated. +In .eslintrc.js, there is a set of rules with status **off or warn**. Whenever you are developing a new file or an existing file, try to correct some warnings, because in the future the rules will be activated. Once the rules are activated, you can't make a commit until you fix the lint errors! You can find the Eslint rules in the .eslintrc.js file. -### husky +### Husky -With husky we can use any git hook. Git Hooks are actions that can be executed if a certain Git event occurs. For example when a developer makes a 'git commit' or a 'git push'. Pre-commit hooks are listed in `.husky/pre-commit` +With Husky we can use any git hook. Git Hooks are actions that can be executed if a certain Git event occurs. For example when a developer makes a `git commit` or a `git push`. Pre-commit hooks are listed in `.husky/pre-commit`. ### Lint-Staged -[Lint-staged](https://github.com/okonet/lint-staged) is used with husky to run actions exclusively on staged files. This allows us to lint staged files and automatically add fixes to the commit. +[Lint-staged](https://github.com/okonet/lint-staged) is used with Husky to run actions exclusively on staged files. This allows us to lint staged files and automatically add fixes to the commit. ### Commit Message and PR Title Format We use [commitlint](https://github.com/conventional-changelog/commitlint), to format our commit messages. Commitlint checks if your commit messages meet the conventional commit format. -You need to use a proper commit message format or you will not be able to commit your changes! husky checks your commit messages before every commit. +You need to use a proper commit message format or you will not be able to commit your changes! Husky checks your commit messages before every commit. Your commit messages will need to follow the [Conventional Commits](https://www.conventionalcommits.org/) format, for example: -``` +```bash feat: add new button ``` -``` +```bash chore: run tests on travis ci ``` -``` +```bash fix(server): send cors headers ``` # Troubleshooting -## Can not install Cypress in some area. +## Cannot install Cypress in some areas -In some area like China, there might be some problem with installing the Cypress, throws error log like this: +In some areas like China, there might be some problems with installing the Cypress. It may throw an error log like this: -``` +```bash npm ERR! URL: https://download.cypress.io/desktop/8.6.0?platform=darwin&arch=x64 npm ERR! Error: read ECONNRESET ``` -To sole this problem, download the zip file directly from Cypress CDN following guide here: https://docs.cypress.io/guides/getting-started/installing-cypress#Direct-download +To solve this problem, download the zip file directly from Cypress CDN following guide here: https://docs.cypress.io/guides/getting-started/installing-cypress#Direct-download -Then install the project with a env variable: +Then install the project with an env variable: -``` +```bash CYPRESS_INSTALL_BINARY=[path/to/Cypress/zip/file] npm ci ``` -## Other resource from Greenstand +## Other resources from Greenstand -We have more tech guides and handbook here: +We have more tech guides and handbooks here: [Greenstand engineer handbook](https://greenstand.gitbook.io/engineering/) ## Workflow with Github -1. Feel free to pick tasks that interests you in the [issue](/issues) page, and leave some comment on it if you are going to work on it. +1. Feel free to pick tasks that interest you in the [issue](/issues) page, and leave some comments on it if you are going to work on it. 2. We tag issues with: - `good first issue`: easy and good for getting started. - `medium`: medium difficulty or needs more work. - - `challenge`: hardest or big tasks, or needs some special skill or tricky or even hack in some way. - - `documentation`: writing job, sometimes it's good for new dev to learn and do some simple job. + - `challenge`: hardest or big tasks, or needs some special skill or tricky or even hacky in some way. + - `documentation`: writing job, sometimes it's good for new devs to learn and do some simple jobs. - `bug`: just bug. - `wontfix`: some issue still in discussion, or can not be implemented at current stage, or just outdated problem. - `high-priority`: urgent problem, like some crucial bug or feature. @@ -413,20 +416,21 @@ We have more tech guides and handbook here: 3. Fork the repo. -4. Coding (In the process, you can rebase/merge the newest code from the main working branch online to get the new changes, check below link to get tutorial on how to update code from upstream) +4. Coding (in the process, you can rebase/merge the newest code from the main working branch online to get the new changes, check below link to get tutorial on how to update code from upstream) 5. Raise the PR, if possible, add `resolves #xx` in the description to link the PR with the issue, in this way, Github will automatically close that issue for us. -6. Optional, if you aren't fully confident about your code, it's always a good idea to create a PR in `draft` status as early as possible, so you can draw others attention on it and give you suggestions. (to do it, just expand the PR button, there is a `draft` selection) -7. If necessary, add some screenshot or video record to show the work, especial when you are doing some UI work, like build a component. +6. Optional: if you aren't fully confident about your code, it's always a good idea to create a PR in `draft` status as early as possible. This way you can draw others attention to it and they'll be able to give you suggestions. To do this, just expand the PR button, there is a `draft` selection. + +7. If necessary, add some screenshots or a video recording to show the work, especially when you are doing UI work, like building a component. -More resource is here: https://app.gitbook.com/@greenstand/s/engineering/tools#github +More resources can be found here: https://app.gitbook.com/@greenstand/s/engineering/tools#github # MISC ## How to connect to production data locally -Sometimes we need to connect production data (map, tree) to debug, to do so, copy the settings in `.env.production` and put them into the `.env.local` so next.js will load them as high priority. +Sometimes we need to connect production data (map, tree) to debug. To do so, copy the settings in `.env.production` and put them into the `.env.local` so Next.js will load them as high priority. . .