---
tags: English
---
# SideeX WebService Client API for Java
SideeX WebService Client API primarily handles the transfer of test suites to a hosted [SideeX WebService](https://hackmd.io/@sideex/book/%2F%40sideex%2Fwebservice) server and returns the test reports.

# Download
Download the [SideeX WebService Client API for Java](https://search.maven.org/artifact/com.github.SideeX/sideex-webservice-client)

# The API for Java

### `ProtocolType`
- `Description`: ProtocolType is a Enum Class type which specifies the http protocol. `HTTP` stands for http request; `HTTPS_DISABLE` stands for https request without certificate; `HTTPS_ENABLE` stands for https request with certificate.

### `SideeXWebServiceClientAPI(String baseURL, ProtocolType protocolType)`
- `Description`: The constructor to create a Client API object.
- `baseURL`: Base URL of the SideeX WebService server.
- `protocolType`: The type of http request used. The value can be set to `ProtocolType.HTTP` or `ProtocolType.HTTPS_DISABLE`.

### `SideeXWebServiceClientAPI(String baseURL, ProtocolType protocolType, String caFilePath)`
- `Description`: The constructor to create a Client API object.
- `baseURL`: Base URL of the SideeX WebService server.
- `protocolType`: The type of http request used. The value is set to `ProtocolType.HTTPS_ENABLE`.
- `caFilePath`: The file path of the http certificate.

### `runTestSuite(Map<String, File> file)`
- `Description`: Uses the API to run test cases.
- `file`: The file that contains test cases.
- Return:

    {
        "token": "xxxx"
    }

### `getState(String token)`
- `Description`: Gets the current test case execution state.
- `token`: The token returned from the *runTestSuite* API.
- If the token is invalid, the response will be

        { 
            "ok": false, 
            "errorMessage": "invalid_token" 
        }

- If the token is `valid` and the state is `running`, the response will be

        {
            "ok": true, 
            "webserviceState": {
                "state": "running"
            }
        }

- If the token is `valid` and the state is `complete`, the response will be

        {
            "ok": true,
            "webserviceState": {
                "state": "complete"
            },
            "reports": {
                "url": "http://{publicURL_in_serviceconfig}/sideex-webservice/downloadReports?token=xxxx",
                "passed": true,
                "summarry": [
                    {
                        "Suites": ["Test_Suite_1"],
                        "SideeXVersion": [3,3,7],
                        "Browser": "chrome 81.0.4044.138",
                        "Platform": "windows",
                        "Language": "(default)",
                        "StartTime": 1589867469846,
                        "EndTime": 1589867472874,
                        "PassedSuite": 1,
                        "TotalSuite": 1,
                        "PassedCase": 1,
                        "TotalPassedCase": 1
                    }
                ]
            },
            "logs": {
                "url": "http://{publicURL_in_serviceconfig}/sideex-webservice/downloadLogs?token=xxxx"
            }
        }

### `download(final Map<String, String> formData, String filePath, int option)`
- `Description`: Download HTML test reports or logs.
- `fromData`: A Map object containing the following:
- `token`: The token returned from the *runTestSuite* API.
- `file`: This parameter is optional. If set `file` to `"reports.zip"`, the API will return a zip file containing all HTML reports, otherwise, it will return an HTML index webpage.
- `filePath`: Set your download file path. e.g.: "./reports".
- `option`: If option is set to `0`, the API will download reports. If set to `1`, it will download logs.

### `deleteJob(String token)`
- `Description`: Delete the test case and the test reports on SideeX WebService server.
- `token`: The token returned from the *runTestSuite* API.
- If success, the response will be

        { 
            "ok": true, "state": "delete_complete" 
        }

- If the token is invalid, the response will be

        { 
            "ok": false, "errorMessage": "invalid_token" 
        }

- If the test case is running, the response will be

        { 
            "ok": false, "errorMessage": "testcase_is_running" 
        }

# How to use

### Send a test case file to a SideeX WebService server

//Create a Client API object connecting to a SideeX WebService server
SideeXWebServiceClientAPI wsClient = new SideeXWebServiceClientAPI("http://127.0.0.1:50000", ProtocolType.HTTP);

//Prepare a test case file
File file = new File("testcase.zip");

//Send the test case file to the server and get a token 
Map<String, File> fileParams = new HashMap<String, File>();
fileParams.put(file.getName(), file);
System.out.println(wsClient.runTestSuite(fileParams));

### Get the current test execution state from the server

//Get the current state
String token = "xxxx";
System.out.println(wsClient.getState(token));

### Download the test reports and logs

//Download the test reports as an HTML index webpage
String token = "xxxx";
Map<String, String> formData = new HashMap<String, String>();
formData.put("token", token);
formData.put("file", "index.html");
wsClient.download(formData, "./index.html", 0);


//Download the test reports as a zip file
String token = "xxxx";
Map<String, String> formData = new HashMap<String, String>();
formData.put("token", token);
formData.put("file", "reports.zip");
wsClient.download(formData, "./reports.zip", 0);


//Download the logs as a zip file
String token = "xxxx";
Map<String, String> formData = new HashMap<String, String>();
formData = new HashMap<String, String>();
formData.put("token", token);
wsClient.download(formData, "./logs.zip", 1);

### Delete the test job from the server

//Delete the test job
String token = "xxxx";
Map<String, String> formData = new HashMap<String, String>();
formData = new HashMap<String, String>();
formData.put("token", token);
System.out.println(wsClient.deleteJob(token));

A complete example:

public class Main {
    public static void main(String[] args) {   
        try {
            //Connect to a SideeX WebService server
            SideeXWebServiceClientAPI wsClient  = new SideeXWebServiceClientAPI("http://127.0.0.1:50000", ProtocolType.HTTP);
            File file = new File("testcase.zip");
            Map<String, File> fileParams = new HashMap<String, File>();
            fileParams.put(file.getName(), file);

            String token = new JSONObject(wsClient.runTestSuite(fileParams)).getString("token"); // get the token
            boolean flag = false;

            //Check the execution state every 2 seconds
            while(!flag) {
                //Get the current state
                String state = new JSONObject(wsClient.getState(token)).getJSONObject("webservice").getString("state");
                if(!state.equals("complete") && !state.equals("error")) {
                    System.out.println(state);
                    Thread.sleep(2000);
                }
                //If test is error
                else if(state.equals("error")) {
                    System.out.println(state);
                    flag = true;
                }
                //If test is complete
                else {
                    System.out.println(state);
                    Map<String, String> formData = new HashMap<String, String>();
                    formData.put("token", token);
                    formData.put("file", "reports.zip");
                    //Download the test report
                    wsClient.download(formData, "./reports.zip", 0);

                    formData = new HashMap<String, String>();
                    formData.put("token", token);
                    //Download the logs
                    wsClient.download(formData, "./logs.zip", 1);
                    flag = true;

                    //Delete the test case and report from the server
                    System.out.println(wsClient.deleteJob(token));
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}