com.saucelabs.saucerest

Class SauceREST

java.lang.Object

com.saucelabs.saucerest.SauceREST

All Implemented Interfaces:

Serializable

public class SauceREST
extends Object
implements Serializable

Simple Java API that invokes the Sauce REST API. The full list of the Sauce REST API functionality is available from https://docs.saucelabs.com/reference/rest-api.

Author:

Ross Rowe

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected String	accessKey The access key to use when performing HTTP requests to the Sauce REST API.
protected String	username The username to use when performing HTTP requests to the Sauce REST API.

Constructor Summary

Constructors

Constructor and Description
SauceREST(String username, String accessKey) Constructs a new instance of the SauceREST class.

Method Summary

Modifier and Type	Method and Description
protected void	addAuthenticationProperty(HttpURLConnection connection) Adds an Authorization request property to the HTTP connection.
protected URL	buildURL(String endpoint) Build the url to be
void	deleteJob(String jobId) Invokes the Sauce REST API to delete a completed job from Sauce.
void	deleteTunnel(String tunnelId) Invokes the Sauce REST API to delete a tunnel.
String	doJSONPOST(URL url, org.json.JSONObject body)
void	downloadLog(String jobId, String location) Downloads the log file for a Sauce Job to the filesystem.
void	downloadVideo(String jobId, String location) Downloads the video for a Sauce Job to the filesystem.
protected String	encodeAuthentication()
boolean	equals(Object obj)
String	getActivity() Invokes the Sauce REST API to retrieve the activity details of the user.
String	getBuildFullJobs(String build)
String	getBuildFullJobs(String build, int limit) Retrieve jobs associated with a build
String	getConcurrency() Invokes the Sauce REST API to retrieve the concurrency details of the user.
static String	getExtraUserAgent()
String	getFullJobs() Returns a String (in JSON format) representing the details for a Sauce job.
String	getFullJobs(int limit) Returns a String (in JSON format) representing the details for a Sauce job.
String	getJobInfo(String jobId) Returns a String (in JSON format) representing the details for a Sauce job.
String	getJobs() Returns a String (in JSON format) representing the details for a Sauce job.
String	getJobs(int limit) Returns a String (in JSON format) representing the details for a Sauce job.
String	getJobs(int limit, long to, int from) Returns a String (in JSON format) representing the details for a Sauce job.
String	getPublicJobLink(String jobId) Generates a link to the job page on Saucelabs.com, which can be accessed without the user's credentials.
String	getStoredFiles() Returns a String (in JSON format) representing the stored files list
String	getSupportedPlatforms(String automationApi) Returns a String (in JSON format) representing the list of objects describing all the OS and browser platforms currently supported on Sauce Labs.
String	getTunnelInformation(String tunnelId) Invokes the Sauce REST API to retrieve the details of the tunnel.
String	getTunnels() Invokes the Sauce REST API to retrieve the details of the tunnels currently associated with the user.
String	getUser() Returns a String (in JSON format) representing the basic account information
protected String	getUserAgent()
String	getUsername() Returns username assigned to this interface
void	jobFailed(String jobId) Marks a Sauce Job as 'failed'.
void	jobPassed(String jobId) Marks a Sauce Job as 'passed'.
HttpURLConnection	openConnection(URL url) Opens a connection to a url.
boolean	recordCI(String platform, String platformVersion) Record CI Usage to Sauce Labs
String	retrieveResults(String path) Returns the HTTP response for invoking https://saucelabs.com/rest/v1/path.
String	retrieveResults(URL restEndpoint)
static void	setExtraUserAgent(String extraUserAgent)
void	stopJob(String jobId) Invokes the Sauce REST API to stop a running job.
void	updateJobInfo(String jobId, Map<String,Object> updates) Invokes the Sauce REST API to update the details of a Sauce job, using the details included in the updates parameter.
String	uploadFile(File file) Uploads a file to Sauce storage.
String	uploadFile(File file, String fileName) Uploads a file to Sauce storage.
String	uploadFile(File file, String fileName, Boolean overwrite) Uploads a file to Sauce storage.
String	uploadFile(InputStream is, String fileName, Boolean overwrite) Uploads a file to Sauce storage.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

username

protected String username

The username to use when performing HTTP requests to the Sauce REST API.

accessKey

protected String accessKey

The access key to use when performing HTTP requests to the Sauce REST API.

Constructor Detail

SauceREST

public SauceREST(String username,
                 String accessKey)

Constructs a new instance of the SauceREST class.

Parameters:

