---
title: SideeX WebService
tags: Chinese
---
# SideeX WebService
[SideeX WebService](https://www.npmjs.com/package/@sideex/webservice)工具提供一個網際服務介面接收與執行SideeX Recorder錄製出之測試案例，可用於公司內部自行建立測試平台，提供測試服務。本文將介紹如何啟動SideeX WebService。啟動後，將可透過以下三種方式來呼叫其網際服務：
1. [SideeX Plugin for Jenkins](https://hackmd.io/@sideex/webservice-jenkins-plugin-zh)
2. SideeX WebService Client API for [Java](https://hackmd.io/@sideex/webservice-client-java-api) | [Python](https://hackmd.io/@sideex/webservice-client-python-api) | [Node.js](https://hackmd.io/@sideex/webservice-client-nodejs-api)
3. [SideeX WebService Web API](https://hackmd.io/@sideex/webservice-web-api)
SideeX WebService架構圖
## 步驟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 WebService
1. 開啟命令列模式並執行`npm i -g @sideex/webservice`
2. 執行`sideex-webservice --config {CONFIG_FILE_PATH}`。設定檔格式請參閱[附錄A](#附錄A---SideeX-WebService-Config-File-Format)。底下為一個簡單的設定檔範例(`serviceconfig.json`)：
```json=
{
"webservice": {
"server": {
"port": 50000
},
"publicURL": {
"hostname": "127.0.0.1",
"port": 50000
},
"projectFolderPath": "test-project",
"testProjectExpireTime": 24
}
}
```
:::info
提示：SideeX WebServer與Selenium Server/Node可於[Docker上運行](#附錄C---於Docker上運行SideeX-WebService與Selenium-Server)
:::
## 步驟3 (可跳過) - 使用Postman檢查SideeX WebService是否啟動
在Postman中開啟新的分頁，選擇`GET` method，輸入`http://<webservice-publicURL-hostname>:<port>/sideex-webservice/echo`，點選`Send`.
## 步驟4：準備測試案例檔案
準備測試案例檔案並將其打包成一個zip檔，此zip檔須包含一個`config.json`(請參閱[附錄B](#附錄B---SideeX-WebService-Client-Config-File-Format))與一個`suites`目錄，而`variables`目錄與`i18n`目錄為選擇性項目，此zip檔內結構如下
```=
testcase.zip
│ config.json
├───suites
│ Test_Suite_1.html
│ ...
├───variables
│ Global_Variables.json
│ ...
├───i18n
ja.json
zh_TW.json
...
```
## 步驟5 (可跳過) - 使用Postman檢查SideeX WebService是否能正常執行測試案例
1. 在Postman中開啟新的分頁，選擇`POST` method，輸入`http://<webservice-publicURL-hostname>:<port>/sideex-webservice/runTestSuites`.
2. 選擇`Body` -> `form-data`，在`Key`欄位輸入`file`，在`Value`欄位點選`Choose Files`加入`testcase.zip`，點選`Send`.
## 步驟6：呼叫SideeX WebService以執行測試案例
可透過底下三種方式來呼叫SideeX WebService以執行步驟3準備之zip檔：
1. [SideeX Plugin for Jenkins](https://hackmd.io/@sideex/webservice-jenkins-plugin-zh)
2. SideeX WebService Client API for [Java](https://hackmd.io/@sideex/webservice-client-java-api) | [Python](https://hackmd.io/@sideex/webservice-client-python-api) | [Node.js](https://hackmd.io/@sideex/webservice-client-nodejs-api)
3. [SideeX WebService Web API](https://hackmd.io/@sideex/webservice-web-api)
# 附錄A - SideeX WebService Config File Format
此附錄將說明SideeX WebService Server設定檔格式(`serviceconfig.json`)。
```json=
{
"webservice": {
"server": {
"port": 50000,
"ssl": {
"active": true,
"privateKey": "your_private_key",
"certificate": "your_certificate"
}
},
"publicURL": {
"hostname": "127.0.0.1",
"port": 50000
},
"testJobsFolderPath": "test-jobs",
"testJobExpireTime": 24
},
"mail": {
"active":2,
"configs": {
"transport": {
"host": "smtp.gmail.com",
"port": 465,
"secure": true,
"auth": {
"user": "your_email@gmail.com",
"pass": "your_app_password"
}
},
"mailer": {
"from": "\"SideeX WebService\" <xxxxx@gmail.com>",
"to": "xxxxx@gmail.com, xxxxx@gmail.com",
"subject": "The test reports generated by SideeX Runner",
"html": "<p> Type your email body here</p>"
}
}
},
"slack": {
"active": 2,
"configs": {
"token": "your_slack_token",
"channel": "your_channel",
"text": "Here comes the test reports generated by SideeX WebService"
}
},
"line": {
"active": 2,
"configs": {
"token": "your_line_notify_token",
"text": "Here comes the test reports generated by SideeX WebService"
}
}
}
```
Description
* **webservice**
* server
* port
* Description: 設定Server Port
* Value: A number
* Default: `50000`
* ssl
* active
* Description: 設定是否啟用SSL連線
* Value: boolean
* Default: `false`
* privateKey
* Description: 設定Private Key檔案路徑。可參閱[如何利用OpenSSL建立Private Key和Certificate](https://hackmd.io/@sideex/ssl-zh)
* Value: A string
* Default: `""`
* certificate
* Description: 設定Certificate檔案路徑。可參閱[如何利用OpenSSL建立Private Key和Certificate](https://hackmd.io/@sideex/ssl-zh)
* Value: A string
* Default: `""`
* publicURL
* hostname
* Description:
* SideeX WebService Server的IP位址
* 若SideeX WebService Server運行於一個Docker Container中，此屬性須設定為Host的IP位址
* Value: A string
* Default: `"127.0.0.1"`
* port
* Description:
* SideeX WebService Server的Port值
* 若SideeX WebService Server運行於一個Docker Container中，此屬性須設定為對應到此Container於Host上的Port
* Value: A number
* Default: `50000`
* testJobsFolderPath
* Description:
- 一個目錄名稱，用以存放測試執行期間產生之暫存檔案
- Value: A string
- Default: `"test-project"`
* testProjectExpireTime
:::info
此屬性可被測試案例zip檔中之`config.json`覆寫
:::
* Description:
- 暫存檔案之到期清除時間
- `0` : 永不清除
- `n` : 每次收到測試案例zip檔案並執行測試，於`n`小時後將清除暫存檔案
- Value: A positive integer (單位：小時)
- Default: `0`
- **mail**
將測試報告以Email寄出。注意：若使用Gmail SMTP伺服器寄信時，須事先建立[Application Password](https://support.google.com/mail/answer/185833?hl=zh-Hant)
:::info
以下屬性可被測試案例zip檔中之`config.json`覆寫
:::
- **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": "xxxx@gmail.com",
"pass": "your_password"
}
}
```
`user` 的欄位請填入您的 gmail 帳號，`pass` 的欄位請根據[這篇](https://support.google.com/accounts/answer/185833)文章產生出一組給郵件的應用程式密碼。
- Default: `undefined`
- **mailer**
- Description: 信件設定。可參考[Message](https://nodemailer.com/message/)
- Value: 如以下格式
```
{
"from": "\"your_title\" <xxxx@gmail.com>",
"to": "xxxx1@gmail.com, xxxx2@gmail.com",
"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)
:::info
以下屬性可被測試案例zip檔中之`config.json`覆寫
:::
- **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)
:::info
以下屬性可被測試案例zip檔中之`config.json`覆寫
:::
- **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: `""`
# 附錄B - SideeX WebService Client Config File Format
此附錄將說明測試案例zip檔中之設定檔格式(`config.json`)。此設定檔格式內容除了以下屬性有差異外，其餘屬性與[SideeX Runner設定檔格式](https://hackmd.io/@sideex/runner-zh)相同：
* `input`、`report.path`、`webdriver.i18n`屬性無作用
* 多了一項屬性：`testProjectExpireTime`。此屬性若有設定值，則將覆蓋SideeX WebService Server設定檔之同名屬性。
格式如下：
```json=
{
"play": {
"mode": 2,
"entry": "",
"noLog": false,
"speed": 5,
"autoWaitTimeout":30,
"period": {
"time": -1,
"maxNum": -1
}
},
"report": {
"type":"html",
"snapshot": 2,
"snapshotQuality": 2
},
"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"
]
}
}
}
]
}
]
},
"webservice": {
"testJobExpireTime": 24
},
"mail": {
"active": 2,
"configs": {
"mailer": {
"from": "\"your_title\" <xxxx@gmail.com>",
"to": "xxxx1@gmail.com, xxxx2@gmail.com",
"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 WebService"
}
}
}
```
# 附錄C - 於Docker上運行SideeX WebService與Selenium Server
此附錄將介紹如何於同一台電腦上運行SideeX WebService container與Selenium Server/Hub containers。
## 步驟1：下載與運行Selenium Hub/Node Docker影像檔
在一台主機(底下簡稱Host)上開啟命令列並執行下列指令：
```=
$ docker run -d -p 4444:4444 --name selenium-hub selenium/hub
$ docker run -d -P -p 5900:5900 --link selenium-hub:hub -v /dev/shm:/dev/shm selenium/node-chrome-debug
$ docker run -d -P -p 5901:5900 --link selenium-hub:hub -v /dev/shm:/dev/shm selenium/node-firefox-debug
```
> 更多資訊請參閱[Docker images for the Selenium Grid Server](https://github.com/SeleniumHQ/docker-selenium)
## 步驟2：下載與運行SideeX WebService Docker影像檔
1. 建立一個`serviceconfig.json`檔案(請參閱[附錄A](#附錄A---SideeX-WebService-Config-File-Format))
2. 建立一個`test-jobs`目錄。此目錄將與SideeX WebService container共用，用以暫存執行測試時所產生的檔案
3. 執行以下指令以下載與執行SideeX WebService Docker影像檔
```=
$ docker run -d -P -p 50000:50000 \
--link selenium-hub:hub \
-v $(pwd)/serviceconfig.json:/opt/sideex-webservice/serviceconfig.json \
-v $(pwd)/test-jobs:/opt/sideex-webservice/test-jobs \
sideex/webservice
```
4. 在使用端測試案例zip檔中的設定檔內容，將`webdriver.configs.serverUrl`屬性設定如下：
```json=
{
"webdriver": {
"configs": [
{
"serverUrl": "http://{Host主機的IP}:{對應到Selenium hub container於Host主機上的Port} 或 http://<selenium-hub-container-name>:{對應到Selenium hub container於Host主機上的Port}",
"type": "selenium",
"browsers":[
{
"active": true,
"capability": {
"browserName": "chrome"
}
}
]
}
]
}
}
```
## 步驟3：監看SideeX WebService Container
執行以下指令以監看SideeX WebService執行時之Log：
```=
$ docker logs -f <SideeX-WebService-container-name>
```
Sign in with Wallet
Connect another wallet