cypress-realworld-app: Open Source API Development & Testing

What is cypress-realworld-app?

Cypress Real-World App is a full-stack payment application built to demonstrate real-world usage of Cypress testing methods, patterns, and workflows, intended for developers and test engineers who want to practise end-to-end, component, and API testing against something that behaves like a production application.

What it is

Cypress Real-World App (RWA) is an MIT-licensed, open-source demo application written in TypeScript, pairing an Express API backend with a React frontend, XState for state management, Material-UI for interface components, and lowdb as a local JSON database. It lives in the Cypress testing ecosystem and is published by the Cypress organisation, with its documentation pointing at docs.cypress.io. The repository ships the application and its test suites together, so the specs, the configuration in cypress.config.ts, and the code they exercise are versioned in one place.

The concrete problem it solves is the gap between trivial Cypress examples and production-grade test suites. Most testing tutorials rely on toy applications with no authentication, no seeded data, and no backend, which leaves developers without a realistic place to learn patterns for API testing, component testing, code coverage, and end-to-end flows. RWA replaces that throwaway sample-app approach with a seeded payment application whose setup and configuration resemble a typical real-world system, and it replaces the external database dependency with a bundled example dataset at data/database.json, so tests run out of the box without provisioning a database server.

Key capabilities

Full-stack Express/React application written in TypeScript, using XState for state machines and Material-UI for the interface.
Zero database dependencies: persistence uses lowdb backed by the bundled data/database.json example dataset.
Local authentication with example users listed by running yarn list:dev:users; the default password for all example users is s3cret.
Database seeding integrated with end-to-end tests, so suites begin from a known data state.
Code coverage exposed through expose.codeCoverage.url in cypress.config.ts and served from the /__coverage__ endpoint.
End-to-end and component testing driven by Cypress, with API testing covered among the repository topics.
CI/CD integration with Cypress Cloud for recorded runs.

Who uses it and how

Developers and test engineers learning Cypress end-to-end testing who want a payment workflow with authentication and real data rather than a static page.
Teams practising API testing and component testing against a running Express backend on port 3001 and a React frontend on port 3000.
Engineers setting up CI/CD pipelines with Cypress Cloud who want a reference project showing recorded runs alongside coverage output.
Anyone who needs deterministic, seeded test data: the bundled dataset lets full suites execute immediately after cloning, with no database server to install or migrate.
Contributors and workshop attendees: the maintainers frame the app for learning, experimenting, and tinkering, and the repository's 5,911 stars, 2,612 forks, and 31 open issues reflect ongoing community use.

Getting started

Clone the repository and run yarn to install dependencies, using Yarn Classic (version 1, installed globally with npm install yarn@1 -g); on Macs with M-series chips, prepend PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true to the install command. Start the application with yarn dev and open the Cypress runner with yarn cypress:open.

How it compares

The facts supplied provide no list of paid products that this project replaces, and they name no directly comparable tools. Cypress Real-World App therefore stands alone in this registry as the reference application for the Cypress testing ecosystem.

When to use it — and when not to

Choose it when you want to learn, experiment, and practise Cypress on an application with realistic structure; the maintainers state plainly that it is purely for demonstration and educational purposes and is not a full-fledged production system, so it should not serve as the basis of a live payment product. A self-hoster must run Node.js at the version pinned in .node-version, keep Yarn Classic installed because the project is not compatible with Yarn Modern (version 2 and later), and keep ports 3000 and 3001 free or edit PORT and VITE_BACKEND_PORT in .env while updating cypress.config.ts to match. Teams unwilling to run a local JSON data file, or expecting a production-grade database and operational hardening, should look elsewhere.

project readme (upstream, from github) — read inline

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][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 Cloud][cypresscloud]

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 npm module yarn (Classic - version 1) globally.

npm install yarn@1 -g

If you have Node.js' experimental Corepack feature enabled, then you should skip the step npm install yarn@1 -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) 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 VITE_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 in cypress.config.ts: e2e.baseUrl, expose.apiUrl, and expose.codeCoverage.url. The port number in e2e.baseUrl corresponds to PORT variable in .env file. Similarly, the port number in expose.apiUrl and expose.codeCoverage.url correspond to VITE_BACKEND_PORT. For example, if you have changed PORT to 13000 and VITE_BACKEND_PORT to 13001 in .env file, then your cypress.config.ts should look similar to the following snippet:
{
  expose: {
    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][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

Frequently asked questions

Is cypress-realworld-app free to use?

cypress-realworld-app is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does cypress-realworld-app do?

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

What is cypress-realworld-app written in?

cypress-realworld-app is primarily written in TypeScript. Its source is publicly available at https://github.com/cypress-io/cypress-realworld-app, and it has 5,912 GitHub stars.