---
tags: English
---
# SideeX WebService

SideeX WebService is a tool that provides a Web service interface for playing SideeX-recorded test cases. This tool can be hosted as a testing server in a company under a private network to provide testing services. There are three ways to invoke a hosted SideeX WebService server:
1. [SideeX Plugin for Jenkins](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-jenkins-plugin)
2. SideeX WebService Client API for [Java](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-java-api) | [Python](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-python-api) | [Node.js](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-nodejs-api)
3. [SideeX WebService Web API](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-web-api)

<!--  -->

The architecture of SideeX WebService

## Step 1 - Start Selenium Standalone Server
1. Download [Selenium Standalone Server](https://www.seleniumhq.org/download/) (Tested version: 3.141.59)
2. Download the the [drivers](/@sideex/webdriver#Here-are-the-browsers-currently-supported-by-SideeX) that you'd like to test
3. Open the terminal and switch to the path where you save the `selenium-server-standalone-{version}.jar` and the drivers
4. Run `java -jar selenium-server-standalone-{version}.jar`

## Step 2 - Start SideeX WebService
1. Run `npm i -g @sideex/webservice`
2. Run `sideex-webservice --config {CONFIG_FILE_PATH}`. See [Appendix A](#Appendix-A---SideeX-WebService-Config-File-Format) for the config file format. The following code shows a simple WebService config file example (`serviceconfig.json`):

{
    "webservice": {
        "server": {
            "port": 50000
        },
        "publicURL": {
            "hostname": "127.0.0.1",
            "port": 50000
        },
        "testJobsFolderPath": "test-jobs",
        "testJobExpireTime": 24
    }
}

:::info
Note that, SideeX WebService and Selenium server/nodes can be run in Docker containers. See [Appendix C](#Appendix-C---Running-SideeX-WebService-and-Selenium-Server-on-Docker).
:::

## Step 3 (Optional) - Use Postman to quickly check if SideeX WebService is started
In Postman, open a new tab and then select `GET` method. Input `http://<webservice-publicURL-hostname>:<port>/sideex-webservice/echo`. Then click on `Send`.

## Step 4 - Prepare a test case zip file
Prepare a zip file containing test case information. A zip file should at least contain a `config.json` (see [Appendix B](#Appendix-B---SideeX-WebService-Client-Config-File-Format)) and a `suites` folder. A `variables` folder and an `i18n` folder are optional.

testcase.zip
│   config.json
├───suites
│       Test_Suite_1.html
│       ...
├───variables
│       Global_Variables.json
│       ...
├───i18n
        ja.json
        zh_TW.json
        ...

## Step 5 (Optional) - Use Postman to quicky check if SideeX WebService can execute test cases successfully
1. In Postman, open a new tab and select `POST` method. Input `http://<webservice-publicURL-hostname>:<port>/sideex-webservice/runTestSuites`.
2. Select `Body` -> `form-data`. Type `file` in the `Key` field. In the `Value` filed, click on `Choose Files` to add `testcase.zip`. Click on `Send`.

## Step 6 - Invoke SideeX WebService to run the zip file
There are three ways to run the test case zip file:
1. Using [SideeX Plugin for Jenkins](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-jenkins-plugin)
2. Using SideeX WebService Client API for [Java](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-java-api) | [Python](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-python-api) | [Node.js](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-client-nodejs-api)
3. Using [SideeX WebService Web API](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice-web-api)

# Appendix A - SideeX WebService Config File Format

An example WebService config file: *serviceconfig.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": "[e-mail]",
                    "pass": "your_app_password" 
                }
            },
            "mailer": {
                "from": "\"SideeX WebService\" <[e-mail]>",
                "to": "[e-mail], [e-mail]",
                "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: Set server port
* Value: A number
* Default: `50000`
* ssl
* active
* Description: Set server ssl
* Value: boolean
* Default: `false`
* privateKey
* Description: Set private key file path. See [How to Generate Private Key and Certificate Using OpenSSL](https://hackmd.io/@sideex/ssl)
* Value: A string
* Default: `""`
* certificate
* Description: Set certificate file path. See [How to Generate Private Key and Certificate Using OpenSSL](https://hackmd.io/@sideex/ssl)
* Value: A string
* Default: `""`
* publicURL
* hostname
* Description:
* The IP address of the SideeX WebService server.
* If the SideeX WebService server runs as a Docker container, it should be host's IP address.
* Value: A string
* Default: `"127.0.0.1"`
* port
* Description:
* The port number of the SideeX WebService server.
* If the SideeX WebService server runs as a Docker container, it should be the host's port number mapped to the container.
* Value: A number
* Default: `50000`
* testJobsFolderPath
* Description:
- A folder for saving the temporarily generated files when running test jobs.
- Value: A string
- Default: `"test-jobs"`
* testJobExpireTime
:::info
This attribute can be overwritten by the client's *config.json*
:::
* Description:
- The expiration time for clearing the temporarily generated files of each test job.
- `0` : Never delete a test job
- `n` : Delete a test job *n* hours later after the job is generated
- Value: A positive integer (in hours)
- Default: `0`

- **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.
:::info
All or parts of the following attributes can be overwritten by the client's *config.json*
:::
- **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"
                    }
                }

The authentication `user` should be your own gmail address, the `pass` can be generate by generating an App Password, follow [this article](https://support.google.com/accounts/answer/185833) to generate an app password for mail.
- 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/book/%2F%40sideex%2Fslack) at first.
:::info
All or parts of the following attributes can be overwritten by the client's *config.json*
:::
- **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.
:::info
All or parts of the following attributes can be overwritten by the client's *config.json*
:::
- **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: `""`

# Appendix B - SideeX WebService Client Config File Format

The config file format is the same as [the one for SideeX Runner](https://hackmd.io/@sideex/book/%2F%40sideex%2Frunner#Documents), except the followings:
* `input`, `report.path`, `webdriver.i18n` will be ignored by SideeX WebService
* A new attribute `testJobExpireTime` is added. This attibute indicates the expiration time for deleting the generated test job. If the attribute is set in the client config file, it will overwrite the one in the WebService config file

An Example WebService Client Config File: *config.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\" <[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 WebService"
        }
    }
}

# Appendix C - Running SideeX WebService and Selenium Server on Docker
The following example shows how to run SideeX WebService container and Selenium Standalone Server/Hub containers on the same host.
## Step 1 - Download and Run Docker images of Selenium Standalone Server Hub and Node

Download and run Selenium Hub and Node

$ 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

> More information about the Selenium Docker can be found at [Docker images for the Selenium Grid Server](https://github.com/SeleniumHQ/docker-selenium)
## Step 2 - Download and Run SideeX WebService Docker image
1. Create a `serviceconfig.json` file as [Appendix A](#Appendix-A---SideeX-WebService-Config-File-Format)
2. Create a `test-jobs` folder. This folder will be shared with the SideeX WebService container for temporarily saving the test cases and reports while test execution.
4. Download and run SideeX WebService Docker image

    $ 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. In the client config file, set the `webdriver.configs.serverUrl` as follows.

    {
        "webdriver": {
            "configs": [
                {
                    "serverUrl": "http://{The IP of the host of the Selenium Hub container}:{The host's port mapped to the container} or http://<selenium-hub-container-name>:{The host's port mapped to the container}",
                    "type": "selenium",
                    "browsers":[
                        {
                            "active": true,
                            "capability": {
                                "browserName": "chrome"
                            }
                        }
                    ]
                }
            ]
        }
    }

## Step 3 - Monitoring the SideeX WebService Container

$ docker logs -f <SideeX-WebService-container-name>