The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

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

Selenium's JavascriptExecutor lets you use JavaScript commands in your test scripts to perform actions in the browser. We've developed a set of custom JavascriptExecutor methods you can use to annotate tests and record pass/fail status. You can also use these methods to track information in your Selenium log for debugging.

See the following sections for more information:

Basic Example

Here's a Java code sample setting a job's name to "My test":

((JavascriptExecutor)driver).executeScript("sauce:job-name=My test"); 


NOTE: Appium JS-Executor methods for Real Device Testing in Sauce Labs are limited and are indicated with the following badge:




Sets the pass/fail status of the job. Options are passed, failed, true, and false. True means passed and false means failed.
"sauce:job-name=My awesome job"
Sets the job name
Sets the job tags in a comma-separated list.
Sets the job’s build name.
"sauce: stop network" 
"sauce: start network"

Stops and restart the VM’s network connection (Mac OSX only).

"sauce: disable log"
"sauce: enable log"

Turns off logging for certain commands within the test in order to omit sensitive data from the log.json file; then re-enables logging.

NOTE: This method does not omit the commands from other possible records, such as the Selenium server log.

"sauce: break"
Sets a Sauce breakpoint in the test. Test execution will pause at this point, waiting for manual control by clicking in the test’s live video. 
"sauce:context=This line appears in the command list as 'info'"
Logs the given line in the job’s Selenium commands list.
"sauce:job-info={'build':'mybuild','name':'my test name', 'public':'team}"
Sets one or more job information fields to the values sent in the JSON-formatted dictionary.


Points to file for testing image injection (e.g. barcode scanning).

NOTE: Spacing in the methods is sensitive, i.e., some methods require a space following  sauce: (stop, start, disable, enable, break, and job-info), while other methods do not.

Setting Pass/Fail

Setting the pass/fail status of your tests is important for getting the most out of your insights, as Selenium has only three built-in states: In Progress, Error, and Complete.

You should update your tests to record pass/fail status with our REST API on completion, using a test framework, or the sauce:job-result method.

Code Example

This code is from a sample Java test script using TestNG. You can find the full version in our Test Frameworks repository

     * Method that gets invoked after test.
     * Dumps browser log and
     * Closes the browser


    public void tearDown(ITestResult result) throws Exception {

        //Gets browser logs if available.
        ((JavascriptExecutor) webDriver.get()).executeScript("sauce:job-result=" + (result.isSuccess() ? "passed" : "failed"));

Providing Context for Selenium Commands

One of the most difficult aspects of troubleshooting Selenium tests can be matching commands to browser actions. The sauce:context method provides you with a way to inject text into the command log to associate with a specific command, essentially adding a comment.

For example, in the command log on the left, it's hard to immediately see which command is responsible for following a link to the page, which one submitted a comment, and which one asserted that the comment was valid. In the screenshot on the right, each set of commands has been provided with a context. 

Code Example

In your script, assign a context with each step of the test is set using the sauce:context method. 

The following code examples are from the Java-TestNG-Selenium framework in our GitHub repository.

     * Method to be invoked after test.
     * Dumps browser log and
     * Closes the browser


    public void tearDown(ITestResult result) throws Exception {

        //Gets browser logs if available.
        ((JavascriptExecutor) webDriver.get()).executeScript("sauce:job-result=" + (result.isSuccess() ? "passed" : "failed"));

    protected void annotate(String text) {
        ((JavascriptExecutor) webDriver.get()).executeScript("sauce:context=" + text);

In your test script, specify the text you want associated with each step of the test:

public class TextInputTest extends TestBase {

     * Runs a simple test verifying if the comment input is functional.
     * @throws InvalidElementStateException

    @org.testng.annotations.Test(dataProvider = "hardCodedBrowsers")
    public void verifyCommentInputTest(String browser, String version, String os, Method method)
            throws MalformedURLException, InvalidElementStateException, UnexpectedException {
        this.createDriver(browser, version, os, method.getName());
        WebDriver driver = this.getWebDriver();

        String commentInputText = UUID.randomUUID().toString();
        this.annotate("Visiting GuineaPig page...");
        GuineaPigPage page = GuineaPigPage.visitPage(driver);

        this.annotate(String.format("Submitting comment: \"%s\"", commentInputText));

        this.annotate(String.format("Asserting submitted comment is: \"%s\"", commentInputText));