How to Use Cypress with GitHub Actions for Automated Testing

To use Cypress with GitHub Actions, create a workflow YAML file in your repository's .github/workflows folder that installs dependencies, runs Cypress tests, and reports results. This setup automates your tests on every push or pull request, ensuring your app works as expected.

Syntax

The GitHub Actions workflow for Cypress typically includes these parts:

• name: The workflow's name.
• on: Events that trigger the workflow, like push or pull_request.
• jobs: Defines tasks to run, usually a test job.
• runs-on: The virtual machine environment, e.g., ubuntu-latest.
• steps: Series of commands like checking out code, installing dependencies, and running Cypress tests.

yaml

name: Cypress Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run Cypress tests
        run: npx cypress run

Example

This example shows a complete GitHub Actions workflow that runs Cypress tests on every push or pull request. It checks out your code, installs dependencies with npm ci, and runs Cypress tests using npx cypress run. The test results will appear in the GitHub Actions interface.

yaml

name: Run Cypress Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Use Node.js 18
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run Cypress tests
        run: npx cypress run

Output

GitHub Actions shows the workflow running with steps: checkout, setup node, install dependencies, and Cypress tests running. Tests pass or fail with logs visible in the Actions tab.

Common Pitfalls

Common mistakes when using Cypress with GitHub Actions include:

• Not installing dependencies properly, causing tests to fail.
• Forgetting to set up Node.js version, leading to environment mismatches.
• Running Cypress without a display server on Linux runners; use cypress run which runs headlessly.
• Not caching node_modules to speed up workflow runs.

Always check logs for errors and ensure your package.json scripts and Cypress config are correct.

yaml

name: Wrong Setup Example
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Cypress tests without install
        run: npx cypress run

---

name: Correct Setup Example
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Run Cypress tests
        run: npx cypress run

Quick Reference

Step	Purpose	Example
actions/checkout@v3	Get your repo code	uses: actions/checkout@v3
Install dependencies	Install npm packages	run: npm ci
Setup Node.js	Use correct Node version	uses: actions/setup-node@v3 with node-version: '18'
Run Cypress tests	Execute tests headlessly	run: npx cypress run
Trigger events	When to run tests	on: [push, pull_request]

Key Takeaways

Create a GitHub Actions workflow YAML file in .github/workflows to automate Cypress tests.

Always install dependencies before running Cypress tests to avoid failures.

Use the latest Node.js version with setup-node action for consistent environments.

Run Cypress tests headlessly with npx cypress run on GitHub's Linux runners.

Check GitHub Actions logs to debug and fix common setup issues quickly.