Page tree
Skip to end of metadata
Go to start of metadata

The following browsers have moved their default mode to be W3C standard:

  • Chrome - Starting from version 75 
  • Safari - Starting from version 12 
  • Edge - Starting from version 17763 

Tests written in JAVA require Selenium jar version 3.14 and above.

There are two main aspects of running Selenium-based tests in the grid. The first aspect is initiating a test session and the other is running tests in parallel on multiple devices.

Initiating a Test Session

To initiate a test session and run a Selenium-based test on the grid, certain capabilities must be specified in the Desired Capabilities object. The capabilities are:

  1. Authentication with Selenium
  2. Cloud URL - the URL of the cloud.

In addition, the Selenium test desired capabilities may include the following capabilities:

    • testName - Specifies the test name. This name will appear in SeeTest Reporter and in the generated report
    • generateReport - By default every Selenium test generates a report and takes screenshots after each command. To disable reports (and screenshots) pass this capability with a false value
    • takeScreenshots - take a screenshot of reports and the device reflection in the Grid page
    • newCommandTimeout - change the default timeout for each command in the test (default is 300 seconds)
    • newSessionWaitTimeout - change the default timeout for creating a new driver (default is 300 seconds)
    • platformName - run the test on the specified platform (Mac, Windows, iOS, etc...)
    • browserName - run the test on the specified browser (default is chrome)
    • browserVersion - run the test on the specified browser version


      BrowserVersion can also accept the value "latest" for the latest version or "latest-X" for versions before the latest. e.g if 'latest' is 70 then 'latest-3' will be 67

    • seleniumScreenshot - if set to true will take a screenshot using selenium grid and not via native OS API. By default set to false. This means the test will take longer.


      add this capability in tests that handle multiple browser windows in order to get a correct report

    • closePopups - provide information on which native popups to close (and how).
    • agentName - the name of the agent that the test will run on.
    • maxScreenshotInterval - the maximum time between consecutive screenshots (default is 10 seconds)
    • reportType - the type of the report that should be generated for the test: video or screenshot (default is both)

The returned capabilities include:

    • reportUrl - that provides a link to view the test report in SeeTest Reporter (if the test is configured to generate a report).
    • sessionId - the session ID of the test.
    • viewUrl - that provides a link to view the test's execution (Windows 10 and macOS only).

If the Selenium test is configured to generate a report, the driver capabilities will include a capability named reportUrl that provides a link to view the test report in SeeTest Reporter.

Below you can find an example written in Java specifying the capabilities above.

In order to be able to run the below code you will need

Selenium- Grid Execution
DesiredCapabilities dc = new DesiredCapabilities();
dc.setCapability("username", "<cloudUsername>");
dc.setCapability("password", "<cloudPassword>");
dc.setCapability("projectName", "<cloudProject>"); //only required if your user has several projects assigned to it. Otherwise, exclude this capability.
//dc.setCapability("accessKey", "<accessKey>"); // can be use instead of username,password and project.
dc.setCapability("generateReport", true);
dc.setCapability("testName", "<testName>");
dc.setCapability(CapabilityType.PLATFORM, Platform.WIN10);
dc.setCapability(CapabilityType.BROWSER_VERSION, "57.0.4");
dc.setCapability(CapabilityType.BROWSER_NAME, BrowserType.FIREFOX);
dc.setCapability("newCommandTimeout", 500);
dc.setCapability("newSessionWaitTimeout", 500);
dc.setCapability("agentName", "<agentName>");
dc.setCapability("maxScreenshotInterval", 10);
//dc.setCapability("seleniumScreenshot", true);
dc.setCapability("reportType", "video");
RemoteWebDriver driver = new RemoteWebDriver(new URL(cloudurl + "/wd/hub/"), dc);
String testReportUrl = driver.getCapabilities().getCapability("reportUrl");
String sessionId =  driver.getCapabilities().getCapability("sessionId"); //will return the session id as String.

Parallel Execution

If you run a test using the capabilities as they appear above, it will run on one device only. However, if you run this test on multiple threads, every thread creates a different instance of the test class which in turn initiates another test request. Running tests in parallel require that you understand the concept of multi-threaded execution (either by built-in specific language implementations or using unit testing frameworks). It also requires that your license includes the ability to run tests on multiple nodes. For more information about these two aspects, visit our documentation on the subject.

Setting test report status

There may be cases where the test developer may want to set the test report status manually.

For example:

  1. If the test fails on the client-side (and not on Selenium Grid side) the test report generated will be with Success status.
  2. If the test can fail but the test code catches the exception and the test developer would not like this failure to set the report status to Fail.

To set the test report status from the client code, one can use the commands:

driver.executeScript("seetest:client.setReportStatus(<test-status>, <error-message>)")
driver.executeScript("seetest:client.setReportStatus(<test-status>, <error-message>, <stacktrace>)")

where test-status is:

  • "true" or "passed" for success
  • "skipped" for skipped
  • everything else for fail

For example

