# cypress-realworld-app **Repository Path**: training-2021/cypress-realworld-app ## Basic Information - **Project Name**: cypress-realworld-app - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2021-10-29 - **Last Updated**: 2023-08-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

A payment application to demonstrate real-world usage of Cypress testing methods, patterns, and workflows.

Cypress Real World App

> 💬 **Note from maintainers** > > This application is purely for demonstration and educational purposes. Its setup and configuration resemble typical real-world applications, but it's not a full-fledged production system. Use this app to learn, experiment, tinker, and practice application testing with Cypress. > > Happy Testing! --- ## Features 🛠 Built with [React][reactjs], [XState][xstate], [Express][express], [lowdb][lowdb], [Material-UI][material-ui] and [TypeScript][typescript] ⚡️ Zero database dependencies 🚀 Full-stack [Express][express]/[React][reactjs] application with real-world features and tests 👮‍♂️ Local Authentication 🔥 Database Seeding with End-to-end Tests 💻 CI/CD + [Cypress Dashboard][cypressdashboard] ## Getting Started The Cypress Real-World App (RWA) is a full-stack Express/React application backed by a local JSON database ([lowdb]). The app is bundled with [example data](./data/database.json) (`data/database.json`) that contains everything you need to start using the app and run tests out-of-the-box. > 🚩 **Note** > > You can login to the app with any of the [example app users](./data/database.json#L2). The default password for all users is `s3cret`. > Example users can be seen by running `yarn list:dev:users`. ### Prerequisites The only requirement for this project is to have [Node.js](https://nodejs.org/en/) **version 14** installed on your machine. Refer to the [.node-version](./.node-version) file for the exact version. TypeScript will be added as a local dependency to the project, so no need to install it. ### Installation ```shell yarn install ``` #### Mac M1 chip users will need to prepend `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true`. ```shell PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true yarn install ``` ### Run the app ```shell yarn dev ``` > 🚩 **Note** > > The app will run on port `3000` (frontend) and `3001` (API backend) by default. Please make sure there are no other applications or services running on both ports. > If you want to change the default ports, you can do so by modifying `REACT_APP_PORT` and `REACT_APP_BACKEND_PORT` variables in `.env` file. > However, make sure the modified port numbers in `.env` are not commited into Git since the CI environments still expect the application to run on the default ports. ### Start Cypress ```shell yarn cypress:open ``` > 🚩 **Note** > > If you have changed the default ports, then you need to update Cypress configuration file (`cypress.json`) locally. > There are three properties that you need to update in `cypress.json`: `baseUrl`, `apiUrl`, and `url`. > The port number in `baseUrl` corresponds to `REACT_APP_PORT` variable in `.env` file. Similarly, the port number in `apiUrl` and `url` correspond to `REACT_APP_BACKEND_PORT`. > For example, if you have changed `REACT_APP_PORT` to `13000` and `REACT_APP_BACKEND_PORT` to `13001` in `.env` file, then your `cypress.json` should look similar to the following snippet: > > ```json > { > "baseUrl": "http://localhost:13000", > /* Omitted for brevity */ > "env": { > "apiUrl": "http://localhost:13001", > /* Omitted for brevity */ > "codeCoverage": { > "url": "http://localhost:13001/__coverage__" > } > }, > "experimentalStudio": true > } > ``` > > Avoid committing the modified `cypress.json` into Git since the CI environments still expect the application to be run on default ports. ## Tests | Type | Location | | ---- | ---------------------------------------- | | api | [cypress/tests/api](./cypress/tests/api) | | ui | [cypress/tests/ui](./cypress/tests/ui) | | unit | [`src/__tests__`](./src/__tests__) | ## Database - The local JSON database is located in [data/database.json](./data/database.json) and is managed with [lowdb]. - The database is [reseeded](./data/database-seed.json) each time the application is started (via `yarn dev`). Database seeding is done in between each [Cypress End-to-End test](./cypress/tests). - Updates via the React frontend are sent to the [Express][express] server and handled by a set of [database utilities](backend/database.ts) - Generate a new database using `yarn db:seed`. - An [empty database seed](./data/empty-seed.json) is provided along with a script (`yarn start:empty`) to view the application without data. ## Additional NPM Scripts | Script | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dev | Starts backend in watch mode and frontend | | dev:auth0 | Starts backend in watch mode and frontend; [Uses Auth0 for Authentication](#auth0) > [Read Guide](http://on.cypress.io/auth0) | | dev:okta | Starts backend in watch mode and frontend; [Uses Okta for Authentication](#okta) > [Read Guide](http://on.cypress.io/okta) | | dev:cognito | Starts backend in watch mode and frontend; [Uses Cognito for Authentication](#amazon-cognito) > [Read Guide](http://on.cypress.io/amazon-cognito) | | dev:google | Starts backend in watch mode and frontend; [Uses Google for Authentication](#google) > [Read Guide](https://docs.cypress.io/guides/testing-strategies/google-authentication.html) | | start | Starts backend and frontend | | types | Validates types | | db:seed | Generates fresh database seeds for json files in /data | | start:empty | Starts backend, frontend and Cypress with empty database seed | | tsnode | Customized ts-node command to get around react-scripts restrictions | | list:dev:users | Provides id and username for users in the dev database | For a complete list of scripts see [package.json](./package.json) ## Code Coverage Report The Cypress Real-World App uses the [@cypress/code-coverage](https://github.com/cypress-io/code-coverage) plugin to generate code coverage reports for the app frontend and backend. To generate a code coverage report: 1. Run `yarn cypress:run --env coverage=true` and wait for the test run to complete. 2. Once the test run is complete, you can view the report at `coverage/index.html`. ## 3rd Party Authentication Providers Support for 3rd party authentication is available in the application to demonstrate the concept and commands needed for programmatic login. ### Auth0 A [guide has been written with detail around adapting the RWA](http://on.cypress.io/auth0) to use [Auth0][auth0] and to explain the programmatic command used for Cypress tests. Prerequisites include an Auth0 account and a Tenant configured for use with a SPA. Environment variables from Auth0 are to be placed in the [.env](./.env). Start the application with `yarn dev:auth0` and run Cypress with `yarn cypress:open`. The only passing spec on this branch will be the [auth0 spec](./cypress/tests/ui-auth-providers/auth0.spec.ts); all others will fail. ### Okta A [guide has been written with detail around adapting the RWA](http://on.cypress.io/okta) to use [Okta][okta] and to explain the programmatic command used for Cypress tests. Prerequisites include an [Okta][okta] account and [application configured for use with a SPA][oktacreateapp]. Environment variables from [Okta][okta] are to be placed in the [.env](./.env). Start the application with `yarn dev:okta` and run Cypress with `yarn cypress:open`. The **only passing spec on this branch** will be the [okta spec](./cypress/tests/ui-auth-providers/okta.spec.ts); all others will fail. ### Amazon Cognito A [guide has been written with detail around adapting the RWA](http://on.cypress.io/amazon-cognito) to use [Amazon Cognito][cognito] as the authentication solution and to explain the programmatic command used for Cypress tests. Prerequisites include an [Amazon Cognito][cognito] account. Environment variables from [Amazon Cognito][cognito] are provided by the [AWS Amplify CLI][awsamplify]. Start the application with `yarn dev:cognito` and run Cypress with `yarn cypress:open`. The **only passing spec on this branch** will be the [cognito spec](./cypress/tests/ui-auth-providers/cognito.spec.ts); all others will fail. ### Google A [guide has been written with detail around adapting the RWA](https://docs.cypress.io/guides/testing-strategies/google-authentication.html) to use [Google][google] as the authentication solution and to explain the programmatic command used for Cypress tests. Prerequisites include an [Google][google] account. Environment variables from [Google][google] are to be placed in the [.env](./.env). Start the application with `yarn dev:google` and run Cypress with `yarn cypress:open`. The **only passing spec** when run with `yarn dev:google` will be the [google spec](./cypress/tests/ui-auth-providers/google.spec.ts); all others will fail. ## License [![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/cypress-io/cypress/blob/master/LICENSE) This project is licensed under the terms of the [MIT license](/LICENSE). [reactjs]: https://reactjs.org [xstate]: https://xstate.js.org [express]: https://expressjs.com [lowdb]: https://github.com/typicode/lowdb [typescript]: https://typescriptlang.org [cypressdashboard]: https://dashboard.cypress.io/projects/7s5okt/runs [material-ui]: https://material-ui.com [okta]: https://okta.com [auth0]: https://auth0.com [oktacreateapp]: https://developer.okta.com/docs/guides/sign-into-spa/react/create-okta-application/ [cognito]: https://aws.amazon.com/cognito [awsamplify]: https://amplify.aws [google]: https://google.com ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

_{Kevin Old}

_{Amir Rustamzadeh}

_{Brian Mann}

_{Gleb Bahmutov}

_{Ben Hong}

_{David Khourshid}

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!!