Using the Selenium IDE Runner

The Selenium IDE Runner (called SIDE Runner here for short) is a command line tool that allows you to run a project .side file, created using Selenium IDE, on a Node.js platform. You can read how to use the SIDE Runner in the Selenium IDE documentation. This article, supplements that documentation, by describing how to pass the various SIDE Eyes options to the SIDE runner.

One time setup

You typically need to do the following steps only once.
  • Install the SIDE runner as described in this Selenium IDE documentation.
  • Assign your API KEY to an environment variables named APPLITOOLS_API_KEY. This is the same value that appears in the in global options menu, in the Account tab API KEY field.
  • If your Eyes server is not in the public cloud, i.e., you have a dedicated cloud or on-premise server, then set the environment variable APPLITOOLS_SERVER_URL to the appropriate URL. This is the same value that appears in the SERVER URL field of the Account tab.

Running a Project .side file

The following sections explain how to use the SIDE Runner. The first section describes how to run a project file using the default options, and the sections that follow describe how to specify various SIDE Eyes options. The description is generic and is followed by an example using a bash command line syntax. Command line for other platforms should be very similar.

Running just the .side file.

In the simplest case, where you have a script that does not use Ultrafast Grid or branching you can run a .side file as follows:
  • Save your project file to a directory, for example, named /mypath/myproject.side
  • Run the file using the following command in your command line:
    • $ selenium-side-runner /mypath/myproject.side

Using branches

If your project uses branches, then you should copy the branch name and parent branch name in the SIDE Eyes menu (e.g. "myBranch", and "myParent") and assign them to the environment variables APPLITOOLS_BRANCH and APPLITOOLS_PARENT_BRANCH respectively :


$ APPLITOOLS_PARENT_BRANCH="myParent"
$ APPLITOOLS_BRANCH="myBranch"	
$ selenium-side-runner /mypath/myproject.side

If you always work with the same branch, then obviously you can set these environment variables permanently.

Using Ultrafast Grid

If you want to run your project using Ultrafast Grid settings that you set up in the IDE, then proceed as follows:

  • In the SIDE Eyes menu, click the download button near the Execute using Ultrafast Grid checkmark:
  • SIDE Eyes saves Ultrafast Grid parameters to a file called visual-grid-config.yml in your download folder. For example, let's assume that the folder is called "/downloads".
  • When you call the SIDE Runner, pass this file to the SIDE Runner as follows:
    • $ selenium-side-runner --config "/downloads/visual-grid-config.yml" /mypath/myproject.side
  • Now when you run the SIDE Runner the options in this file is read and used. Note that if you want to add other options to the configuration file, then you should copy the configuration values in the visual-grid-config.yml file to a new configuration file, add your configurations, and then pass that file to the --config option instead of the visual-grid-config.yml file.

enable/disable visual checkpoints

If you want to run the test without visual checkpoints, then call the SIDE Runner as follows. Visual checkpoints are enabled by default; the example below shows how to disable visual checkpoints.

$ selenium-side-runner --params="eyesDisabled=true" /mypath/myproject.side

enable/disable Root cause analysis

By default, the SIDE Runner sends DOM information required for Root cause analysis. If you want to disable sending DOM information then call the SIDE Runner as follows:

$ selenium-side-runner --params="eyesDomUploadEnabled=false" /mypath/myproject.side

eyesLogsEnabled

If you enable this flag, the SIDE Runner outputs log information. The information displayed may help troubleshoot some types of problems. This option is disabled by default.

$ selenium-side-runner --params="eyesLogsEnabled=true" /mypath/myproject.side

Multiple options

If you want to pass the SIDE Runner multiple, setup options, then pass both parameters in the same --params argument as follows: 

$ selenium-side-runner --params="eyesDisabled=true eyesDomUploadEnabled=false" /mypath/myproject.side