---
title: SideeX Runner
tags: Chinese
---

# SideeX Runner
SideeX Runner是一個命令列介面(Command Line Interface)工具，支援在命令列模式下播放由SideeX Recorder錄製出的測試案例。

## 快速入門

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

### 步驟1：啟動Selenium Server
1. 下載[Selenium Server](https://www.seleniumhq.org/download/) (已測版本：3.141.59)
2. 下載[WebDriver](/@sideex/webdriver-zh#Here-are-the-browsers-currently-supported-by-SideeX)，並將其放置於與`selenium-server-standalone-{version}.jar`相同目錄下
3. 開啟命令列模式並且切換路徑至`selenium-server-standalone-{version}.jar`的目錄
4. 執行`java -jar selenium-server-standalone-{version}.jar`

### 步驟2：執行SideeX Runner
1. 開啟命令列模式並執行`npm i -g @sideex/runner`
2. 執行`sideex-runner --config {CONFIG_FILE_PATH}`。如下範例，當執行以下設定檔時，所有指定的測試套件中之測試案例都將會透過WebDriver於Chrome上播放。設定檔格式請參閱[附錄 A](##-附錄-A---SideeX-Runner設定檔格式)。

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

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

### 步驟3：觀看、推送與解析測試報告
- **觀看測試報告**：測試報告檔案將會於[設定檔](##-附錄-A---SideeX-Runner設定檔格式)中指定的目錄下被產生，格式可為HTML或JSON，HTML檔案可以瀏覽器開啟觀看，JSON檔案可被其他程式解析與再處理。
- **推送測試報告**：測試報告可自動推送至Email、Slack與Line，可參閱[設定檔格式](##-附錄-A---SideeX-Runner設定檔格式)。
- **輸出資料**：測試報告中將包含測試案例中區域變數與全域變數最後執行的值，有時候這些資料有助於除錯並且可供其他程式解析與再處理，請參閱[測試報告格式](https://hackmd.io/@sideex/book-zh/%2F%40sideex%2Freportspec)。

## 附錄 A - SideeX Runner設定檔格式
*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
注意：上述config檔中的**webdriver**與**play**屬性可由SideeX Record的設定頁面匯出後轉貼。WebDriver設定請參閱[透過WebDriver進行跨瀏覽器測試](https://hackmd.io/@sideex/webdriver-zh)
:::

格式說明：
- **input**
- **testSuites**
- Description: 測試套件檔案路徑
- Value: A string array
- Default: `[]`
- **variables**
- Description: 變數檔案路徑，檔案格式須為`json`或`csv`
- Value: A string array
- Default: `[]`
- **play**
- **mode**
- Description: 播放模式
- Value: `0`, `1`, or `2`。`0`為播放此測試案例，`1`為播放此測試套件，`2`為播放所有測試套件
- Default: `2`
- **entry**
- Description: 指定欲播放的測試案例或套件
- 若`mode`=`0`，此屬性須設定為一個測試案例的全名，例如`testsuite1.testcase1`
- 若`mode`=`1`，此屬性須設定為一個測試套件的全名，例如`testsuite2`
- 若`mode`=`2`，此屬性可免設定並將會被忽略
- Value: A string
- Default: `""`
- **noLog**
- Description:
- 此屬性設定為`true`代表關閉Log
- Value: boolean
- Default: `false`
- **speed**
- Description: 播放速度。`1`為最慢速，`5`為最快速
- Value: `1`, `2`, `3`, `4`, or `5`.
- Default: `5`
- **autoWaitTimeout**
- Description: 執行下個指令前的自動等待時間上限。
- Value: A number (單位: 秒)
- Default: `30`
- **period**
- **time**
- Description: 週期性播放模式之週期。`-1`代表關閉週期性播放
- Value: A number (單位：秒)
- Default: `-1`
- **maxNum**
- Description: 最多播放次數。設定為`-1`代表無限次播放
- Value: A number
- Default: `-1`
- **report**
- **type**
- Description: 測案報告檔案格式
- Value: `"html"`, `"json"` 或 `"all"`
- Default: `"html"`
- **path**
- Description: 測試報告儲存路徑。如果此路徑不存在，在執行時將會自動產生
- Value: A string
- Default: `""`
- **snapshot**
- Description: 設定是否播放每個指令時擷取網頁快照
- `0` : 不擷圖
- `1` : 指令失敗時才擷圖
- `2` : 不論執行狀態一律擷圖
- Value: `0`, `1`, or `2`
- Default: `2`
- **snapshotQuality**
- Description: 網頁快照品質，其值由1至100，100為最高畫面品質。注意：品質設定越高，測試報告檔案大小越大
- Value: `1` to `100`.
- Default: `20`

- **webdriver**
- **configs**
- **serverUrl**
- Description: WebDriver伺服器URL (Selenium Server或Appium Server)
- Value: A URL string
- Default: `""`
- **type**
- Description: WebDriver伺服器型態
- Value: `"selenium"`或`"appium"`
- Default: `"selenium"`
- **browsers**
- Description: 瀏覽器清單(Browser Capabilities)
- Value: An array
- Default: `[]`
- **active**
- Description: 啟用或停用此劉覽器
- Value: boolean
- Default: `true`
- **capability**
- **browserName**
- Description: 瀏覽器名稱
- Value:
- For desktop browsers: `"chrome"`, `"firefox"`, `"MicrosoftEdge"`, `"safari"` or `"opera"`.
- For mobile browsers: 請參閱[這裡](https://hackmd.io/@sideex/webdriver-zh#%E8%A1%8C%E5%8B%95%E7%80%8F%E8%A6%BD%E5%99%A8)
- **platformName**
- Description: The platform
- Value:
- 針對桌面瀏覽器: `"WINDOWS"`, `"LINUX"`, or `"MAC"`
- 針對行動裝置瀏覽器: 請參閱[這裡](https://hackmd.io/@sideex/webdriver-zh#%E8%A1%8C%E5%8B%95%E7%80%8F%E8%A6%BD%E5%99%A8)
- **browserVersion**
- Description: 瀏覽器版本
- Value: A string
- **(更多capability設定)**
可自行加入更多符合W3C WebDriver Capability規範的capability設定。例如，可加入啟動瀏覽器無頭(Headless)模式的設定：

                     // 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:
            - 各國語言代碼與語言檔路徑。所有的語言代碼可參考SideeX Recorder的設定頁面。更多說明請參閱[多國語言測試](/@sideex/book-zh/%2F%40sideex%2Fi18n-zh)
        - Value: 語言代碼與語言檔清單，播放時將依清單上語言順序執行

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

        - Default: `undefined`
- **mail**
將測試報告以Email寄出。注意：若使用Gmail SMTP伺服器寄信時，須事先建立[Application Password](https://support.google.com/mail/answer/185833?hl=zh-Hant)
    - **active**
        - Description
            - `0` : 不寄送信件
            - `1` : 當測試失敗時才寄送信件
            - `2` : 不論測試結果一律寄送信件
        - Value: `0`, `1` or `2`
        - Default: `0`
    - **configs**
        - **transport**
            - Description: Mail伺服器設定。可參考[SMTP Transport](https://nodemailer.com/smtp/)
            - Value: 如以下格式

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

            - Default: `undefined`
        - **mailer**
            - Description: 信件設定。可參考[Message](https://nodemailer.com/message/)
            - Value: 如以下格式

{
"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**
推送測試報告至Slack。事先須準備[Slack Token與Channel](/@sideex/slack-zh)
    - **active**
        - Description
            - `0` : 不推送至Slack
            - `1` : 當測試失敗時才推送至Slack
            - `2` : 不論測試結果一律推送至Slack
        - Value: `0`, `1` or `2`
        - Default: `0`
    - **configs**
        - **token**
            - Description: Slack APP之Token
            - Value: A string
            - Default: `""`
        - **channel**
            - Description: Slack Workspace Channels
            - Value: A string
            - Default: `""`
        - **text**
            - Description: 推送文字訊息。將顯示於Test Report Summary前
            - Value: A string
            - Default: `""`

- **line**
推送測試報告至Line。事先須準備[Line Notify Token](https://hackmd.io/@sideex/line-notify-zh)
    - **active**
        - Description
            - `0` : 不推送至Line
            - `1` : 當測試失敗時才推送至Line
            - `2` : 不論測試結果一律推送至Line
        - Value: `0`, `1` or `2`
        - Default: `2`
    - **configs**
        - **token**
            - Description: Line Notify Token
            - Value: A string
            - Default: `""`
        - **text**
            - Description: 推送文字訊息。將顯示於Test Report Summary前
            - Value: A string
            - Default: `""`