Skip to main content

Use Argos with GitHub Actions

Configure GitHub Actions to send screenshots to Argos visual testing platform.

1. Install Argos CLI​

npm i --save-dev @argos-ci/cli

Read the CLI documentation if you need information about advanced usages.

2. Upload the screenshots​

Add the following command to your CI workflow to upload screenshots to Argos:

npm exec argos upload ./screenshots

Complete example​

.github/workflows/ci.yml
name: Argos

on:
  push:
    # Argos has to run on your reference branch to creates reference builds
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  argos:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository code
        uses: actions/checkout@v3

      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: current

      - name: Install dependencies
        run: npm ci

      # -----
      # 👉 Insert the steps required to take screenshots
      # -----

      - name: Upload screenshots to argos-ci.com
        continue-on-error: true
        # 👇 change "./screenshots" by your screenshots folder path
        run: npm exec argos upload ./screenshots

For a repository examples, check out our GitHub repository.

What's next?

Congratulations on installing Argos! 🎉
The next step is to integrate visual review into your development workflow. Visit our review changes section to learn how to.

Troubleshooting​

Force repository detection with ARGOS_TOKEN​

To ensure seamless integration with GitHub Actions, the ARGOS_TOKEN is usually not required. However, if the automatic repository detection doesn't work, you may need to specify the token. If that's the case, follow these steps:
  1. Log in to Argos, navigate to your project settings and copy your ARGOS_TOKEN.
  2. On GitHub, navigate to your repository settings and set a new repository secret called ARGOS_TOKEN with the value you have copied.
  3. Expose the ARGOS_TOKEN when you call the argos' upload command.
.github/workflows/ci.yml
- name: Upload screenshots to argos-ci.com
  continue-on-error: true
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
  run: npm exec argos upload ./screenshots

Why do my screenshots show elements not present in my local code?​

When running tests on GitHub, it defaults to performing tests on the merge commit. This means that it behaves as if a rebase had been done before running the tests. As a result, some elements may appear in your screenshots that are not visible in your local code.

It is not a problem with Argos because it is handled automatically by our system but it can be suprising.

If you wish to disable this behavior and have GitHub check out the pull request's HEAD commit instead of the merge commit, you can use the following configuration in your workflow file:

- uses: actions/checkout@v3
  with:
    ref: ${{ github.event.pull_request.head.sha }}

By specifying the ref parameter with the value ${{ github.event.pull_request.head.sha }}, you ensure that GitHub checks out the specific commit associated with the pull request, allowing your screenshots to accurately reflect the code changes made in that commit.

Make sure to update your workflow file with this configuration if you want to avoid including extraneous elements in your screenshots.