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
2. SideeX WebService Client API for Java | Python | Node.js
3. SideeX WebService Web API

The architecture of SideeX WebService

Step 1 - Start Selenium Standalone Server

1. Download Selenium Standalone Server (Tested version: 3.141.59)
2. Download the the drivers 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 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
    }
}

Note that, SideeX WebService and Selenium server/nodes can be run in Docker containers. See Appendix C.

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) 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
2. Using SideeX WebService Client API for Java | Python | Node.js
3. Using SideeX WebService 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
        • Value: A string
        • Default: ""
      • certificate
        • Description: Set certificate file path. See How to Generate Private Key and Certificate Using OpenSSL
        • 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

    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 first.

  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 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 to generate an app password for mail.
      • Default: undefined
    • mailer
      • Description: Refer to the 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 at first.

  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 at first.

  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, 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

Step 2 - Download and Run SideeX WebService Docker image

1. Create a serviceconfig.json file as Appendix A
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.
3. 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>