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 an example of how you might set a job's name to "My test":
((JavascriptExecutor)driver).executeScript("sauce:job-name=My test");
Methods
| Method | Description |
|---|---|
"sauce:job-result=passed" | 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 |
"sauce:job-tags=tag1,tag2,tag3" | Sets the job tags in a comma-separated list. |
"sauce:job-build=mybuild123" | Sets the job’s build name. |
"sauce: stop network" "sauce: start network" | Stops and restart the VM’s network connection (Mac OSX only). |
"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. |
| Logs the given line in the job’s Selenium commands list. |
| Sets one or more job information fields to the values sent in the JSON-formatted dictionary. |
Spaces are Sensitive
Note the space required in sauce: stop, start, break, and job-info, not used in the other methods.
Setting Pass/Fail
Setting the pass/fail status of your tests is important for getting the most out of your analytics, 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
*/
@AfterMethod
public void tearDown(ITestResult result) throws Exception {
//Gets browser logs if available.
((JavascriptExecutor) webDriver.get()).executeScript("sauce:job-result=" + (result.isSuccess() ? "passed" : "failed"));
webDriver.get().quit();
}
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 TestBase.java 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
*/
@AfterMethod
public void tearDown(ITestResult result) throws Exception {
//Gets browser logs if available.
((JavascriptExecutor) webDriver.get()).executeScript("sauce:job-result=" + (result.isSuccess() ? "passed" : "failed"));
webDriver.get().quit();
}
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));
page.submitComment(commentInputText);
this.annotate(String.format("Asserting submitted comment is: \"%s\"", commentInputText));
Assert.assertTrue(page.getSubmittedCommentText().contains(commentInputText));
}
Overview
Content Tools