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");
Methods
NOTE: Appium JS-Executor methods for Real Device Testing in Sauce Labs are limited and are indicated with the following badge:
SUPPORTED ON RDC
Method | Description |
---|---|
"sauce:job-result=passed" SUPPORTED ON RDC | 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: disable log" "sauce: enable log" | Turns off logging for certain commands within the test in order to omit sensitive data from the NOTE: This method does not omit the commands from other possible records. |
"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. |
"sauce:inject-image='/path/to/image/file.jpg'" SUPPORTED ON RDC | 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 */ @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)); }