Creates a new WebDriver client, which provides control over a browser.
Every WebDriver command returns a {@code webdriver.promise.Promise} that represents the result of that command. Callbacks may be registered on this object to manipulate the command result or catch an expected error. Any commands scheduled with a callback are considered sub-commands and will execute before the next command in the current frame. For example:
var message = []; driver.call(message.push, message, 'a').then(function() { driver.call(message.push, message, 'b'); }); driver.call(message.push, message, 'c'); driver.call(function() { alert('message is abc? ' + (message.join('') == 'abc')); });
A base URL to run get requests against.
Selector element that has an ng-app in scope.
All get methods will be resolved against this base URL. Relative URLs are = resolved the way anchor tags resolve.
The wrapped webdriver instance. Use this to interact with pages that do not contain Angular (such as a log-in screen).
If true, Protractor will not attempt to synchronize with the page before performing actions. This can be harmful because Protractor will not wait until $timeouts and $http calls have been processed, which can cause tests to become flaky. This should be used only when necessary, such as when a page continuously polls an API using $timeout.
An object that holds custom test parameters.
The css selector for an element on which to find Angular. This is usually 'body' but if your ng-app is on a subsection of the page it may be a subelement.
Helper function for finding elements by css.
Helper function for finding arrays of elements by css.
Creates a new action sequence using this driver. The sequence will not be scheduled for execution until {@link webdriver.ActionSequence#perform} is called. Example:
driver.actions().
mouseDown(element1).
mouseMove(element2).
mouseUp().
perform();
A new action sequence for this instance.
Add a module to load before Angular whenever Protractor.get is called. Modules will be registered after existing modules already on the page, so any module registered here will override preexisting modules with the same name.
The name of the module to load or override.
The JavaScript to load the module.
Schedules a command to execute a custom function.
The function to execute.
The object in whose scope to execute the function.
Any arguments to pass to the function.
A promise that will be resolved with the function's result.
Clear the list of registered mock modules.
Schedules a command to close the current window.
A promise that will be resolved when this command has completed.
The control flow used by this instance.
Pauses the test and injects some helper functions into the browser, so that debugging may be done in the browser console.
This should be used under node in debug mode, i.e. with
protractor debug
While in the debugger, commands can be scheduled through webdriver by entering the repl: debug> repl Press Ctrl + C to leave rdebug repl
ptor.findElement(protractor.By.input('user').sendKeys('Laura')); ptor.debugger(); debug> c
This will run the sendKeys command as the next task, then re-enter the debugger.
Helper function for finding elements.
Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window. The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window.
Any arguments provided in addition to the script will be included as script arguments and may be referenced using the {@code arguments} object. Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned.
Unlike executing synchronous JavaScript with {@code webdriver.WebDriver.prototype.executeScript}, scripts executed with this function must explicitly signal they are finished by invoking the provided callback. This callback will always be injected into the executed function as the last argument, and thus may be referenced with {@code arguments[arguments.length - 1]}. The following steps will be taken for resolving this functions return value against the first argument to the script's callback function:
Example #1: Performing a sleep that is synchronized with the currently
selected window:
var start = new Date().getTime();
driver.executeAsyncScript(
'window.setTimeout(arguments[arguments.length - 1], 500);').
then(function() {
console.log('Elapsed time: ' + (new Date().getTime() - start) + ' ms');
});
Example #2: Synchronizing a test with an AJAX application:
var button = driver.findElement(By.id('compose-button'));
button.click();
driver.executeAsyncScript(
'var callback = arguments[arguments.length - 1];' +
'mailClient.getComposeWindowWidget().onload(callback);');
driver.switchTo().frame('composeWidget');
driver.findElement(By.id('to')).sendKEys('dog@example.com');
Example #3: Injecting a XMLHttpRequest and waiting for the result. In this
example, the inject script is specified with a function literal. When using
this format, the function is converted to a string for injection, so it
should not reference any symbols not defined in the scope of the page under
test.
driver.executeAsyncScript(function() {
var callback = arguments[arguments.length - 1];
var xhr = new XMLHttpRequest();
xhr.open("GET", "/resource/data.json", true);
xhr.onreadystatechange = function() {
if (xhr.readyState == 4) {
callback(xhr.resposneText);
}
}
xhr.send('');
}).then(function(str) {
console.log(JSON.parse(str)['food']);
});
The script to execute.
The arguments to pass to the script.
A promise that will resolve to the scripts return value.
Schedules a command to execute JavaScript in the context of the currently selected frame or window. The script fragment will be executed as the body of an anonymous function. If the script is provided as a function object, that function will be converted to a string for injection into the target window.
Any arguments provided in addition to the script will be included as script arguments and may be referenced using the {@code arguments} object. Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. Arrays and objects may also be used as script arguments as long as each item adheres to the types previously mentioned.
The script may refer to any variables accessible from the current window. Furthermore, the script will execute in the window's context, thus {@code document} may be used to refer to the current document. Any local variables will not be available once the script has finished executing, though global variables will persist.
If the script has a return value (i.e. if the script contains a return statement), then the following steps will be taken for resolving this functions return value:
The script to execute.
The arguments to pass to the script.
A promise that will resolve to the scripts return value.
Schedule a command to find an element on the page. If the element cannot be found, a {@code bot.ErrorCode.NO_SUCH_ELEMENT} result will be returned by the driver. Unlike other commands, this error cannot be suppressed. In other words, scheduling a command to find an element doubles as an assert that the element is present on the page. To test whether an element is present on the page, use {@code #isElementPresent} instead.
The search criteria for find an element may either be a
{@code webdriver.Locator} object, or a simple JSON object whose sole key
is one of the accepted locator strategies, as defined by
{@code webdriver.Locator.Strategy}. For example, the following two statements
are equivalent:
var e1 = driver.findElement(By.id('foo'));
var e2 = driver.findElement({id:'foo'});
When running in the browser, a WebDriver cannot manipulate DOM elements directly; it may do so only through a {@link webdriver.WebElement} reference. This function may be used to generate a WebElement from a DOM element. A reference to the DOM element will be stored in a known location and this driver will attempt to retrieve it through {@link #executeScript}. If the element cannot be found (eg, it belongs to a different document than the one this instance is currently focused on), a {@link bot.ErrorCode.NO_SUCH_ELEMENT} error will be returned.
The locator strategy to use when searching for the element, or the actual DOM element to be located by the server.
Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.
A WebElement that can be used to issue commands against the located element. If the element is not found, the element will be invalidated and all scheduled commands aborted.
Schedule a command to search for multiple elements on the page.
The locator strategy to use when searching for the element.
Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.
A promise that will be resolved to an array of the located {@link webdriver.WebElement}s.
Schedules a command to navigate to the given URL.
The fully qualified URL to open.
A promise that will be resolved when the document has finished loading.
Schedules a command to retrieve the current list of available window handles.
A promise that will be resolved with an array of window handles.
A promise that will resolve with the this instance's capabilities.
Schedules a command to retrieve the URL of the current page.
A promise that will be resolved with the current URL.
Returns the current absolute url from AngularJS.
Schedules a command to retrieve the current page's source. The page source returned is a representation of the underlying DOM: do not expect it to be formatted or escaped in the same way as the response sent from the web server.
A promise that will be resolved with the current page source.
A promise for this client's session.
Schedules a command to retrieve the current page's title.
A promise that will be resolved with the current page's title.
Schedules a command to retrieve they current window handle.
A promise that will be resolved with the current window handle.
Schedules a command to test if an element is present on the page.
If given a DOM element, this function will check if it belongs to the document the driver is currently focused on. Otherwise, the function will test if at least one element can be found with the given search criteria.
The locator strategy to use when searching for the element, or the actual DOM element to be located by the server.
Arguments to pass to {@code #executeScript} if using a JavaScript locator. Otherwise ignored.
A promise that will resolve to whether the element is present on the page.
The options interface for this instance.
The navigation interface for this instance.
Schedules a command to quit the current session. After calling quit, this instance will be invalidated and may no longer be used to issue commands against the browser.
A promise that will be resolved when the command has completed.
Schedules a {@code webdriver.Command} to be executed by this driver's {@code webdriver.CommandExecutor}.
The command to schedule.
A description of the command for debugging.
A promise that will be resolved with the command result.
Schedules a command to make the driver sleep for the given amount of time.
The amount of time, in milliseconds, to sleep.
A promise that will be resolved when the sleep has finished.
The target locator interface for this instance.
Schedule a command to take a screenshot. The driver makes a best effort to return a screenshot of the following, in order of preference:
A promise that will be resolved to the screenshot as a base-64 encoded PNG.
Schedules a command to wait for a condition to hold, as defined by some user supplied function. If any errors occur while evaluating the wait, they will be allowed to propagate.
The function to evaluate as a wait condition.
How long to wait for the condition to be true.
An optional message to use if the wait times out.
A promise that will be resolved when the wait condition has been satisfied.
Instruct webdriver to wait until Angular has finished rendering and has no outstanding $http calls before continuing.
A promise that will resolve to the scripts return value.
Wrap a webdriver.WebElement with protractor specific functionality.
the wrapped web element.