Cypress End‐to‐End Tests with GitHub Actions Workflow

This documentation outlines the steps to set up Cypress end-to-end tests in a project using GitHub Actions. The workflow runs automatically every 15 minutes and can also be triggered manually. It includes setting up the environment, running the tests heedlessly, generating a report, and copying the results to a remote server.

---

1. Setting Up Cypress in Your Project

Before configuring GitHub Actions, you need to set up Cypress in your project:

1. Install Cypress and Mochawesome Reporter:

   • Navigate to your project directory and install the required packages:

     npm install cypress --save-dev
     npm install cypress-mochawesome-reporter --save-dev

2. Configure Cypress:

   • Open the cypress.json (or cypress.config.js if you’re using the latest Cypress version) and configure the Mochawesome reporter:

     {
       "reporter": "cypress-mochawesome-reporter",
       "reporterOptions": {
         "reportDir": "cypress/reports",
         "overwrite": false,
         "html": false,
         "json": true
       }
     }

3. Set Up Cypress Tests:

   • Create your Cypress test files under cypress/integration/. For example, example.spec.js.

2. Configuring GitHub Actions Workflow

Create a GitHub Actions workflow file in your repository to automate the testing process.

1. Create the Workflow File:

   • In your project, navigate to .github/workflows/ and create a new file named cypress-tests.yml.

2. Define the Workflow:

   • Add the following configuration to your cypress-tests.yml:

     name: Cypress E2E Tests
     
     on:
       schedule:
         - cron: '*/15 * * * *'  # Runs every 15 minutes
       workflow_dispatch:         # Allows manual triggering
     
     jobs:
       e2e-tests:
         runs-on: self-hosted  # Using self-hosted runner
     
         env:
           SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
           REMOTE_SERVER: ${{ secrets.REMOTE_SERVER }}
           REMOTE_PATH: ${{ secrets.REMOTE_PATH }}
     
         steps:
           - name: Checkout repository
             uses: actions/checkout@v4
     
           - name: Change directory to cypress_tests
             run: cd cypress_tests
     
           - name: Setup Node.js
             uses: actions/setup-node@v4
             with:
               node-version: '20'
     
           - name: Install system dependencies
             run: sudo apt-get install -y xvfb
     
           - name: Install project dependencies
             run: npm install
     
           - name: Run Cypress tests
             run: xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" npx cypress run
     
           - name: Generate Mochawesome report
             run: npx mochawesome-merge cypress/reports/*.json | npx mochawesome-report-generator -o cypress/reports
     
           - name: Copy reports to remote server
             uses: appleboy/[email protected]
             with:
               host: ${{ secrets.REMOTE_SERVER }}
               username: ${{ secrets.SSH_USERNAME }}
               key: ${{ secrets.SSH_PRIVATE_KEY }}
               target: ${{ secrets.REMOTE_PATH }}
               source: "cypress/reports/*"

   • Explanation of Key Components:

     • Triggers:

       • The workflow runs every 15 minutes using a cron schedule.
       • It can also be triggered manually with workflow_dispatch.

     • Job Configuration:

       • The workflow uses a self-hosted runner.
       • Environment variables for SSH access are set using GitHub secrets.

     • Steps:

       • Checkout repository: Uses actions/checkout@v4 to pull the latest code.
       • Change directory: Switches to the cypress_tests directory where your tests are located.
       • Setup Node.js: Installs Node.js version 20 using actions/setup-node@v4.
       • Install system dependencies: Installs xvfb, which is necessary for headless browser testing.
       • Install project dependencies: Installs all the dependencies required by the project, including Cypress.
       • Run Cypress tests: Runs the tests headlessly using xvfb-run to simulate a display environment.
       • Generate Mochawesome report: Merges and generates the test report using mochawesome.
       • Copy reports to remote server: Uses appleboy/[email protected] to securely copy the generated reports to a remote server.

3. Setting Up GitHub Secrets

For secure handling of sensitive information such as SSH keys and server details, use GitHub Secrets:

1. Add Secrets:
   • Go to your GitHub repository settings and navigate to Secrets and variables > Actions.
   • Add the following secrets:
     • SSH_PRIVATE_KEY: Your private SSH key.
     • REMOTE_SERVER: The IP address or hostname of your remote server.
     • REMOTE_PATH: The destination path on the remote server where reports will be copied.
     • SSH_USERNAME: The SSH username for the remote server.

4. Running the Workflow

Once the workflow is configured:

1. Automatic Execution:

   • The workflow will run every 15 minutes as per the cron schedule.

2. Manual Trigger:

   • You can manually trigger the workflow from the Actions tab in your GitHub repository.

3. Reviewing Reports:

   • After execution, test reports will be copied to the specified remote server, where they can be accessed for review.

---

This setup ensures that Cypress end-to-end tests are run consistently, and results are securely archived for further analysis.