driver.executeScript("seetest:client.setReportStatus(\"Skipped\", \"This test should skip\")");
driver.executeScript("seetest:client.setReportStatus(\"Failed\", \"Element text is wrong\",
                     \"java.lang.Throwable at ClientSideFailureTest.clientSideFailure( at ClientSideFailureTest.test(\")");

Add a step to test report with the status

Users can add a step in the report from the client code.

For example:

driver.executeScript(""\"This step should passed\",\"true\")");
driver.executeScript(""\"This step should failed\",\"false\")");

Add steps group to the report

User can add a group of steps in the report.

To begin a steps group, call the following command:

driver.executeScript("seetest:client.startStepsGroup("\"Name of steps group\")");

To end a steps group, call the following command:


All the steps that appear between 'startStepsGroup' and 'stopStepsGroup' will be part of the group of the steps.

For example:

driver.executeScript("seetest:client.startStepsGroup("\"Name of steps group\")");

add a step to test report before every 'it'

When user will run more than one it with one Driver you can set testName for each 'it' in the report:

exports.config = {  
        onPrepare: function() {
                specStarted: async function(result) {
                    await browser.executeScript('seetest:client.startGroup('+result.description+'));');

 onComplete: () => {
        specs: ['test.js']

Add test property (tag) to report

Users can add a test property (tag) to the report from the client code.

For example:

driver.executeScript("seetest:client.addTestProperty(\"key\", \"value\")");

Handling native OS popups

If during a selenium web test, the browser or OS displays a native popup that the user wants to close, he can specify how to close this popup.

Using the capability closePopups the user can specify one or more expressions that specify which native popups to look for and if found which button to click.

The user can specify one expression or a list of expressions.

For Windows each expression is in the form <regex>::<button-name> where

  • regex - Find a popup with a title that contains the regex
  • button-name - Name of a button to click on the associated popup

Native popups handling code - Windows
dc.setCapability("closePopups", "Windows Security::OK"); // Close popup to confirm client-certificate selection for Edge
dc.setCapability("closePopups", new String [] { "Windows Security::OK", "TitleRegex::Button" });

For macOS each expression should follow one of the following syntax formats

  • <text-to-find>::<button-name> - This will search for a popup with text-to-find in the browser's process and will press the button with button-name.
  • <text-to-find>@<process-name>::<button-name> - This will search for a popup with text-to-find in the process process-name and will press the button with button-name.

Native popups handling code - MacOS
// Example code to close popup from MacOS keychain security agent
dc.setCapability("closePopups", new String [] { "wants to sign using key@SecurityAgent::Always Allow" });

The default can change by setting the property 
popup-monitor-interval-in-seconds in the config/ file. A test that has a valid closePopups capability will search for a popup every X seconds where X is 5 by default.

Download a file to your client computer in a grid session

Users can download a file from the Selenium Agent machine to the local machine in the grid session.

File size up to 50MB.

For example:

byte[] content = null;
Object res = driver.executeScript("seetest:client.getFile("\"<SELENIUM_AGENT_FILE_NAME>\")");
content = Base64.getDecoder().decode((String) res);
FileUtils.writeByteArrayToFile(new File("<CLIENTS_PATH_+_FILE_NAME>"), content);

List all your session's files in a grid session (Chrome only)

Users can list all the files that their session downloaded in the grid session.

the returned type is List<String>.

For example:

List<String> files = (List<String>) driver.executeScript("seetest:client.getFileList()");
System.out.println("list: " + files);

Running with custom Firefox profile

Mostly used for client certificates.

Firefox saves client certificates in the profile but Selenium uses a temporary profile. To pass this issue we need to add a capability that will make Selenium run with our custom profile.

First, we need to make a profile and load our certificate on it:

  • Launch Firefox and click the menu icon found in the upper-right corner of the browser. After that, click the Preferences icon.
  • Go to the Certificates tab and then click the View Certificates button.
  • The previous step should have launched the Firefox Certificate Manager. Click the Your Certificates tab and then click the Import button.


  • The previous step should launch a browser that you can use to navigate to the directory where your client certificate file (usually a PKCS12 file with the .p12 or .pfx extension) is stored. Select the file and enter the required password. If you succeed, you should see a notification that says "Successfully restored your security certificate(s) and private key(s)." (or something to that effect). Click OK to proceed.


  • You should then see your newly imported certificate under the Your Certificates collection of your Firefox Certificate Manager.

Now our custom profile is done.

To use it with selenium we need to take the only the files named cert9.db and key4.db and pack them in a zip file (You can zip the entire profile and not just the certificate part, but it is not recommended):

Now all that is left is to add the profile to the desired capabilities:

File file = new File("[PATH_TO_PROFILE_ZIP_FILE]");
String firefoxProfile = "";
try {
	firefoxProfile = Base64.getEncoder().encodeToString(FileUtils.readFileToByteArray(file));
} catch (IOException e) {
dc.setCapability(FirefoxDriver.PROFILE, firefoxProfile);

We will get a driver with the custom profile we supplied.

  • No labels