Awesome
<p align="center"> <!-- We use two SVGs here so that this displays correctly on Github. This might not look right in other Markdown previewers. --> <img alt="Cypress Real World App Logo" src="./src/svgs/rwa-logo-light.svg#gh-dark-mode-only" /> <img alt="Cypress Real World App Logo" src="./src/svgs/rwa-logo.svg#gh-light-mode-only" /> </p> <p align="center"> <a href="https://cypress.io"> <img width="140" alt="Cypress Logo" src="./src/svgs/built-by-cypress.svg" /> </a> </p> <p align="center"> <a href="https://cloud.cypress.io/projects/7s5okt/runs"> <img src="https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/detailed/7s5okt/develop&style=flat&logo=cypress" /> </a> <a href="https://codecov.io/gh/cypress-io/cypress-realworld-app"> <img src="https://codecov.io/gh/cypress-io/cypress-realworld-app/branch/develop/graph/badge.svg" /> </a> <a href="https://percy.io/cypress-io/cypress-realworld-app"> <img src="https://percy.io/static/images/percy-badge.svg" /> </a> <a href="#contributors-"> <img src="https://img.shields.io/badge/all_contributors-6-green.svg?style=flat" /> </a> </p> <p align="center"> A payment application to demonstrate <strong>real-world</strong> usage of <a href="https://cypress.io">Cypress</a> testing methods, patterns, and workflows. </p> <p align="center"> <img style='width: 70%' alt="Cypress Real World App" src="./public/img/rwa-readme-screenshot.png" /> </p>š¬ 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, XState, Express, lowdb, Material-UI and TypeScript ā”ļø Zero database dependencies š Full-stack Express/React application with real-world features and tests š®āāļø Local Authentication š„ Database Seeding with End-to-end Tests š» CI/CD + Cypress Cloud
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
) 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. The default password for all users is
s3cret
. Example users can be seen by runningyarn list:dev:users
.
Prerequisites
This project requires Node.js to be installed on your machine. Refer to the .node-version file for the exact version.
Yarn Classic is also required. Once you have Node.js installed, execute the following to install the npm module yarn (Classic - version 1) globally.
npm install yarn@latest -g
If you have Node.js' experimental Corepack feature enabled, then you should skip the step npm install yarn@latest -g
to install Yarn Classic globally. The RWA project is locally configured for Corepack
to use Yarn Classic (version 1).
Yarn Modern
This project is not compatible with Yarn Modern (version 2 and later).
Installation
To clone the repo to your local system and install dependencies, execute the following commands:
git clone https://github.com/cypress-io/cypress-realworld-app
cd cypress-realworld-app
yarn
Mac users with M-series chips will need to prepend PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
.
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true yarn install
Run the app
yarn dev
š© Note
The app will run on port
3000
(frontend) and3001
(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 modifyingPORT
andVITE_BACKEND_PORT
variables in.env
file. However, make sure the modified port numbers in.env
are not committed into Git since the CI environments still expect the application to run on the default ports.
Start Cypress
yarn cypress:open
š© Note
If you have changed the default ports, then you need to update Cypress configuration file (
cypress.config.ts
) locally. There are three properties that you need to update incypress.config.ts
:e2e.baseUrl
,env.apiUrl
, andenv.url
. The port number ine2e.baseUrl
corresponds toPORT
variable in.env
file. Similarly, the port number inenv.apiUrl
andenv.url
correspond toVITE_BACKEND_PORT
. For example, if you have changedPORT
to13000
andVITE_BACKEND_PORT
to13001
in.env
file, then yourcypress.config.ts
should look similar to the following snippet:{ env: { apiUrl: "http://localhost:13001", codeCoverage: { url: "http://localhost:13001/__coverage__" }, }, e2e: { baseUrl: "http://localhost:13000" } }
Avoid committing the modified
cypress.config.ts
into Git since the CI environments still expect the application to be run on default ports.
Tests
Type | Location |
---|---|
api | cypress/tests/api |
ui | cypress/tests/ui |
component | src/(next to component) |
unit | src/__tests__ |
Database
-
The local JSON database is located in data/database.json and is managed with lowdb.
-
The database is reseeded each time the application is started (via
yarn dev
). Database seeding is done in between each Cypress End-to-End test. -
Updates via the React frontend are sent to the Express server and handled by a set of database utilities
-
Generate a new database using
yarn db:seed
. -
An empty database seed 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:coverage | Starts backend in watch mode and frontend with instrumented code coverage enabled |
dev:auth0 | Starts backend in watch mode and frontend; Uses Auth0 for Authentication > Read Guide |
dev:okta | Starts backend in watch mode and frontend; Uses Okta for Authentication > Read Guide |
dev:cognito | Starts backend in watch mode and frontend; Uses Cognito for Authentication > Read Guide |
dev:google | Starts backend in watch mode and frontend; Uses Google for Authentication > Read Guide |
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
Code Coverage Report
The Cypress Real-World App uses the @cypress/code-coverage plugin to generate code coverage reports for the app frontend and backend.
To generate a code coverage report:
- Start the development server with coverage enabled by running
yarn dev:coverage
. - Run
yarn cypress:run --env coverage=true
and wait for the test run to complete. - 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 concepts on logging in with a 3rd party provider.
The app contains different entry points for each provider. There is a separate index file for each provider, and to use one, you must replace the current index.tsx file with the desired one. The following providers are supported:
- Auth0 (index.auth0.tsx)
- Okta (index.okta.tsx)
- Amazon Cognito (index.cognito.tsx)
- Google (index.google.tsx)
Auth0
The Auth0 tests have been rewritten to take advantage of our cy.session
and cy.origin
commands.
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. For more details see Auth0 Application Setup and Setting Auth0 app credentials in Cypress.
To start the application with Auth0, replace the current src/index.tsx file with the src/index.auth0.tsx file and 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; all others will fail. Please note that your test user will need to authorize your Auth0 app before the tests will pass.
Okta
A guide has been written with detail around adapting the RWA to use Okta and to explain the programmatic command used for Cypress tests.
Prerequisites include an Okta account and application configured for use with a SPA. Environment variables from Okta are to be placed in the .env.
To start the application with Okta, replace the current src/index.tsx file with the src/index.okta.tsx file and 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; all others will fail.
Amazon Cognito
A guide has been written with detail around adapting the RWA to use Amazon Cognito as the authentication solution and to explain the programmatic command used for Cypress tests.
Prerequisites include an Amazon Cognito account. Environment variables from Amazon Cognito are provided by the AWS Amplify CLI.
- A user pool is required (identity pool is not used here)
- The user pool must have a hosted UI domain configured, which must:
- allow callback and sign-out URLs of
http://localhost:3000/
, - allow implicit grant Oauth grant type,
- allow these OpenID Connect scopes:
- aws.cognito.signin.user.admin
- openid
- allow callback and sign-out URLs of
- The user pool must have an app client configured, with:
- enabled auth flow
ALLOW_USER_PASSWORD_AUTH
, only for programmatic login flavor of test. - The
cy.origin()
flavor of test only requires auth flowALLOW_USER_SRP_AUTH
, and does not requireALLOW_USER_PASSWORD_AUTH
.
- enabled auth flow
- The user pool must have a user corresponding to the
AWS_COGNITO
env vars mentioned below, and the user's Confirmation Status must beConfirmed
. If it isForce Reset Password
, then use a browser to log in once athttp://localhost:3000
whileyarn dev:cognito
is running to reset their password.
- The user pool must have a hosted UI domain configured, which must:
The test knobs are in a few places:
- The
.env
file hasVITE_AUTH_TOKEN_NAME
and vars beginningAWS_COGNITO
. Be careful not to commit any secrets. - Both
scripts/mock-aws-exports.js
andscripts/mock-aws-exports-es5.js
must have the same data; only their export statements differ. These files can be edited manually or exported from the amplify CLI. cypress.config.ts
hascognito_programmatic_login
to control flavor of the test.
To start the application with Cognito, replace the current src/index.tsx file with the src/index.cognito.tsx file and start the application with yarn dev:cognito
and run Cypress with yarn cypress:open
. yarn dev
may need to have been run once first.
The only passing spec on this branch will be the cognito spec; all others will fail.
A guide has been written with detail around adapting the RWA to use Google as the authentication solution and to explain the programmatic command used for Cypress tests.
Prerequisites include an Google account. Environment variables from Google are to be placed in the .env.
To start the application with Google, replace the current src/index.tsx file with the src/index.google.tsx file and 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; all others will fail.
License
This project is licensed under the terms of the MIT license.
Contributors āØ
Thanks goes to these wonderful people (emoji key):
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> <!-- prettier-ignore-start --> <!-- markdownlint-disable --> <table> <tr> <td align="center"><a href="http://www.kevinold.com"><img src="https://avatars0.githubusercontent.com/u/21967?v=4" width="100px;" alt=""/><br /><sub><b>Kevin Old</b></sub></a></td> <td align="center"><a href="https://twitter.com/amirrustam"><img src="https://avatars0.githubusercontent.com/u/334337?v=4" width="100px;" alt=""/><br /><sub><b>Amir Rustamzadeh</b></sub></a></td> <td align="center"><a href="https://twitter.com/be_mann"><img src="https://avatars2.githubusercontent.com/u/1268976?v=4" width="100px;" alt=""/><br /><sub><b>Brian Mann</b></sub></a></td> <td align="center"><a href="https://glebbahmutov.com/"><img src="https://avatars1.githubusercontent.com/u/2212006?v=4" width="100px;" alt=""/><br /><sub><b>Gleb Bahmutov</b></sub></a></td> <td align="center"><a href="http://www.bencodezen.io"><img src="https://avatars0.githubusercontent.com/u/4836334?v=4" width="100px;" alt=""/><br /><sub><b>Ben Hong</b></sub></a></td> <td align="center"><a href="https://github.com/davidkpiano"><img src="https://avatars2.githubusercontent.com/u/1093738?v=4" width="100px;" alt=""/><br /><sub><b>David Khourshid</b></sub></a></td> </tr> </table> <!-- markdownlint-enable --> <!-- prettier-ignore-end --> <!-- ALL-CONTRIBUTORS-LIST:END -->This project follows the all-contributors specification. Contributions of any kind welcome!!