username - The username to use when performing HTTP requests to the Sauce REST API

accessKey - The access key to use when performing HTTP requests to the Sauce REST API

Method Detail

getExtraUserAgent

public static String getExtraUserAgent()

setExtraUserAgent

public static void setExtraUserAgent(String extraUserAgent)

getUsername

public String getUsername()

Returns username assigned to this interface

Returns:

Returns username assigned to this interface

buildURL

protected URL buildURL(String endpoint)

Build the url to be

Parameters:

endpoint - Endpoint url, example "info/platforms/appium"

Returns:

URL to use in direct fetch functions

getUserAgent

protected String getUserAgent()

doJSONPOST

public String doJSONPOST(URL url,
                         org.json.JSONObject body)
                  throws SauceException

Throws:

SauceException

jobPassed

public void jobPassed(String jobId)

Marks a Sauce Job as 'passed'.

Parameters:

jobId - the Sauce Job Id, typically equal to the Selenium/WebDriver sessionId

jobFailed

public void jobFailed(String jobId)

Marks a Sauce Job as 'failed'.

Parameters:

jobId - the Sauce Job Id, typically equal to the Selenium/WebDriver sessionId

downloadVideo

public void downloadVideo(String jobId,
                          String location)

Downloads the video for a Sauce Job to the filesystem. The file will be stored in a directory specified by the location field.

Parameters:

jobId - the Sauce Job Id, typically equal to the Selenium/WebDriver sessionId

location - represents the base directory where the video should be downloaded to

downloadLog

public void downloadLog(String jobId,
                        String location)

Downloads the log file for a Sauce Job to the filesystem. The file will be stored in a directory specified by the location field.

Parameters:

jobId - the Sauce Job Id, typically equal to the Selenium/WebDriver sessionId

location - represents the base directory where the video should be downloaded to

retrieveResults

public String retrieveResults(String path)

Returns the HTTP response for invoking https://saucelabs.com/rest/v1/path.

Parameters:

path - path to append to the url

Returns:

HTTP response contents

getJobInfo

public String getJobInfo(String jobId)

Returns a String (in JSON format) representing the details for a Sauce job.

Parameters:

jobId - the Sauce Job id to retrieve

Returns:

String (in JSON format) representing the details for a Sauce job

getFullJobs

public String getFullJobs()

Returns a String (in JSON format) representing the details for a Sauce job.

Returns:

String (in JSON format) representing the details for a Sauce job

getFullJobs

public String getFullJobs(int limit)

Returns a String (in JSON format) representing the details for a Sauce job.

Parameters:

limit - Number of jobs to return

Returns:

String (in JSON format) representing the details for a Sauce job

getJobs

public String getJobs()

Returns a String (in JSON format) representing the details for a Sauce job.

Returns:

String (in JSON format) representing the jobID for a sauce Job

getJobs

public String getJobs(int limit)

Returns a String (in JSON format) representing the details for a Sauce job.

Parameters:

limit - Number of jobs to return(max of 500)

Returns:

String (in JSON format) representing the jobID for a sauce Job

getJobs

public String getJobs(int limit,
                      long to,
                      int from)

Returns a String (in JSON format) representing the details for a Sauce job.

Parameters:

limit - Number of jobs to return(max of 500)

to - value in Epoch time format denoting the time to end the job list searh

from - value in Epoch time format denoting the time to start the search

Returns:

String (in JSON format) representing the jobID for a sauce Job

retrieveResults

public String retrieveResults(URL restEndpoint)

Parameters:

restEndpoint - the URL to perform a HTTP GET

Returns:

Returns the response from invoking a HTTP GET for the restEndpoint

addAuthenticationProperty

protected void addAuthenticationProperty(HttpURLConnection connection)

Adds an Authorization request property to the HTTP connection.

Parameters:

connection - HttpURLConnection instance which represents the current HTTP request

updateJobInfo

public void updateJobInfo(String jobId,
                          Map<String,Object> updates)

Invokes the Sauce REST API to update the details of a Sauce job, using the details included in the updates parameter.

Parameters:

jobId - the Sauce job id to update

updates - Map of attributes to update

stopJob

public void stopJob(String jobId)

Invokes the Sauce REST API to stop a running job.

Parameters:

jobId - the Sauce Job id

deleteJob

public void deleteJob(String jobId)

Invokes the Sauce REST API to delete a completed job from Sauce.

Parameters:

jobId - the Sauce Job id

openConnection

public HttpURLConnection openConnection(URL url)
                                 throws IOException

Opens a connection to a url.

Parameters:

