franaragm/cypress-realworld-app

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

💬 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 running yarn 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 correct version of yarn.

npm install yarn -g

The following command allows you to check that you have Yarn Classic (version 1) installed and active:

yarn -v

This project is not compatible with Yarn Modern (version 2 and later).

TypeScript will be added as a local dependency to the project, so no need to install it.

Installation

yarn

Mac M1 chip users 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) 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 PORT and REACT_APP_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.js) locally. There are three properties that you need to update in cypress.config.js: e2e.baseUrl, env.apiUrl, and env.url. The port number in e2e.baseUrl corresponds to PORT variable in .env file. Similarly, the port number in env.apiUrl and env.url correspond to REACT_APP_BACKEND_PORT. For example, if you have changed PORT to 13000 and REACT_APP_BACKEND_PORT to 13001 in .env file, then your cypress.config.js 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.js 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
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: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:

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 concept and commands needed for programmatic login.

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.

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.

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.

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; all others will fail.

Google

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.

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.