Asayer CLI

How to use Asayer Synthetics CLI.

Installation

$ npm i -g @asayer/asayer-cli

Usage

$ asayer --help

  Usage: asayer [options] [command]
       _                              _          ____ _     ___ 
      / \   ___  __ _ _   _  ___ _ __(_) ___    / ___| |   |_ _|
     / _ \ / __|/ _` | | | |/ _ \ '__| |/ _ \  | |   | |    | | 
    / ___ \\__ \ (_| | |_| |  __/ |_ | | (_) | | |___| |___ | | 
   /_/   \_\___/\__,_|\__, |\___|_(_)|_|\___/   \____|_____|___|
                      |___/                                     
  Options:
    -V, --version                      Output the version number
    -t, --token <token>                User token from Asayer Dashboard
    -u, --url <url>                    Custom test URL, overrides the environment's URL
    -T, --tests <test1,test2,...>      List containing test Ids to be executed (separated by a comma)
    -e, --environment <environmentId>  Environment Id
    -d, --debug                        Debug console errors
    -h, --help                         Display help for command
  
  Commands:
    setup [options]                    Configure your Asayer CLI
    local [options]                    Use a local server for Asayer on-premise
    docker [options]                   Configure docker for local testing
  If --tests is not present, you will be guided by the interactive mode.
  Command's help:
    $ asayer [command] --help
    Examples:
      $ asayer setup --help

$ asayer setup --help

  Usage: asayer setup [options]
  Configure your Asayer CLI
  Options:
    -t, --token <token>  User token from Asayer Dashboard
    -h, --help           Display help for command
  If --token is not present, you will be guided by the interactive mode.

$ asayer local --help

  Usage: asayer local [options]
  Use a local server for Asayer on-premise
  Options:
    -t, --token <token>                User token from Asayer Dashboard
    -T, --tests <test1,test2,...>      List containing test Ids to be executed (separated by a comma)
    -u, --url <url>                    Custom test URL, overrides the environment's URL
    -U, --update                       Update images
    -c, --clean                        Clean residual containers
    -S, --stop-all                     Stop all running tests
    -n, --network <network>            Network type to use, possible values "bridge", "host", "container:<name|id>", "<custom>"  (default: "host")
    -h, --extra-hosts <hostname:ip>    List of hostname:ip mapping separated by comma ","
    --dns-name <dns>                   List of dns names separated by comma "," (example "host.docker.internal")
    --dns-ip <dns-ip>                  List of DNS IPs separated by comma ","
    --tags <tags>                      List of tags separated by comma "," (default: ["CLI","local"])
    -M, --max-memory <memory>          The maximum memory limit in Mb, must be >= to minMemory (the default value is in Bytes) (default: 2147483648)
    -m, --min-memory <memory>          The minimum memory limit in Mb, must be <= to maxMemory (the default value is in Bytes) (default: 2147483648)
    -f, --fail-code <exitCode>         Exit code when test fails (default: 1)
    --no-remove                        Don't remove the container after test
    -N, --no-limit                     Don't use any memory limits
    -q, --queue <size>                 Execution queue size (default: 2)
    -e, --environment <environmentId>  Environment Id
    --help                             Display help for command
  If --tests is not present, you will be guided by the interactive mode.

$ asayer docker --help

  Usage: asayer docker [options]
  Configure docker for local testing  
  Options:
    -v, --verify                  Verify if the current docker connection is valid
    -C, --config                  Use the provided config options
    -h, --host <host>             The docker host address, used with --config (default: "127.0.0.1")
    -p, --port <port>             The docker host port, used with --config (default: 2375)
    -P, --protocol <protocol>     The docker host protocol, used with --config (default: "auto detect")
    -c, --cert-dir <path>         The docker host's certificate directory, used with --config (default: "/etc/docker/certs.d/")
    --cert <client cert>          The path or name of the client's certificate file, used with --config (default: "cert.pem")
    --key <client key>            The path or name of the client's key file, used with --config (default: "key.pem")
    --ca <certificate authority>  The path or name of the certificate authority file, used with --config (default: "ca.pem")
    --no-check                    Don't check the server identity, used with --config
    --docker-version <version>    The docker version, used with --config (default: "auto detect")
    --show                        Print the current configuration
    --default                     Use default config
    -r, --reset                   Reset configuration to default
    --help                        Display help for command
  If --config is not present, you will be guided by the interactive mode.

Token Configuration

Start by copying your organization token from Preferences. Configure your token by following one of the below steps:

• Saving your token, so you don't have to specify it with each command:
  • Interactive mode: asayer setup
  • Direct method: asayer setup --token "MY_TOKEN"
• Using the environment variable ASAYER_TOKEN
• Using the option --token "MY_TOKEN" when executing each command

In case there are several methods configured, the following order would apply:

1. --token "MY_TOKEN"
2. The environment variable
3. The saved token

Run Tests in Asayer Cloud

• To select the tests to run using the interactive mode: asayer
• To specify which tests to run on default environment: asayer --tests "TEST_ID1,TEST_ID2"
• To specify which tests to run on a specific environment: asayer --tests "TEST_ID1,TEST_ID2" --environment "ENVIRONMENT ID"
• To override the test/environments's URL, add this option to any of the previous commands: --url "https://asayer.io"

Run Tests On-Premise

Running on-premise tests requires docker to be installed on the host.

Setup

Running tests locally on your host makes Asayer CLI interact with docker. To configure that, follow one of the below steps:

• Default configuration: to check if the default configuration works use asayer docker --verify
• Interactive mode: asayer docker
• Direct method: asayer docker --config --host "127.0.0.1" --port 3000 --protocol "https"
  • Any missing option will be replaced by the default value
  • List of available options:
    • -h, --host <host>: docker host address (default: "127.0.0.1")
    • -p, --port <port>: docker host port (default: 2375)
    • -P, --protocol <protocol>: docker host protocol (default: "auto detect")
    • -c, --cert-dir <path>: docker host's certificate directory (default: "/etc/docker/certs.d/")
    • --cert <client cert>: path or name of the client's certificate file (default: "cert.pem")
    • --key <client key>: path or name of the client's key file (default: "key.pem")
    • --ca <certificate authority>: path or name of the certificate authority file (default: "ca.pem")
    • --no-check: don't check the server identity
    • --docker-version <version>: docker version (default: "auto detect")

Run Tests

To run your tests locally:

• Use interactive mode: asayer local
• Run selected tests on default environment: asayer local --tests "TEST_ID1,TEST_ID2"
• Run selected tests on a specific environment: asayer local --tests "TEST_ID1,TEST_ID2" --environment "ENVIRONMENT_ID"
• To override the test/environment's URL, add this option to the previous command: --url "https://asayer.io"
• To change the queue size in order to run more than 2 tests at the same time, use the option: --queue INTEGER

Stop Runs

In case you lost the connection with the terminal or started the asayer local command in the background, the containers will keep running until all tests are finished. You can use asayer local --stop-all to stop them.