Use Argos with GitHub Actions
Configure GitHub Actions to send screenshots to Argos visual testing platform.
1. Install Argos CLI
- npm
- yarn
- pnpm
- bun
npm i --save-dev @argos-ci/cli
yarn add --dev @argos-ci/cli
pnpm add --save-dev @argos-ci/cli
bun add --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
- yarn
- pnpm
- bun
npm exec argos upload ./screenshots
yarn run argos upload ./screenshots
pnpm exec argos upload ./screenshots
bun x argos upload ./screenshots
Complete example
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:- Log in to Argos, navigate to your project settings and copy your
ARGOS_TOKEN
. - On GitHub, navigate to your repository settings and set a new repository secret called
ARGOS_TOKEN
with the value you have copied. - Expose the
ARGOS_TOKEN
when you call the argos' upload command.
- 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.