url - URL to connect to

Returns:

HttpURLConnection instance representing the URL connection

Throws:

IOException - when a bad url is provided

uploadFile

public String uploadFile(File file)
                  throws IOException

Uploads a file to Sauce storage.

Parameters:

file - the file to upload -param fileName uses file.getName() to store in sauce -param overwrite set to true

Returns:

the md5 hash returned by sauce of the file

Throws:

IOException - can be thrown when server returns an error (tcp or http status not in the 200 range)

uploadFile

public String uploadFile(File file,
                         String fileName)
                  throws IOException

Uploads a file to Sauce storage.

Parameters:

file - the file to upload

fileName - name of the file in sauce storage -param overwrite set to true

Returns:

the md5 hash returned by sauce of the file

Throws:

IOException - can be thrown when server returns an error (tcp or http status not in the 200 range)

uploadFile

public String uploadFile(File file,
                         String fileName,
                         Boolean overwrite)
                  throws IOException

Uploads a file to Sauce storage.

Parameters:

file - the file to upload

fileName - name of the file in sauce storage

overwrite - boolean flag to overwrite file in sauce storage if it exists

Returns:

the md5 hash returned by sauce of the file

Throws:

IOException - can be thrown when server returns an error (tcp or http status not in the 200 range)

uploadFile

public String uploadFile(InputStream is,
                         String fileName,
                         Boolean overwrite)
                  throws IOException

Uploads a file to Sauce storage.

Parameters:

is - Input stream of the file to be uploaded

fileName - name of the file in sauce storage

overwrite - boolean flag to overwrite file in sauce storage if it exists

Returns:

the md5 hash returned by sauce of the file

Throws:

IOException - can be thrown when server returns an error (tcp or http status not in the 200 range)

getPublicJobLink

public String getPublicJobLink(String jobId)

Generates a link to the job page on Saucelabs.com, which can be accessed without the user's credentials. Auth token is HMAC/MD5 of the job ID with the key <username>:<api key> (see http://saucelabs.com/docs/integration#public-job-links).

Parameters:

jobId - the Sauce Job Id, typically equal to the Selenium/WebDriver sessionId

Returns:

link to the job page with authorization token

encodeAuthentication

protected String encodeAuthentication()

Returns:

base64 encoded String representing the username/access key

deleteTunnel

public void deleteTunnel(String tunnelId)

Invokes the Sauce REST API to delete a tunnel.

Parameters:

tunnelId - Identifier of the tunnel to delete

getTunnels

public String getTunnels()

Invokes the Sauce REST API to retrieve the details of the tunnels currently associated with the user.

Returns:

String (in JSON format) representing the tunnel information

getTunnelInformation

public String getTunnelInformation(String tunnelId)

Invokes the Sauce REST API to retrieve the details of the tunnel.

Parameters:

tunnelId - the Sauce Tunnel id

Returns:

String (in JSON format) representing the tunnel information

getConcurrency

public String getConcurrency()

Invokes the Sauce REST API to retrieve the concurrency details of the user.

Returns:

String (in JSON format) representing the concurrency information

getActivity

public String getActivity()

Invokes the Sauce REST API to retrieve the activity details of the user.

Returns:

String (in JSON format) representing the activity information

getStoredFiles

public String getStoredFiles()

Returns a String (in JSON format) representing the stored files list

Returns:

String (in JSON format) representing the stored files list

getUser

public String getUser()

Returns a String (in JSON format) representing the basic account information

Returns:

String (in JSON format) representing the basic account information

getSupportedPlatforms

public String getSupportedPlatforms(String automationApi)

Returns a String (in JSON format) representing the list of objects describing all the OS and browser platforms currently supported on Sauce Labs. (see https://docs.saucelabs.com/reference/rest-api/#get-supported-platforms).

Parameters:

automationApi - the automation API name

Returns:

String (in JSON format) representing the supported platforms information

getBuildFullJobs

public String getBuildFullJobs(String build,
                               int limit)

Retrieve jobs associated with a build

Parameters:

build - Build Id

limit - Max jobs to return

Returns:

String (in JSON format) representing jobs associated with a build

getBuildFullJobs

public String getBuildFullJobs(String build)

recordCI

public boolean recordCI(String platform,
                        String platformVersion)

Record CI Usage to Sauce Labs

Parameters:

platform - Platform string. Such as "jenkins", "bamboo", "teamcity"

platformVersion - Version string. Such as "1.1.1"

Returns:

if it was a success or not

equals

public boolean equals(Object obj)

Overrides:

equals in class Object