---
tags: English
---

# SideeX Runner
SideeX Runner is a tool that supports playing SideeX-recorded test cases in command line mode.

## Quick Start

> Prerequisite:
> - [Java SE](https://www.oracle.com/java/technologies/javase-downloads.html)
> - [Node.js](https://nodejs.org)

### Step 1 - Start Selenium Server
1. Download [Selenium Server](https://www.seleniumhq.org/download/) (Tested version: 3.141.59)
2. Download the [WebDriver](/@sideex/book/%2F%40sideex%2Fwebdriver) and put it in the same folder as `selenium-server-standalone-{version}.jar`.
3. Open the terminal and switch to the path to the `selenium-server-standalone-{version}.jar`
4. Run `java -jar selenium-server-standalone-{version}.jar`

### Step 2 - Execute SideeX Runner
1. Open command line mode and run `npm i -g @sideex/runner`
2. Run `sideex-runner --config {CONFIG_FILE_PATH}`. For example, when running with the following config file, all of the test cases in the test suite will be run with Chrome through WebDriver under command line mode. See [Appendix A](##-Appendix-A---SideeX-Runner-Config-File-Format) for the config file format.

    {
        "input": {
            "testSuites": ["YOUR_TESTSUITE_FILE_PATH"]
        },

        "webdriver": {
            "configs": [
                {
                    "serverUrl": "http://localhost:4444",
                    "type": "selenium",
                    "browsers":[
                        {
                            "active": true,
                            "capability": {
                                "browserName": "chrome"
                            }
                        }
                    ]
                }
            ]
        }
    }

### Step 3 - View, Send, or Parse Test Reports
- **View Test Reports**: The test reports will be generated under the directory specified in the config file. The file format can be HTML or JSON. The HTML files can directly opened in Browser for human inspection. The JSON files are intended for being parsed by programs.
- **Send Test Reports**: The test reports can be sent to Email, Slack, or Line (See [Appendix A](##-Appendix-A---SideeX-Runner-Config-File-Format))
- **Output Data**: The test reports will contain the latest values of all local and global variables defined in test cases. Sometimes these values are useful for debugging and can be further processed by the other programs. See [Test Report Specification](https://hackmd.io/@sideex/book/%2F%40sideex%2Freportspec)

## Appendix A - SideeX Runner Config File Format
An example config file: *config.json*

{
    "input": {
        "testSuites": ["./testsuite1.html", "./testsuite2.html", "./testsuite3.html"],
        "variables": ["./globalvar.json"]
    },

    "play": {
        "mode": 2,
        "entry": "",
        "noLog": false,
        "speed": 5,
        "autoWaitTimeout":30,
        "period": {
            "time": -1,
            "maxNum": -1
        }
    },

    "report": {
        "path": "./",
        "type":"html",
        "snapshot": 2,
        "snapshotQuality": 20
    },

    "webdriver": {
        "configs": [
            {
                "serverUrl": "http://localhost:4444",
                "type": "selenium",
                "browsers":[
                    {
                        "active": true,
                        "capability": {
                            "browserName": "chrome",
                            "goog:chromeOptions": {
                                "args": [
                                    "headless",
                                    "disable-gpu",
                                    "window-size=1080,720",
                                    "no-sandbox"
                                ]
                            }
                        }
                    },
                    {
                        "active": true,
                        "capability": {
                            "browserName": "firefox",
                            "moz:firefoxOptions": {
                                "args": [
                                    "-headless",
                                    "-disable-gpu",
                                    "-window-size=1080,720"
                                ]
                            }
                        }
                    }
                ]
            }
        ],
        
        "i18n": {
            "ja": "./ja.json"
        }
    },
    
    "mail": {
        "active": 2,
        "configs": {
          "transport": {
            "host": "smtp.gmail.com",
            "port": 465,
            "secure": true,
            "auth": {
              "user": "[e-mail]",
              "pass": "your_password"
            }
          },
          "mailer": {
            "from": "\"your_title\" <[e-mail]>",
            "to": "[e-mail], [e-mail]",
            "subject": "The test reports generated by SideeX Runner",
            "html": "<p>Type your own mail body here</p>"
          }
        }
    },
    
    "slack": {
        "active": 2,
        "configs": {
            "token": "your_slack_token",
            "channel": "your_channel",
            "text": "Here comes the test reports generated by SideeX Runner"
        }
    },
    
    "line": {
        "active": 2,
        "configs": {
            "token": "your_line_notify_token",
            "text": "Here comes the test reports generated by SideeX Runner"
        }
    }
}

:::info
Note that: The **webdriver** and **play** parts can be copied from the file exported by the Option page of SideeX Recorder. See [SideeX Recorder to WebDriver](https://hackmd.io/@sideex/webdriver) for more information about WebDriver settings.
:::

Format description:
- **input**
- **testSuites**
- Description: Set the file paths to the test suites
- Value: A string array
- Default: `[]`
- **variables**
- Description: Set the file paths to the variable files. Only accept `json` and `csv` files.
- Value: A string array
- Default: `[]`
- **play**
- **mode**
- Description: The mode of playback.
- Value: `0`, `1`, or `2`
- Default: `2`
- **entry**
- Description: The entry test case or test suite when running.
- If `mode`=`0`, this field should be set to a full name of test case, e.g. `testsuite1.testcase1`.
- If `mode`=`1`, this field should be set to a test suite, e.g. `testsuite2`.
- If `mode`=`2`, this field will be ignored.
- Value: A string
- Default: `""`
- **noLog**
- Description:
- Set to `true` to disable the log.
- Value: boolean
- Default: `false`
- **speed**
- Description: The speed of the playback. `5` is the fast speed.
- Value: `1`, `2`, `3`, `4`, or `5`.
- Default: `5`
- **autoWaitTimeout**
- Description: The timeout before executing the next command.
- Value: A number (in seconds)
- Default: `30`
- **period**
- **time**
- Description: The duration of the periodical running. Set to `-1` to disable the periodical running.
- Value: A number (in seconds)
- Default: `-1`
- **maxNum**
- Description: The maximum number of times of the periodical running. Set to `-1` to run infinitely.
- Value: A number
- Default: `-1`
- **report**
- **type**
- Description: The type of the test report.
- Value: `"html"` , `"json"` or `"all"`
- Default: `"html"`
- **path**
- Description: The path for saving the test report. If the path does not exist, a folder of the path will be automatically created before running.
- Value: A string
- Default: `""`
- **snapshot**
- Description: Playback with snapshots
- `0` : No snapshot
- `1` : Capture snapshots on errors
- `2` : Always capture snapshots
- Value: `0`, `1`, or `2`
- Default: `2`
- **snapshotQuality**
- Description: Snapshot quality ranging from 1 to 100. 100 is the highest quality. A higher quality value will require more disk space.
- Value: `1` to `100`.
- Default: `20`

- **webdriver**
- **configs**
- **serverUrl**
- Description: The URL of the WebDriver server.
- Value: A URL string
- Default: `""`
- **type**
- Description: The type of the WebDriver server.
- Value: `"selenium"` or `"appium"`
- Default: `"selenium"`
- **browsers**
- Description: The browser capabilities to be matched
- Value: An array
- Default: `[]`
- **active**
- Description: Activate or inactivate the browser.
- Value: boolean
- Default: `true`
- **capability**
- **browserName**
- Description: The browser name.
- Value:
- For desktop browsers: `"chrome"`, `"firefox"`, `"MicrosoftEdge"`, `"safari"` or `"opera"`.
- For mobile browsers: See [here](https://hackmd.io/@sideex/webdriver#Mobile-Browsers).
- **platformName**
- Description: The platform
- Value:
- For desktop browsers: `"WINDOWS"`, `"LINUX"`, or `"MAC"`
- For mobile browsers: See [here](https://hackmd.io/@sideex/webdriver#Mobile-Browsers).
- **browserVersion**
- Description: The browser version.
- Value: A string
- **(More Options)**
More options that follow W3C WebDriver Capability spec. For example, you can start the headless mode for different browsers:

                     // For Chrome
                     "goog:chromeOptions": {
                         "args": [
                             "headless",
                             "disable-gpu",
                             "window-size=1080,720",
                             "no-sandbox"
                         ]
                     }
                     // For Firefox
                     "moz:firefoxOptions": {
                        "args":   [
                            "-headless",
                            "-disable-gpu",
                            "-window-size=1080,720"
                        ]
                     }
    - **i18n**
        - Description:
            - Language codes and files paths. All the language codes can be found in the Option page of SideeX Recorder. All the languages set here will be run in order. See [Internationalization (i18n) Testing Using SideeX](/@sideex/book/%2F%40sideex%2Fi18n) for more information.
        - Value: Mapping from language codes to language files.

{
"ja": "./ja.json",
"ZH-tw": "./tw.json"
}

        - Default: `undefined`
- **mail**
Sending reports via an SMTP server. Note that, if you use Gmail as your SMTP server, you need to create an [application password](https://support.google.com/mail/answer/185833) first.
    - **active**
        - Description
            - `0` : No sending
            - `1` : Sending on errors
            - `2` : Always sending
        - Value: `0`, `1` or `2`
        - Default: `0`
    - **configs**
        - **transport**
            - Description: Refer to the [SMTP Transport](https://nodemailer.com/smtp/) config 
            - Value: For example:

{
"host": "smtp.gmail.com",
"port": 465,
"secure": true,
"auth": {
"user": "[e-mail]",
"pass": "your_password"
}
}

            - Default: `undefined`
        - **mailer**
            - Description: Refer to the [Message](https://nodemailer.com/message/) config
            - Value: For example:

{
"from": "\"your_title\" <[e-mail]>",
"to": "[e-mail], [e-mail]",
"subject": "The test reports generated by SideeX Runner",
"html": "<p>Type your own mail body here</p>"
}

            - Default: `undefined`
            
- **slack**
Sending reports via Slack. You have to prepare a [Slack token and channel](/@sideex/slack) at first.
    - **active**
        - Description
            - `0` : No sending
            - `1` : Sending on errors
            - `2` : Always sending
        - Value: `0`, `1` or `2`
        - Default: `0`
    - **configs**
        - **token**
            - Description: The token of the slack app
            - Value: A string
            - Default: `""`
        - **channel**
            - Description: The slack workspace channels
            - Value: A string
            - Default: `""`
        - **text**
            - Description: The text showing in front of the test report summary
            - Value: A string
            - Default: `""`

- **line**
Sending reports via Line Notify. You have to prepare a [Line Notify token](https://hackmd.io/@sideex/line-notify) at first.
    - **active**
        - Description
            - `0` : No sending
            - `1` : Sending on errors
            - `2` : Always sending
        - Value: `0`, `1` or `2`
        - Default: `2`
    - **configs**
        - **token**
            - Description: The token of the Line Notify
            - Value: A string
            - Default: `""`
        - **text**
            - Description: The text showing in front of the test report summary
            - Value: A string
            - Default: `""`