Skip to content

docs: add introduction to README #1416

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jennifer-shehane merged 1 commit into from
Mar 28, 2025
Merged

docs: add introduction to README #1416

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 23 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,28 @@
# cypress-io/github-action [![Action status][ci-badge]][ci-workflow] [![cypress][cloud-badge]][cloud-project] [![renovate-app badge][renovate-badge]][renovate-bot]

> [GitHub Action](https://docs.github.com/en/actions) for running [Cypress](https://www.cypress.io) end-to-end and component tests. Includes npm, pnpm and Yarn installation, custom caching and lots of configuration options.

Placing `use: cypress-io/github-action@v6` into a GitHub Action workflow gives you a simple way to run Cypress. The action takes the project's npm, pnpm or Yarn package manager lock file and installs dependencies with [caching](#caching). It then proceeds to run Cypress end-to-end tests with the built-in Electron browser and provides a test summary after completion.

If you are testing against a running server like the [Cypress Kitchen Sink showcase example](https://example.cypress.io/) on https://example.cypress.io/ no other parameters are necessary. In other cases where you need to fire up a development server, you can add the [start](#start-server) parameter to the workflow. Browse through the examples to find other useful parameters.
> [Cypress](https://www.cypress.io) based `cypress-io/github-action` runs [End-to-End](#end-to-end-testing) or [Component](#component-testing) tests in [GitHub Actions](https://docs.github.com/en/actions/) Continuous Integration (CI) workflows, optionally [recording](#record-test-results-on-cypress-cloud) to [Cypress Cloud](https://on.cypress.io/guides/cloud/introduction)

## Introduction

In addition to running Cypress tests, the action includes [dependency installation](#installation), [caching](#caching) and more:

| Function | Benefits |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Single-line call](#end-to-end-testing) | Simplified use by installing dependencies and running Cypress in one line of workflow code |
| [Build app](#build-app), [Start server](#start-server) and [Wait for server](#wait-on) options | Convenience of app, server and test coordination |
| [cypress run](https://docs.cypress.io/app/references/command-line#cypress-run) CLI type options | Improved readability with vertically listed workflow options |
| [Dependency installation](#installation) based on [npm](https://docs.npmjs.com/cli/configuring-npm/package-lock-json), [pnpm](https://pnpm.io/git#lockfiles) and [Yarn Classic](https://classic.yarnpkg.com/en/docs/yarn-lock) lock files | Reduced command complexity |
| [Caching](#caching) of Cypress binary and dependencies for [npm](https://docs.npmjs.com/cli/commands/npm-cache) and [Yarn Classic](https://classic.yarnpkg.com/lang/en/docs/cli/cache/) installations | Reduced download bandwidth requirements |
| [Job summary](#job-summary-title) | Fast access to results overview |
| [Docker](#docker-image) compatibility | Improved independence from [GitHub-hosted runner image](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) version changes. Fixed Docker environments can be used. |
| [Recording](#record-test-results-on-cypress-cloud) to Cypress Cloud compatibility including [parallel](#parallel) execution | Improved interpretation of test results through [Cypress Cloud](https://on.cypress.io/cloud) |
| [Live examples](#examples) | Speeds up introduction and troubleshooting |
| [Yarn Modern](#yarn-modern) usage and cache examples | Extends usage beyond [Yarn Classic](https://classic.yarnpkg.com/) |
| [pnpm cache examples](#pnpm) | Reduced download bandwidth requirements for [pnpm](https://pnpm.io/) |
| [Debug](#debugging) enabled | Improved workflow troubleshooting |
| [Ping utility](#debugging-waiting-for-url-to-respond) | Improved server reachability troubleshooting |

The following examples demonstrate the actions' functions.

## Examples

Expand Down