Skip to main content

Argos Command Line Interface (CLI)

The Argos Command Line Interface (CLI) easiest and fastest way to upload screenshots to the Argos visual testing platform. It should be exectuted by your CI.

@argos-ci/cli is available as an npm package and its source code can be found on GitHub.

Installation​

Install the @argos-cli package from npm:

npm i --save-dev @argos-cli

Configuration​

Argos uses a token called ARGOS_TOKEN to identify to which repository the screenshots you send are related to.

  • Step 1: Get the token value
    On Argos, go to the repository you want to set and click on the "settings" tab. Store the ARGOS_TOKEN value.

  • Step 2: Create a secret in your CI
    Set the ARGOS_TOKEN as an environment variable and paste the value you stored in the previous step.

Note: Instead of using an environment variable, you can also specify the token with the --token=<your-repository-token> argument, but this is not recommended.

Usage​

Upload Command​

Use the upload command to upload screenshots stored in the ./screenshots folder:

npx @argos-ci/cli upload ./screenshots

Help Command​

To see a list of available options, use the argos help command:

npx @argos-ci/cli help upload

Advanced Usage​

Running Multiple Argos Builds on the Same Commit​

To run multiple builds for the same commit, assign a name to the Argos build using the --build-name argument.

In this example, we create one build for components and another for E2E:

npx @argos-ci/cli upload --build-name components ./screenshots/components
npx @argos-ci/cli upload --build-name e2e ./screenshots/e2e

Parallel Test Suites​

Parallelism is a technique for speeding up test suites by running multiple tests concurrently and then combining the results at the end.

To configure parallel test suites using @argos-ci/cli, you need to set two environment variables:

  • ARGOS_PARALLEL_NONCE: a unique build ID for this parallel build. Argos groups uploaded screenshots using this ID.
  • ARGOS_PARALLEL_TOTAL: the total number of parallel nodes being run. argos upload must be called exactly this number of times.

Note: It is also possible to configure parallel mode using the --parallel-nonce and --parallel-total arguments.

Once configured, the @argos-ci/cli upload command can be run multiple times to aggregate screenshots in the same build

ARGOS_PARALLEL_NONCE=<unique-build-id> ARGOS_PARALLEL_TOTAL=<total-batch-count> argos upload --parallel ./screenshots