{"id":13496451,"url":"https://github.com/cypress-io/cypress-realworld-app","last_synced_at":"2025-05-12T13:25:17.613Z","repository":{"id":37730813,"uuid":"232162578","full_name":"cypress-io/cypress-realworld-app","owner":"cypress-io","description":"A payment application to demonstrate real-world usage of Cypress testing methods, patterns, and workflows.","archived":false,"fork":false,"pushed_at":"2025-05-01T18:56:11.000Z","size":12408,"stargazers_count":5693,"open_issues_count":40,"forks_count":2353,"subscribers_count":82,"default_branch":"develop","last_synced_at":"2025-05-01T19:42:41.961Z","etag":null,"topics":["api-testing","code-coverage","component-testing","cypress","end-to-end-testing","testing","testing-practices"],"latest_commit_sha":null,"homepage":"https://docs.cypress.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cypress-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-06T18:39:43.000Z","updated_at":"2025-05-01T12:37:45.000Z","dependencies_parsed_at":"2024-03-25T07:30:52.392Z","dependency_job_id":"9bf5722d-b2ae-4077-93fc-65377eef0fcf","html_url":"https://github.com/cypress-io/cypress-realworld-app","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-realworld-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-realworld-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-realworld-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-io%2Fcypress-realworld-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypress-io","download_url":"https://codeload.github.com/cypress-io/cypress-realworld-app/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253746223,"owners_count":21957519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-testing","code-coverage","component-testing","cypress","end-to-end-testing","testing","testing-practices"],"created_at":"2024-07-31T19:01:48.032Z","updated_at":"2025-05-12T13:25:17.588Z","avatar_url":"https://github.com/cypress-io.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Awesome XState","testing","Building","🛠️ Developer Tools"],"sub_categories":["Articles","Workflows"],"readme":"\u003cp align=\"center\"\u003e\n  \u003c!-- We use two SVGs here so that this displays correctly\n    on Github. This might not look right in other Markdown previewers. --\u003e\n  \u003cimg alt=\"Cypress Real World App Logo\" src=\"./src/svgs/rwa-logo-light.svg#gh-dark-mode-only\" /\u003e\n  \u003cimg alt=\"Cypress Real World App Logo\" src=\"./src/svgs/rwa-logo.svg#gh-light-mode-only\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://cypress.io\"\u003e\n    \u003cimg width=\"140\" alt=\"Cypress Logo\" src=\"./src/svgs/built-by-cypress.svg\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n   \u003ca href=\"https://cloud.cypress.io/projects/7s5okt/runs\"\u003e\n    \u003cimg src=\"https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/detailed/7s5okt/develop\u0026style=flat\u0026logo=cypress\" /\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://codecov.io/gh/cypress-io/cypress-realworld-app\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/cypress-io/cypress-realworld-app/branch/develop/graph/badge.svg\" /\u003e\n  \u003c/a\u003e\n\n  \u003ca href=\"https://percy.io/cypress-io/cypress-realworld-app\"\u003e\n    \u003cimg src=\"https://percy.io/static/images/percy-badge.svg\" /\u003e\n  \u003c/a\u003e\n\n   \u003ca href=\"#contributors-\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/all_contributors-6-green.svg?style=flat\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\nA payment application to demonstrate \u003cstrong\u003ereal-world\u003c/strong\u003e usage of \u003ca href=\"https://cypress.io\"\u003eCypress\u003c/a\u003e testing methods, patterns, and workflows.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 70%' alt=\"Cypress Real World App\" src=\"./public/img/rwa-readme-screenshot.png\" /\u003e\n\u003c/p\u003e\n\n\u003e 💬 **Note from maintainers**\n\u003e\n\u003e 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.\n\u003e\n\u003e Happy Testing!\n\n---\n\n## Features\n\n🛠 Built with [React][reactjs], [XState][xstate], [Express][express], [lowdb][lowdb], [Material-UI][material-ui] and [TypeScript][typescript]\n⚡️ Zero database dependencies\n🚀 Full-stack [Express][express]/[React][reactjs] application with real-world features and tests\n👮‍♂️ Local Authentication\n🔥 Database Seeding with End-to-end Tests\n💻 CI/CD + [Cypress Cloud][cypresscloud]\n\n## Getting Started\n\nThe Cypress Real-World App (RWA) is a full-stack Express/React application backed by a local JSON database ([lowdb]).\n\nThe 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.\n\n\u003e 🚩 **Note**\n\u003e\n\u003e 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`.\n\u003e Example users can be seen by running `yarn list:dev:users`.\n\n### Prerequisites\n\nThis project requires [Node.js](https://nodejs.org/en/) to be installed on your machine. Refer to the [.node-version](./.node-version) file for the exact version.\n\n[Yarn Classic](https://classic.yarnpkg.com/) is also required. Once you have [Node.js](https://nodejs.org/en/) installed, execute the following to install the npm module [yarn](https://www.npmjs.com/package/yarn) (Classic - version 1) globally.\n\n```shell\nnpm install yarn@latest -g\n```\n\nIf you have Node.js' experimental [Corepack](https://nodejs.org/dist/latest/docs/api/corepack.html) 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).\n\n#### Yarn Modern\n\n**This project is not compatible with [Yarn Modern](https://yarnpkg.com/) (version 2 and later).**\n\n### Installation\n\nTo clone the repo to your local system and install dependencies, execute the following commands:\n\n```shell\ngit clone https://github.com/cypress-io/cypress-realworld-app\ncd cypress-realworld-app\nyarn\n```\n\n#### Mac users with M-series chips will need to prepend `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true`.\n\n```shell\nPUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true yarn install\n```\n\n### Run the app\n\n```shell\nyarn dev\n```\n\n\u003e 🚩 **Note**\n\u003e\n\u003e 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.\n\u003e If you want to change the default ports, you can do so by modifying `PORT` and `VITE_BACKEND_PORT` variables in `.env` file.\n\u003e 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.\n\n### Start Cypress\n\n```shell\nyarn cypress:open\n```\n\n\u003e 🚩 **Note**\n\u003e\n\u003e If you have changed the default ports, then you need to update Cypress configuration file (`cypress.config.ts`) locally.\n\u003e There are three properties that you need to update in `cypress.config.ts`: `e2e.baseUrl`, `env.apiUrl`, and `env.url`.\n\u003e 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 `VITE_BACKEND_PORT`.\n\u003e 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:\n\u003e\n\u003e ```js\n\u003e {\n\u003e   env: {\n\u003e     apiUrl: \"http://localhost:13001\",\n\u003e     codeCoverage: {\n\u003e       url: \"http://localhost:13001/__coverage__\"\n\u003e     },\n\u003e   },\n\u003e   e2e: {\n\u003e     baseUrl: \"http://localhost:13000\"\n\u003e   }\n\u003e }\n\u003e ```\n\u003e\n\u003e Avoid committing the modified `cypress.config.ts` into Git since the CI environments still expect the application to be run on default ports.\n\n## Tests\n\n| Type      | Location                                 |\n| --------- | ---------------------------------------- |\n| api       | [cypress/tests/api](./cypress/tests/api) |\n| ui        | [cypress/tests/ui](./cypress/tests/ui)   |\n| component | [src/(next to component)](./src)         |\n| unit      | [`src/__tests__`](./src/__tests__)       |\n\n## Database\n\n- The local JSON database is located in [data/database.json](./data/database.json) and is managed with [lowdb].\n\n- 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).\n\n- Updates via the React frontend are sent to the [Express][express] server and handled by a set of [database utilities](backend/database.ts)\n\n- Generate a new database using `yarn db:seed`.\n\n- An [empty database seed](./data/empty-seed.json) is provided along with a script (`yarn start:empty`) to view the application without data.\n\n## Additional NPM Scripts\n\n| Script         | Description                                                                                                                                                                       |\n| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| dev            | Starts backend in watch mode and frontend                                                                                                                                         |\n| dev:coverage   | Starts backend in watch mode and frontend with instrumented code coverage enabled                                                                                                 |\n| dev:auth0      | Starts backend in watch mode and frontend; [Uses Auth0 for Authentication](#auth0) \u003e [Read Guide](http://on.cypress.io/auth0)                                                     |\n| dev:okta       | Starts backend in watch mode and frontend; [Uses Okta for Authentication](#okta) \u003e [Read Guide](http://on.cypress.io/okta)                                                        |\n| dev:cognito    | Starts backend in watch mode and frontend; [Uses Cognito for Authentication](#amazon-cognito) \u003e [Read Guide](http://on.cypress.io/amazon-cognito)                                 |\n| dev:google     | Starts backend in watch mode and frontend; [Uses Google for Authentication](#google) \u003e [Read Guide](https://docs.cypress.io/guides/testing-strategies/google-authentication.html) |\n| start          | Starts backend and frontend                                                                                                                                                       |\n| types          | Validates types                                                                                                                                                                   |\n| db:seed        | Generates fresh database seeds for json files in /data                                                                                                                            |\n| start:empty    | Starts backend, frontend and Cypress with empty database seed                                                                                                                     |\n| tsnode         | Customized ts-node command to get around react-scripts restrictions                                                                                                               |\n| list:dev:users | Provides id and username for users in the dev database                                                                                                                            |\n\nFor a complete list of scripts see [package.json](./package.json)\n\n## Code Coverage Report\n\nThe 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.\n\nTo generate a code coverage report:\n\n1. Start the development server with coverage enabled by running `yarn dev:coverage`.\n2. Run `yarn cypress:run --env coverage=true` and wait for the test run to complete.\n3. Once the test run is complete, you can view the report at `coverage/index.html`.\n\n## 3rd Party Authentication Providers\n\nSupport for 3rd party authentication is available in the application to demonstrate the concepts on logging in with a 3rd party provider.\n\nThe 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:\n\n- [Auth0](#auth0) (index.auth0.tsx)\n- [Okta](#okta) (index.okta.tsx)\n- [Amazon Cognito](#amazon-cognito) (index.cognito.tsx)\n- [Google](#google) (index.google.tsx)\n\n### Auth0\n\nThe [Auth0](https://auth0.com/) tests have been rewritten to take advantage of our [`cy.session`](https://docs.cypress.io/api/commands/session) and [`cy.origin`](https://docs.cypress.io/api/commands/origin) commands.\n\nPrerequisites 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). For more details see [Auth0 Application Setup](http://on.cypress.io/auth0#Auth0-Application-Setup) and [Setting Auth0 app credentials in Cypress](http://on.cypress.io/auth0#Setting-Auth0-app-credentials-in-Cypress).\n\nTo 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`.\n\nThe only passing spec on this branch will be the [auth0 spec](./cypress/tests/ui-auth-providers/auth0.spec.ts); all others will fail. Please note that your test user will need to authorize your Auth0 app before the tests will pass.\n\n### Okta\n\nA [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.\n\nPrerequisites 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).\n\nTo 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`.\n\nThe **only passing spec on this branch** will be the [okta spec](./cypress/tests/ui-auth-providers/okta.spec.ts); all others will fail.\n\n### Amazon Cognito\n\nA [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.\n\nPrerequisites include an [Amazon Cognito][cognito] account. Environment variables from [Amazon Cognito][cognito] are provided by the [AWS Amplify CLI][awsamplify].\n\n- A user pool is required (identity pool is not used here)\n  - The user pool must have a hosted UI domain configured, which must:\n    - allow callback and sign-out URLs of `http://localhost:3000/`,\n    - allow implicit grant Oauth grant type,\n    - allow these OpenID Connect scopes:\n      - aws.cognito.signin.user.admin\n      - email\n      - openid\n  - The user pool must have an app client configured, with:\n    - enabled auth flow `ALLOW_USER_PASSWORD_AUTH`, only for programmatic login flavor of test.\n    - The `cy.origin()` flavor of test only requires auth flow `ALLOW_USER_SRP_AUTH`, and does not require `ALLOW_USER_PASSWORD_AUTH`.\n  - The user pool must have a user corresponding to the `AWS_COGNITO` env vars mentioned below, and the user's Confirmation Status must be `Confirmed`. If it is `Force Reset Password`, then use a browser to log in once at `http://localhost:3000` while `yarn dev:cognito` is running to reset their password.\n\nThe test knobs are in a few places:\n\n- The `.env` file has `VITE_AUTH_TOKEN_NAME` and vars beginning `AWS_COGNITO`. Be careful not to commit any secrets.\n- Both `scripts/mock-aws-exports.js` and `scripts/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.\n- `cypress.config.ts` has `cognito_programmatic_login` to control flavor of the test.\n\nTo 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.\n\nThe **only passing spec on this branch** will be the [cognito spec](./cypress/tests/ui-auth-providers/cognito.spec.ts); all others will fail.\n\n### Google\n\nA [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.\n\nPrerequisites include an [Google][google] account. Environment variables from [Google][google] are to be placed in the [.env](./.env).\n\nTo 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`.\n\nThe **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.\n\n## License\n\n[![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/cypress-io/cypress/blob/master/LICENSE)\n\nThis project is licensed under the terms of the [MIT license](/LICENSE).\n\n[reactjs]: https://reactjs.org\n[xstate]: https://xstate.js.org\n[express]: https://expressjs.com\n[lowdb]: https://github.com/typicode/lowdb\n[typescript]: https://typescriptlang.org\n[cypresscloud]: https://cloud.cypress.io/projects/7s5okt/runs\n[material-ui]: https://material-ui.com\n[okta]: https://okta.com\n[auth0]: https://auth0.com\n[oktacreateapp]: https://developer.okta.com/docs/guides/sign-into-spa/react/create-okta-application/\n[cognito]: https://aws.amazon.com/cognito\n[awsamplify]: https://amplify.aws\n[google]: https://google.com\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://www.kevinold.com\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/21967?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eKevin Old\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://twitter.com/amirrustam\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/334337?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eAmir Rustamzadeh\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://twitter.com/be_mann\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1268976?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBrian Mann\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://glebbahmutov.com/\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/2212006?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eGleb Bahmutov\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"http://www.bencodezen.io\"\u003e\u003cimg src=\"https://avatars0.githubusercontent.com/u/4836334?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eBen Hong\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/davidkpiano\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/1093738?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eDavid Khourshid\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcypress-realworld-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypress-io%2Fcypress-realworld-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-io%2Fcypress-realworld-app/lists"}