Integrate TestCafe with GitHub Actions

This topic describes how to use the Run TestCafe action to integrate TestCafe tests into the GitHub Actions build process.

Step 1 - Create a Workflow

Create a YAML file (for instance, testcafe-workflow.yml) in the .github/workflows directory in your repository.

Specify the workflow name and the event that triggers this workflow.

name: End-to-End Tests
on: [push]

In this example, the workflow runs when you push changes to the repository.

Step 2 - Create a Job

Create a job that runs the TestCafe tests.

Provide the job name and specify the type of machine that should run the job.

You can use a GitHub-hosted machine:

name: End-to-End Tests
on: [push]

jobs:
  test:
    name: Run TestCafe Tests
    runs-on: windows-latest

This job runs on a GitHub-hosted virtual machine with the latest Windows version. test is the job ID that must be unique to the jobs object.

You can use a GitHub-hosted virtual machine with a variety of operating systems to run tests, as listed on the following page: GitHub Docs. For simplicity, all examples in this article run on windows-latest.

Github Actions use the macOS Catalina 10.15 virtual environment with "System Integrity Protection" enabled as macos-latest. With this setting enabled, TestCafe requires screen recording permission, which cannot be obtained programmatically. For this reason, TestCafe is unable to run tests with GitHub Actions locally on macos-latest.

However, tests can run on macOS virtual machines if you connect the browser as remote.

Example

export HOSTNAME=localhost
export PORT1=1337
export PORT2=1338
testcafe remote test.js --hostname ${HOSTNAME} --ports ${PORT1},${PORT2} &
pid=$!
open -a Safari http://${HOSTNAME}:${PORT1}/browser/connect
wait $pid

Alternatively, you can host your own runners for the job. This gives you more precise control over the environment.

To set up the self-hosted runners, add them to your repository.

After that, configure runs-on in your workflow .yml file:

name: End-to-End Tests
on: [push]

jobs:
  test:
    name: Run TestCafe Tests
    runs-on: [self-hosted, linux]

Make sure that the intended machine meets the requirements for self-hosted runner machines.

For more information about self-hosted runners in the GitHub Actions workflow, refer to the following topic: Using self-hosted runners in a workflow.

Step 3 - Add a Step that Fetches the Repository

Add a step that uses the checkout action to fetch your repository content.

name: End-to-End Tests
on: [push]

jobs:
  test:
    name: Run TestCafe Tests
    runs-on: windows-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v1

Step 4 - Add a Step that Runs TestCafe

Add the Run TestCafe action. Use the args parameter to provide TestCafe command line arguments.

name: End-to-End Tests
on: [push]

jobs:
  test:
    name: Run TestCafe Tests
    runs-on: windows-latest
    steps:
      - name: Check out the repository
        uses: actions/checkout@v1
      - name: Run tests
        uses: DevExpress/testcafe-action@latest
        with:
            args: "chrome tests"

Action Options

args

TestCafe command line arguments.

- uses: DevExpress/testcafe-action@latest
  with:
    args: "chrome fixture.js -s takeOnFails=true -q -c 3"

version

Optional

The TestCafe version to install.

- uses: DevExpress/testcafe-action@latest
  with:
    version: "1.6.0"
    args: "chrome tests"

Default value: latest

Example

The following workflow demonstrates how to run TestCafe tests across Node.js versions and operating systems.

name: Target Multiple Node.js Versions and Operating Systems
on: [push]

jobs:
  build:
    name: Run Tests Across Node.js Versions and Operating Systems
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [8, 10, 12]
    steps:
      - uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
      - uses: actions/checkout@v1
      - name: Run TestCafe Tests
        uses: DevExpress/testcafe-action@latest
        with:
          args: "chrome tests"

This job contains a matrix strategy that duplicates it to run on Windows and Ubuntu virtual machines in three Node.js versions (8, 10, and 12).

The setup-node action installs the Node.js version defined in the matrix. Then, checkout fetches the code and testcafe-action runs tests.