# cypress-realworld-app: a full-stack payments demo built to be tested with Cypress

> The Cypress Real World App (RWA) is an Express/React payment application with a local JSON database, shipped so engineers can practise API, UI, component and unit testing against something that behaves like a real product. It is a teaching fixture, not a starting point for your own payments backend.

**cypress-io/cypress-realworld-app** — A payment application to demonstrate real-world usage of Cypress testing methods, patterns, and workflows.

- Repository: https://github.com/cypress-io/cypress-realworld-app
- Website: https://docs.cypress.io
- Stars: 5,913 · Forks: 2,613
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/cypress-io-cypress-realworld-app

## What cypress-realworld-app is actually for

Most testing tutorials hand you a to-do list with three inputs. Real applications have authentication, money movement, a database that changes between tests, and a backend that the browser talks to over HTTP. cypress-realworld-app exists to close that gap. It is a payment application, and the README is explicit that it is "purely for demonstration and educational purposes" and "not a full-fledged production system".

The audience is narrower than the name suggests. If you are evaluating Cypress as a tool, this repository is the reference implementation the Cypress team points at. If you already use Cypress and want to see how API tests, UI tests, component tests and unit tests are separated and named, the cypress/ directory is the interesting part, not the payments UI. If you want a codebase to fork into a real product, you are in the wrong repository, and the maintainers say so in the README note.

The feature list is deliberately ordinary: React, XState, Express, lowdb, Material-UI and TypeScript, with local authentication and database seeding driven by end-to-end tests. That combination is the point. Each piece creates a testing problem worth solving.

## How the Express, React and lowdb layers fit together

The application is a full-stack Express backend serving a React frontend, with a local JSON file as the database. lowdb manages data/database.json, and the README states that updates from the React frontend are sent to the Express server and handled by a set of database utilities in backend/database.ts. So the browser never writes the JSON file directly; every mutation goes through the API.

Seeding is the mechanism that makes the tests repeatable. According to the README, the database is reseeded from data/database-seed.json each time the application starts via yarn dev, and seeding also happens between each Cypress end-to-end test. That second part matters more than the first. A test that creates a transaction does not leak that transaction into the next test, which is the usual source of flaky suites.

The test layout is split by type rather than by feature. API tests live in cypress/tests/api, UI tests in cypress/tests/ui, component tests sit next to their components under src, and unit tests live in src/__tests__. That is a layout decision worth copying even if you never run this app: it makes the intent of a new test obvious from its path.

Ports are fixed by convention. The README says the app runs on port 3000 for the frontend and 3001 for the API backend by default.

## Installing cypress-realworld-app and running your first test

The README requires Node.js, with the exact version in the .node-version file, and Yarn Classic. It states plainly that the project is not compatible with Yarn Modern (version 2 and later), so if your global yarn is version 2 or above, install Classic first:

```bash
npm install yarn@1 -g
```

If Node's experimental Corepack feature is enabled, the README says to skip that step, because the project is locally configured for Corepack to use Yarn Classic.

Clone and install. On a Mac with an M-series chip, prepend the Puppeteer variable as shown in the README:

```bash
git clone https://github.com/cypress-io/cypress-realworld-app
cd cypress-realworld-app
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true yarn install
```

Start the application. It should come up on port 3000 for the frontend and 3001 for the API, so make sure nothing else holds those ports:

```bash
yarn dev
```

You can log in as any example user with the password s3cret. To see the available users, the README points at a script:

```bash
yarn list:dev:users
```

Then open the Cypress runner:

```bash
yarn cypress:open
```

If you changed the ports in .env, the README warns that you must also update cypress.config.ts locally: e2e.baseUrl follows PORT, and expose.apiUrl plus expose.codeCoverage.url follow VITE_BACKEND_PORT. It also warns against committing those changes, because CI expects the default ports. Two other scripts are worth knowing: yarn db:seed generates a new database, and yarn start:empty runs the app against data/empty-seed.json with no data at all.

## The JSON database is the limitation, not a detail

lowdb writing to data/database.json is what makes the project zero-dependency and instantly runnable. It is also the reason the app cannot be treated as a production system. There is no concurrency control described, no migration story, and the README does not document rollback or backup for the JSON file. Every yarn dev reseeds it, which is perfect for tests and wrong for anything a user depends on.

The consequence for test authors is subtler. Because seeding happens between end-to-end tests, a test that depends on state created by an earlier test will pass locally and fail once the suite is reordered or parallelised. The seeding behaviour is a guardrail, not a safety net you can lean on.

There is a second boundary. The README states the app is for learning and experimentation, and the release history supports reading it that way: the most recent tagged release is v1.0.18 from 2021-08-06, while the develop branch was last pushed on 2026-09-21. The tags are old and the branch is current, so if you pin a version you are pinning something five years behind the code people actually run. The README does not describe a support window or a deprecation policy.

Finally, the port and config coupling is a real friction point. Changing PORT and VITE_BACKEND_PORT in .env forces matching edits to three properties in cypress.config.ts, and the README explicitly tells you not to commit them. That is a documented manual step, not a bug, but it is the kind of thing that breaks a first run for someone who only skimmed the setup.

## cypress-realworld-app compared with a hand-rolled test fixture

The obvious alternative is not another framework. It is the fixture you would build yourself: a small Express app with a few routes, plus your own Cypress config. The difference in approach is that you control the domain, so the tests you write map to your product's vocabulary, and you avoid the port, Corepack and Yarn Classic constraints entirely.

What you give up is the parts that are tedious to invent. Authentication with seeded users and a shared password, a transaction model, a backend that the frontend calls over HTTP, and a database that resets between tests. cypress-realworld-app has all of that already wired, and its test folders show four distinct testing styles in one repository. Building an equivalent fixture to learn from would take longer than reading this one.

A second alternative, for teams that already have a product, is to test the product. A demo app cannot tell you how your own authentication redirects behave or where your API is slow. The RWA is a rehearsal space, and rehearsals are only useful before the performance, not instead of it. If your goal is confidence in a specific codebase, this repository is the wrong target and the README would agree.

## Licence, CI and the cost of keeping it running

The repository is MIT licensed, and package.json declares "license": "MIT". For a demo application that is about as permissive as it gets: you can copy patterns, extract test helpers and adapt the structure. The licence does not cover the Cypress test runner itself, which is a separate product, and nothing here should be read as legal advice about combining the two in a commercial setting.

The README lists CI/CD plus Cypress Cloud as a feature, and the repository carries CircleCI configuration, a Codecov badge, a Percy badge and a renovate.json file. That means the project has automated dependency updates and visual regression runs on its own infrastructure. It does not mean your fork inherits them. If you clone it, you own the Node version, the Yarn Classic pin and any Puppeteer download workaround your platform needs.

Upgrade cost is the sharp edge. A tagged release from 2021-08-06 will not carry the dependency bumps that landed on develop since. The README does not document a migration path between versions, so the practical choice is to track develop and accept that it moves, or to pin v1.0.18 and accept that it is old. Both are defensible for a learning tool, and neither is documented as supported.

## Conclusion

Adopt cypress-realworld-app if you are learning Cypress patterns or need a realistic target for a team workshop, and read the test folders in cypress/tests before you write anything of your own. Do not adopt it as the base of a production payment service: the README states it is purely for demonstration, the database is a JSON file reseeded on every yarn dev, and the last tagged release is v1.0.18 from 2021-08-06 even though the develop branch was pushed on 2026-09-21. Verify first that your Node version matches .node-version, that your package manager is Yarn Classic rather than Yarn Modern, and that ports 3000 and 3001 are free on the machine where you intend to run it.

## FAQ

### Is cypress-realworld-app free to use?

The repository is MIT licensed and package.json declares "license": "MIT", so the application code is free to use and adapt. The Cypress test runner is a separate product, and the README does not describe its pricing.

### How do I skip or ignore a test in cypress-realworld-app?

The README does not document how to skip an individual test. It does document the test layout, with API tests in cypress/tests/api, UI tests in cypress/tests/ui, component tests under src and unit tests in src/__tests__, which is where you would look for the test in question.

### How long does it take to learn Cypress using cypress-realworld-app?

The README gives no time estimate. It does say the app is bundled with example data so tests can run out-of-the-box, and that any example user can log in with the password s3cret, which removes the setup work that usually comes first.

### Which is better for testing cypress-realworld-app, Cypress or Jest?

The repository uses both rather than choosing. Unit tests live in src/__tests__, while API and UI tests live under cypress/tests, so the split is by test type rather than by tool.

## Sources

- [cypress-io/cypress-realworld-app on GitHub](https://github.com/cypress-io/cypress-realworld-app)
- [License: MIT](https://github.com/cypress-io/cypress-realworld-app/blob/develop/LICENSE)
- [Project website](https://docs.cypress.io)
- [README](https://github.com/cypress-io/cypress-realworld-app/blob/develop/README.md)
- [Releases](https://github.com/cypress-io/cypress-realworld-app/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cypress-io-cypress-realworld-app