diff --git a/gulpfile.js b/gulpfile.js index ba83286d6..c3cb36fe2 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -65,6 +65,11 @@ gulp.task('built:copy', () => { .pipe(gulp.dest('built/')); }); +gulp.task('built:copy:typings', () => { + return gulp.src(['lib/selenium-webdriver/**/*.d.ts']) + .pipe(gulp.dest('built/selenium-webdriver/')); +}); + gulp.task('webdriver:update', (done) => { runSpawn(done, 'node', ['bin/webdriver-manager', 'update']); }); @@ -88,7 +93,7 @@ gulp.task('prepublish', gulp.series('checkVersion', 'tsc', 'built:copy')); gulp.task('pretest', gulp.series( 'checkVersion', gulp.parallel('webdriver:update', 'tslint', 'format'), - 'tsc', 'built:copy', 'tsc:spec')); + 'tsc', 'built:copy', 'built:copy:typings', 'tsc:spec')); gulp.task('default', gulp.series('prepublish')); diff --git a/lib/browser.ts b/lib/browser.ts index 68e101f93..1acb8980f 100644 --- a/lib/browser.ts +++ b/lib/browser.ts @@ -1,7 +1,9 @@ import {BPClient} from 'blocking-proxy'; -import {By, Command as WdCommand, ICommandName, Navigation, promise as wdpromise, Session, WebDriver, WebElement, WebElementPromise} from 'selenium-webdriver'; +import {By, Navigation, WebDriver, WebElement, WebElementPromise} from 'selenium-webdriver'; +import {Command, ICommandName} from 'selenium-webdriver/lib/command'; import * as url from 'url'; -import {extend as extendWD, ExtendedWebDriver} from 'webdriver-js-extender'; + +const CommandName = require('selenium-webdriver/lib/command').Name as ICommandName; import {build$, build$$, ElementArrayFinder, ElementFinder} from './element'; import {IError} from './exitCodes'; @@ -11,9 +13,6 @@ import {Logger} from './logger'; import {Plugins} from './plugins'; const clientSideScripts = require('./clientsidescripts'); -// TODO: fix the typings for selenium-webdriver/lib/command -const Command = require('selenium-webdriver/lib/command').Command as typeof WdCommand; -const CommandName = require('selenium-webdriver/lib/command').Name as ICommandName; // jshint browser: true @@ -33,15 +32,6 @@ for (let foo in require('selenium-webdriver')) { exports[foo] = require('selenium-webdriver')[foo]; } - -// Explicitly define types for webdriver.WebDriver and ExtendedWebDriver. -// We do this because we use composition over inheritance to implement polymorphism, and therefore -// we don't want to inherit WebDriver's constructor. -export class AbstractWebDriver {} -export interface AbstractWebDriver extends WebDriver {} -export class AbstractExtendedWebDriver extends AbstractWebDriver {} -export interface AbstractExtendedWebDriver extends ExtendedWebDriver {} - /** * Mix a function from one object onto another. The function will still be * called in the context of the original object. Any arguments of type @@ -109,7 +99,7 @@ function buildElementHelper(browser: ProtractorBrowser): ElementHelper { * @param {boolean=} opt_untrackOutstandingTimeouts Whether Protractor should * stop tracking outstanding $timeouts. */ -export class ProtractorBrowser extends AbstractExtendedWebDriver { +export class ProtractorBrowser { /** * @type {ProtractorBy} */ @@ -121,12 +111,11 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { ExpectedConditions: ProtractorExpectedConditions; /** - * The wrapped webdriver instance. Use this to interact with pages that do - * not contain Angular (such as a log-in screen). + * The browser's WebDriver instance * - * @type {webdriver_extensions.ExtendedWebDriver} + * @type {webdriver.WebDriver} */ - driver: ExtendedWebDriver; + driver: WebDriver; /** * The client used to control the BlockingProxy. If unset, BlockingProxy is @@ -278,8 +267,7 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { * Information about mock modules that will be installed during every * get(). * - * @type {Array<{name: string, script: function|string, args: - * Array.}>} + * @type {Array<{name: string, script: function|string, args: Array.}>} */ mockModules_: {name: string, script: string|Function, args: any[]}[]; @@ -304,32 +292,23 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { constructor( webdriverInstance: WebDriver, opt_baseUrl?: string, opt_rootElement?: string|Promise, opt_untrackOutstandingTimeouts?: boolean, opt_blockingProxyUrl?: string) { - super(); // These functions should delegate to the webdriver instance, but should // wait for Angular to sync up before performing the action. This does not // include functions which are overridden by protractor below. let methodsToSync = ['getCurrentUrl', 'getPageSource', 'getTitle']; - let extendWDInstance: ExtendedWebDriver; - try { - extendWDInstance = extendWD(webdriverInstance); - } catch (e) { - // Probably not a driver that can be extended (e.g. gotten using - // `directConnect: true` in the config) - extendWDInstance = webdriverInstance as ExtendedWebDriver; - } // Mix all other driver functionality into Protractor. Object.getOwnPropertyNames(WebDriver.prototype).forEach(method => { - if (!this[method] && typeof(extendWDInstance as any)[method] === 'function') { + if (!this[method] && typeof(webdriverInstance as any)[method] === 'function') { if (methodsToSync.indexOf(method) !== -1) { - ptorMixin(this, extendWDInstance, method, this.waitForAngular.bind(this)); + ptorMixin(this, webdriverInstance, method, this.waitForAngular.bind(this)); } else { - ptorMixin(this, extendWDInstance, method); + ptorMixin(this, webdriverInstance, method); } } }); - this.driver = extendWDInstance; + this.driver = webdriverInstance; if (opt_blockingProxyUrl) { logger.info('Starting BP client for ' + opt_blockingProxyUrl); this.bpClient = new BPClient(opt_blockingProxyUrl); @@ -490,10 +469,9 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { } // TODO(selenium4): schedule does not exist on driver. Should use execute instead. - return (this.driver as any) - .execute(new Command(CommandName.EXECUTE_SCRIPT) - .setParameter('script', script) - .setParameter('args', scriptArgs)); + return this.driver.execute((new Command(CommandName.EXECUTE_SCRIPT) as Command) + .setParameter('script', script) + .setParameter('args', scriptArgs)); } /** @@ -620,7 +598,7 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { } /** - * Waits for Angular to finish rendering before searching for elements. + * Waits for Angular to finish renderActionSequenceing before searching for elements. * @see webdriver.WebDriver.findElement * @returns {!webdriver.WebElementPromise} A promise that will be resolved to * the located {@link webdriver.WebElement}. @@ -882,7 +860,7 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { * await browser.get('http://angular.github.io/protractor/#/tutorial'); * await browser.setLocation('api'); * expect(await browser.getCurrentUrl()) - * .toBe('http://angular.github.io/protractor/#/api'); + * .toBe('http://angular.g../../ithub.io/protractor/#/api'); * * @param {string} url In page URL using the same syntax as $location.url() * @returns {!Promise} A promise that will resolve once @@ -921,18 +899,4 @@ export class ProtractorBrowser extends AbstractExtendedWebDriver { return await this.executeScriptWithDescription( clientSideScripts.getLocationAbsUrl, 'Protractor.getLocationAbsUrl()', rootEl); } - - /** - * Determine if the control flow is enabled. - * - * @returns true if the control flow is enabled, false otherwise. - */ - controlFlowIsEnabled() { - if ((wdpromise as any).USE_PROMISE_MANAGER !== undefined) { - return (wdpromise as any).USE_PROMISE_MANAGER; - } else { - // True for old versions of `selenium-webdriver`, probably false in >=5.0.0 - return !!wdpromise.ControlFlow; - } - } } diff --git a/lib/driverProviders/attachSession.ts b/lib/driverProviders/attachSession.ts index ca385161b..5b8ee11ae 100644 --- a/lib/driverProviders/attachSession.ts +++ b/lib/driverProviders/attachSession.ts @@ -4,14 +4,12 @@ * it down, and setting up the driver correctly. */ import {Session, WebDriver} from 'selenium-webdriver'; +import {Executor, HttpClient} from 'selenium-webdriver/http'; import {Config} from '../config'; import {Logger} from '../logger'; - import {DriverProvider} from './driverProvider'; -const http = require('selenium-webdriver/http'); - let logger = new Logger('attachSession'); export class AttachSession extends DriverProvider { @@ -36,9 +34,9 @@ export class AttachSession extends DriverProvider { * @return {WebDriver} webdriver instance */ async getNewDriver(): Promise { - const httpClient = new http.HttpClient(this.config_.seleniumAddress); - const executor = new http.Executor(httpClient); - const session = new Session(this.config_.seleniumSessionId, null); + const httpClient: HttpClient = new HttpClient(this.config_.seleniumAddress); + const executor: Executor = new Executor(httpClient); + const session: Session = new Session(this.config_.seleniumSessionId, null); const newDriver = new WebDriver(session, executor); this.drivers_.push(newDriver); diff --git a/lib/driverProviders/direct.ts b/lib/driverProviders/direct.ts index e7b0dc9db..e37aaea88 100644 --- a/lib/driverProviders/direct.ts +++ b/lib/driverProviders/direct.ts @@ -5,8 +5,9 @@ */ import * as fs from 'fs'; import {Capabilities, WebDriver} from 'selenium-webdriver'; -import {Driver as DriverForChrome, ServiceBuilder as ChromeServiceBuilder} from 'selenium-webdriver/chrome'; -import {Driver as DriverForFirefox, ServiceBuilder as FirefoxServiceBuilder} from 'selenium-webdriver/firefox'; +import {Driver as DriverForChrome, ServiceBuilder as ServiceBuilderForChrome} from 'selenium-webdriver/chrome'; +import {Driver as DriverForFirefox, ServiceBuilder as SerivceBuilderForFirefox} from 'selenium-webdriver/firefox'; + import {ChromeDriver, GeckoDriver} from 'webdriver-manager'; import {Config} from '../config'; @@ -73,7 +74,8 @@ export class Direct extends DriverProvider { '. Run \'webdriver-manager update\' to download binaries.'); } - let chromeService = new ChromeServiceBuilder(chromeDriverFile).build(); + const chromeService = + (new ServiceBuilderForChrome(chromeDriverFile) as ServiceBuilderForChrome).build(); driver = await DriverForChrome.createSession( new Capabilities(this.config_.capabilities), chromeService); break; @@ -97,7 +99,7 @@ export class Direct extends DriverProvider { '. Run \'webdriver-manager update\' to download binaries.'); } - let firefoxService = new FirefoxServiceBuilder(geckoDriverFile).build(); + let firefoxService = new SerivceBuilderForFirefox(geckoDriverFile).build(); driver = await DriverForFirefox.createSession( new Capabilities(this.config_.capabilities), firefoxService); break; diff --git a/lib/driverProviders/driverProvider.ts b/lib/driverProviders/driverProvider.ts index f562db5e1..cd78702ef 100644 --- a/lib/driverProviders/driverProvider.ts +++ b/lib/driverProviders/driverProvider.ts @@ -4,13 +4,13 @@ * it down, and setting up the driver correctly. */ import {Builder, WebDriver} from 'selenium-webdriver'; - import {BlockingProxyRunner} from '../bpRunner'; import {Config} from '../config'; import {BrowserError} from '../exitCodes'; import {Logger} from '../logger'; let logger = new Logger('driverProvider'); + export abstract class DriverProvider { drivers_: WebDriver[]; config_: Config; @@ -43,9 +43,9 @@ export abstract class DriverProvider { * Create a new driver. * * @public - * @return webdriver instance + * @return a promise to a webdriver instance */ - async getNewDriver() { + async getNewDriver(): Promise { let builder: Builder; if (this.config_.useBlockingProxy) { builder = diff --git a/lib/driverProviders/local.ts b/lib/driverProviders/local.ts index 078631efa..6c64b9fb0 100644 --- a/lib/driverProviders/local.ts +++ b/lib/driverProviders/local.ts @@ -19,7 +19,7 @@ import {DriverProvider} from './driverProvider'; let logger = new Logger('local'); export class Local extends DriverProvider { - server_: any; + server_: SeleniumServer; constructor(config: Config) { super(config); this.server_ = null; diff --git a/lib/driverProviders/mock.ts b/lib/driverProviders/mock.ts index b183feb81..3b18da1ef 100644 --- a/lib/driverProviders/mock.ts +++ b/lib/driverProviders/mock.ts @@ -9,7 +9,7 @@ import {Config} from '../config'; import {DriverProvider} from './driverProvider'; export class MockExecutor { - execute(command: any): any {} + execute(_: any): any {} } export class Mock extends DriverProvider { @@ -39,8 +39,8 @@ export class Mock extends DriverProvider { * @return webdriver instance */ async getNewDriver(): Promise { - let mockSession = new Session('test_session_id', {}); - let newDriver = new WebDriver(mockSession, new MockExecutor()); + const mockSession: Session = new Session('test_session_id', {}); + const newDriver: WebDriver = new WebDriver(mockSession, new MockExecutor()); this.drivers_.push(newDriver); return newDriver; } diff --git a/lib/driverProviders/sauce.ts b/lib/driverProviders/sauce.ts index 6816a24a5..5c90f9bed 100644 --- a/lib/driverProviders/sauce.ts +++ b/lib/driverProviders/sauce.ts @@ -4,7 +4,7 @@ * it down, and setting up the driver correctly. */ -import {Session, WebDriver} from 'selenium-webdriver'; +import {WebDriver} from 'selenium-webdriver'; import * as util from 'util'; import {Config} from '../config'; @@ -33,14 +33,13 @@ export class Sauce extends DriverProvider { * @return {Promise} A promise that will resolve when the update is complete. */ updateJob(update: any): Promise { - let mappedDrivers = this.drivers_.map((driver: WebDriver) => { - driver.getSession().then((session: Session) => { - logger.info('SauceLabs results available at http://saucelabs.com/jobs/' + session.getId()); - this.sauceServer_.updateJob(session.getId(), update, (err: Error) => { - if (err) { - throw new Error('Error updating Sauce pass/fail status: ' + util.inspect(err)); - } - }); + let mappedDrivers = this.drivers_.map(async (driver: WebDriver) => { + const session = await driver.getSession(); + logger.info('SauceLabs results available at http://saucelabs.com/jobs/' + session.getId()); + this.sauceServer_.updateJob(session.getId(), update, (err: Error) => { + if (err) { + throw new Error('Error updating Sauce pass/fail status: ' + util.inspect(err)); + } }); }); return Promise.all(mappedDrivers); diff --git a/lib/element.ts b/lib/element.ts index bdde04fff..97d1fa15c 100644 --- a/lib/element.ts +++ b/lib/element.ts @@ -889,7 +889,7 @@ export class ElementFinder extends WebdriverWebElement { const id = this.elementArrayFinder_.getWebElements().then((parentWebElements: WebElement[]) => { return parentWebElements[0]; }); - return new WebElementPromise(this.browser_.driver, id); + return new WebElementPromise(this.browser_.driver, id) as WebElementPromise; } /** diff --git a/lib/index.ts b/lib/index.ts index 479dd26a3..9d5beb26d 100644 --- a/lib/index.ts +++ b/lib/index.ts @@ -1,13 +1,12 @@ import {ElementHelper, ProtractorBrowser} from './browser'; import {ElementArrayFinder, ElementFinder} from './element'; import {ProtractorExpectedConditions} from './expectedConditions'; -import {Locator, ProtractorBy} from './locators'; +import {ProtractorBy} from './locators'; import {PluginConfig, ProtractorPlugin} from './plugins'; import {Ptor} from './ptor'; -// Re-export selenium-webdriver types. -// TODO(selenium4): Actions class typings missing. ActionSequence is deprecated. -export {/*Actions,*/ Browser, Builder, Button, Capabilities, Capability, error, EventEmitter, FileDetector, Key, logging, promise, Session, until, WebDriver, WebElement, WebElementPromise} from 'selenium-webdriver'; +// Re-export selenium-webdriver types from typings directory. +export {Actions, Browser, Builder, Button, Capabilities, Capability, error, EventEmitter, FileDetector, Key, logging, promise, Session, until, WebDriver, WebElement, WebElementPromise} from 'selenium-webdriver'; // Re-export public types. export {ElementHelper, ProtractorBrowser} from './browser'; export {Config} from './config'; @@ -20,14 +19,13 @@ export {Runner} from './runner'; export type PluginConfig = PluginConfig; export type ProtractorPlugin = ProtractorPlugin; -export let utils = { +export const utils = { firefox: require('selenium-webdriver/firefox'), http: require('selenium-webdriver/http'), remote: require('selenium-webdriver/remote') }; -export let Command = require('selenium-webdriver/lib/command').Command; -export let CommandName = require('selenium-webdriver/lib/command').Name; +export {Command, Name as CommandName} from 'selenium-webdriver/lib/command'; // Export API instances based on the global Protractor object. // We base this on NodeJS `global` because we do not want to mask diff --git a/lib/locators.ts b/lib/locators.ts index 2fe317df8..1dda967ab 100644 --- a/lib/locators.ts +++ b/lib/locators.ts @@ -10,7 +10,7 @@ export class WebdriverBy { css: (css: string) => By = By.css; id: (id: string) => By = By.id; linkText: (linkText: string) => By = By.linkText; - js: (js: string|Function, ...var_args: any[]) => By = By.js; + js: (js: string|Function, ...var_args: any[]) => (webdriver: WebDriver) => Promise = By.js; name: (name: string) => By = By.name; partialLinkText: (partialText: string) => By = By.partialLinkText; tagName: (tagName: string) => By = By.tagName; diff --git a/lib/plugins.ts b/lib/plugins.ts index bccd742e2..6fd77e99e 100644 --- a/lib/plugins.ts +++ b/lib/plugins.ts @@ -1,5 +1,3 @@ -import * as webdriver from 'selenium-webdriver'; - import {ProtractorBrowser} from './browser'; import {Config} from './config'; import {ConfigParser} from './configParser'; @@ -109,11 +107,11 @@ export interface ProtractorPlugin { * @throws {*} If this function throws an error, a failed assertion is added to * the test results. * - * @return {webdriver.promise.Promise=} Can return a promise, in which case + * @return {Promise=} Can return a promise, in which case * protractor will wait for the promise to resolve before continuing. If * the promise is rejected, a failed assertion is added to the test results. */ - onPageLoad?(browser: ProtractorBrowser): void|webdriver.promise.Promise; + onPageLoad?(browser: ProtractorBrowser): void|Promise; /** * This is called inside browser.get() directly after angular is done @@ -127,11 +125,11 @@ export interface ProtractorPlugin { * @throws {*} If this function throws an error, a failed assertion is added to * the test results. * - * @return {webdriver.promise.Promise=} Can return a promise, in which case + * @return {Promise=} Can return a promise, in which case * protractor will wait for the promise to resolve before continuing. If * the promise is rejected, a failed assertion is added to the test results. */ - onPageStable?(browser: ProtractorBrowser): void|webdriver.promise.Promise; + onPageStable?(browser: ProtractorBrowser): void|Promise; /** * Between every webdriver action, Protractor calls browser.waitForAngular() to @@ -146,14 +144,14 @@ export interface ProtractorPlugin { * @throws {*} If this function throws an error, a failed assertion is added to * the test results. * - * @return {webdriver.promise.Promise=} Can return a promise, in which case + * @return {Promise=} Can return a promise, in which case * protractor will wait for the promise to resolve before continuing. If the * promise is rejected, a failed assertion is added to the test results, and * protractor will continue onto the next command. If nothing is returned or * something other than a promise is returned, protractor will continue * onto the next command. */ - waitForPromise?(browser: ProtractorBrowser): webdriver.promise.Promise; + waitForPromise?(browser: ProtractorBrowser): Promise; /** * Between every webdriver action, Protractor calls browser.waitForAngular() to @@ -169,13 +167,13 @@ export interface ProtractorPlugin { * @throws {*} If this function throws an error, a failed assertion is added to * the test results. * - * @return {webdriver.promise.Promise|boolean} If truthy, Protractor + * @return {Promise|boolean} If truthy, Protractor * will continue onto the next command. If falsy, webdriver will * continuously re-run this function until it is truthy. If a rejected promise * is returned, a failed assertion is added to the test results, and Protractor * will continue onto the next command. */ - waitForCondition?(browser: ProtractorBrowser): webdriver.promise.Promise|boolean; + waitForCondition?(browser: ProtractorBrowser): Promise|boolean; /** * Used to turn off default checks for angular stability @@ -478,7 +476,7 @@ export class Plugins { private pluginFunFactory(funName: string, failReturnVal?: boolean): (...args: any[]) => Promise; private pluginFunFactory(funName: string, failReturnVal?: boolean): - (...args: any[]) => webdriver.promise.Promise; + (...args: any[]) => Promise; private pluginFunFactory(funName: string, failReturnVal?: boolean) { return (...args: any[]) => { const promises = diff --git a/lib/ptor.ts b/lib/ptor.ts index f8c7af88b..1ac4ff5b2 100644 --- a/lib/ptor.ts +++ b/lib/ptor.ts @@ -2,6 +2,7 @@ import * as webdriver from 'selenium-webdriver'; import * as chrome from 'selenium-webdriver/chrome'; import * as firefox from 'selenium-webdriver/firefox'; import * as http from 'selenium-webdriver/http'; +import * as command from 'selenium-webdriver/lib/command'; import * as remote from 'selenium-webdriver/remote'; import {ElementHelper, ProtractorBrowser} from './browser'; @@ -34,7 +35,7 @@ export class Ptor { ProtractorExpectedConditions = require('./expectedConditions').ProtractorExpectedConditions; // Export selenium webdriver. - ActionSequence = webdriver.ActionSequence; + Actions = webdriver.Actions; Browser = webdriver.Browser; Builder = webdriver.Builder; Button = webdriver.Button; @@ -51,8 +52,8 @@ export class Ptor { logging = webdriver.logging; promise = webdriver.promise; until = webdriver.until; - Command = require('selenium-webdriver/lib/command').Command; - CommandName = require('selenium-webdriver/lib/command').Name; + Command = command.Command; + CommandName = command.Name; utils = {firefox: firefox, http: http, remote: remote, chrome: chrome}; } diff --git a/lib/runner.ts b/lib/runner.ts index de0bfff8b..f8f29418d 100644 --- a/lib/runner.ts +++ b/lib/runner.ts @@ -1,6 +1,4 @@ import {EventEmitter} from 'events'; -// TODO(cnishina): remove when selenium webdriver is upgraded. -import {promise as wdpromise, WebDriver} from 'selenium-webdriver'; import * as util from 'util'; import {ProtractorBrowser} from './browser'; @@ -324,11 +322,6 @@ export class Runner extends EventEmitter { throw new Error('Spec patterns did not match any files.'); } - // TODO(selenium4): Remove when selenium is upgraded. - if (this.config_.SELENIUM_PROMISE_MANAGER != null) { - (wdpromise as any).USE_PROMISE_MANAGER = this.config_.SELENIUM_PROMISE_MANAGER; - } - if (this.config_.webDriverLogDir || this.config_.highlightDelay) { this.config_.useBlockingProxy = true; } diff --git a/lib/selenium-webdriver/chrome.d.ts b/lib/selenium-webdriver/chrome.d.ts new file mode 100644 index 000000000..e44191bd0 --- /dev/null +++ b/lib/selenium-webdriver/chrome.d.ts @@ -0,0 +1,350 @@ +import * as http from './http'; +import * as webdriver from './index'; +import * as remote from './remote'; + +/** + * Creates a new WebDriver client for Chrome. + * + * @extends {webdriver.WebDriver} + */ +export class Driver extends webdriver.WebDriver { + /** + * Creates a new session with the ChromeDriver. + * + * @param {(Capabilities|Options)=} opt_config The configuration options. + * @param {(remote.DriverService|http.Executor)=} opt_serviceExecutor Either + * a DriverService to use for the remote end, or a preconfigured executor + * for an externally managed endpoint. If neither is provided, the + * {@linkplain ##getDefaultService default service} will be used by + * default. + * @return {!Driver} A new driver instance. + */ + static createSession( + opt_config?: Options|webdriver.CreateSessionCapabilities, + opt_service?: remote.DriverService|http.Executor): Driver; +} + +export interface IOptionsValues { + args: string[]; + binary?: string; + detach: boolean; + extensions: string[]; + localState?: any; + logFile?: string; + prefs?: any; +} + +export interface IPerfLoggingPrefs { + enableNetwork: boolean; + enablePage: boolean; + enableTimeline: boolean; + tracingCategories: string; + bufferUsageReportingInterval: number; +} + +/** + * Class for managing ChromeDriver specific options. + */ +export class Options extends webdriver.Capabilities { + /** + * @constructor + */ + constructor(); + + /** + * Extracts the ChromeDriver specific options from the given capabilities + * object. + * @param {!webdriver.Capabilities} capabilities The capabilities object. + * @return {!Options} The ChromeDriver options. + */ + static fromCapabilities(capabilities: webdriver.Capabilities): Options; + + /** + * Add additional command line arguments to use when launching the Chrome + * browser. Each argument may be specified with or without the '--' prefix + * (e.g. '--foo' and 'foo'). Arguments with an associated value should be + * delimited by an '=': 'foo=bar'. + * @param {...(string|!Array.)} var_args The arguments to add. + * @return {!Options} A self reference. + */ + addArguments(...var_args: string[]): Options; + + /** + * Configures the chromedriver to start Chrome in headless mode. + * + * > __NOTE:__ Resizing the browser window in headless mode is only supported + * > in Chrome 60. Users are encouraged to set an initial window size with + * > the {@link #windowSize windowSize({width, height})} option. + * + * @return {!Options} A self reference. + */ + headless(): Options; + + /** + * Sets the initial window size. + * + * @param {{width: number, height: number}} size The desired window size. + * @return {!Options} A self reference. + * @throws {TypeError} if width or height is unspecified, not a number, or + * less than or equal to 0. + */ + windowSize(size: {width: number, height: number}): Options; + + /** + * List of Chrome command line switches to exclude that ChromeDriver by + * default passes when starting Chrome. Do not prefix switches with '--'. + * + * @param {...(string|!Array)} var_args The switches to exclude. + * @return {!Options} A self reference. + */ + excludeSwitches(...var_args: string[]): Options; + + /** + * Add additional extensions to install when launching Chrome. Each extension + * should be specified as the path to the packed CRX file, or a Buffer for an + * extension. + * @param {...(string|!Buffer|!Array.<(string|!Buffer)>)} var_args The + * extensions to add. + * @return {!Options} A self reference. + */ + addExtensions(...var_args: any[]): Options; + + /** + * Sets the path to the Chrome binary to use. On Mac OS X, this path should + * reference the actual Chrome executable, not just the application binary + * (e.g. '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'). + * + * The binary path be absolute or relative to the chromedriver server + * executable, but it must exist on the machine that will launch Chrome. + * + * @param {string} path The path to the Chrome binary to use. + * @return {!Options} A self reference. + */ + setChromeBinaryPath(path: string): Options; + + /** + * Sets whether to leave the started Chrome browser running if the controlling + * ChromeDriver service is killed before {@link webdriver.WebDriver#quit()} is + * called. + * @param {boolean} detach Whether to leave the browser running if the + * chromedriver service is killed before the session. + * @return {!Options} A self reference. + */ + detachDriver(detach: boolean): Options; + + /** + * Sets the user preferences for Chrome's user profile. See the 'Preferences' + * file in Chrome's user data directory for examples. + * @param {!Object} prefs Dictionary of user preferences to use. + * @return {!Options} A self reference. + */ + setUserPreferences(prefs: any): Options; + + /** + * Sets the performance logging preferences. Options include: + * + * - `enableNetwork`: Whether or not to collect events from Network domain. + * - `enablePage`: Whether or not to collect events from Page domain. + * - `enableTimeline`: Whether or not to collect events from Timeline domain. + * Note: when tracing is enabled, Timeline domain is implicitly disabled, + * unless `enableTimeline` is explicitly set to true. + * - `tracingCategories`: A comma-separated string of Chrome tracing + * categories for which trace events should be collected. An unspecified or + * empty string disables tracing. + * - `bufferUsageReportingInterval`: The requested number of milliseconds + * between DevTools trace buffer usage events. For example, if 1000, then + * once per second, DevTools will report how full the trace buffer is. If + * a report indicates the buffer usage is 100%, a warning will be issued. + * + * @param {{enableNetwork: boolean, + * enablePage: boolean, + * enableTimeline: boolean, + * tracingCategories: string, + * bufferUsageReportingInterval: number}} prefs The performance + * logging preferences. + * @return {!Options} A self reference. + */ + setPerfLoggingPrefs(prefs: IPerfLoggingPrefs): Options; + + /** + * Sets preferences for the 'Local State' file in Chrome's user data + * directory. + * @param {!Object} state Dictionary of local state preferences. + * @return {!Options} A self reference. + */ + setLocalState(state: any): Options; + + /** + * Sets the name of the activity hosting a Chrome-based Android WebView. This + * option must be set to connect to an [Android WebView]( + * https://sites.google.com/a/chromium.org/chromedriver/getting-started/getting-started---android) + * + * @param {string} name The activity name. + * @return {!Options} A self reference. + */ + androidActivity(name: string): Options; + + /** + * Sets the device serial number to connect to via ADB. If not specified, the + * ChromeDriver will select an unused device at random. An error will be + * returned if all devices already have active sessions. + * + * @param {string} serial The device serial number to connect to. + * @return {!Options} A self reference. + */ + androidDeviceSerial(serial: string): Options; + + /** + * Configures the ChromeDriver to launch Chrome on Android via adb. This + * function is shorthand for + * {@link #androidPackage options.androidPackage('com.android.chrome')}. + * @return {!Options} A self reference. + */ + androidChrome(): Options; + + /** + * Sets the package name of the Chrome or WebView app. + * + * @param {?string} pkg The package to connect to, or `null` to disable + * Android and switch back to using desktop Chrome. + * @return {!Options} A self reference. + */ + androidPackage(pkg: string): Options; + + /** + * Sets the process name of the Activity hosting the WebView (as given by + * `ps`). If not specified, the process name is assumed to be the same as + * {@link #androidPackage}. + * + * @param {string} processName The main activity name. + * @return {!Options} A self reference. + */ + androidProcess(processName: string): Options; + + /** + * Sets whether to connect to an already-running instead of the specified + * {@linkplain #androidProcess app} instead of launching the app with a clean + * data directory. + * + * @param {boolean} useRunning Whether to connect to a running instance. + * @return {!Options} A self reference. + */ + androidUseRunningApp(useRunning: boolean): Options; + + /** + * Sets the path to Chrome's log file. This path should exist on the machine + * that will launch Chrome. + * @param {string} path Path to the log file to use. + * @return {!Options} A self reference. + */ + setChromeLogFile(path: string): Options; + + /** + * Sets the directory to store Chrome minidumps in. This option is only + * supported when ChromeDriver is running on Linux. + * @param {string} path The directory path. + * @return {!Options} A self reference. + */ + setChromeMinidumpPath(path: string): Options; + + /** + * Configures Chrome to emulate a mobile device. For more information, refer + * to the ChromeDriver project page on [mobile emulation][em]. Configuration + * options include: + * + * - `deviceName`: The name of a pre-configured [emulated device][devem] + * - `width`: screen width, in pixels + * - `height`: screen height, in pixels + * - `pixelRatio`: screen pixel ratio + * + * __Example 1: Using a Pre-configured Device__ + * + * let options = new chrome.Options().setMobileEmulation( + * {deviceName: 'Google Nexus 5'}); + * + * let driver = new chrome.Driver(options); + * + * __Example 2: Using Custom Screen Configuration__ + * + * let options = new chrome.Options().setMobileEmulation({ + * width: 360, + * height: 640, + * pixelRatio: 3.0 + * }); + * + * let driver = new chrome.Driver(options); + * + * + * [em]: https://sites.google.com/a/chromium.org/chromedriver/mobile-emulation + * [devem]: https://developer.chrome.com/devtools/docs/device-mode + * + * @param {?({deviceName: string}| + * {width: number, height: number, pixelRatio: number})} config The + * mobile emulation configuration, or `null` to disable emulation. + * @return {!Options} A self reference. + */ + setMobileEmulation(config: any): Options; +} + +/** + * Creates {@link remote.DriverService} instances that manage a ChromeDriver + * server. + */ +export class ServiceBuilder extends remote.DriverService.Builder { + /** + * @param {string=} opt_exe Path to the server executable to use. If omitted, + * the builder will attempt to locate the chromedriver on the current + * PATH. + * @throws {Error} If provided executable does not exist, or the chromedriver + * cannot be found on the PATH. + * @constructor + */ + constructor(opt_exe?: string); + + /** + * Sets which port adb is listening to. _The ChromeDriver will connect to adb + * if an {@linkplain Options#androidPackage Android session} is requested, but + * adb **must** be started beforehand._ + * + * @param {number} port Which port adb is running on. + * @return {!ServiceBuilder} A self reference. + */ + setAdbPort(port: number): this; + + /** + * Sets the path of the log file the driver should log to. If a log file is + * not specified, the driver will log to stderr. + * @param {string} path Path of the log file to use. + * @return {!ServiceBuilder} A self reference. + */ + loggingTo(path: string): this; + + /** + * Enables verbose logging. + * @return {!ServiceBuilder} A self reference. + */ + enableVerboseLogging(): this; + + /** + * Sets the number of threads the driver should use to manage HTTP requests. + * By default, the driver will use 4 threads. + * @param {number} n The number of threads to use. + * @return {!ServiceBuilder} A self reference. + */ + setNumHttpThreads(n: number): this; +} + +/** + * Returns the default ChromeDriver service. If such a service has not been + * configured, one will be constructed using the default configuration for + * a ChromeDriver executable found on the system PATH. + * @return {!remote.DriverService} The default ChromeDriver service. + */ +export function getDefaultService(): remote.DriverService; + +/** + * Sets the default service to use for new ChromeDriver instances. + * @param {!remote.DriverService} service The service to use. + * @throws {Error} If the default service is currently running. + */ +export function setDefaultService(service: remote.DriverService): void; diff --git a/lib/selenium-webdriver/edge.d.ts b/lib/selenium-webdriver/edge.d.ts new file mode 100644 index 000000000..508c99721 --- /dev/null +++ b/lib/selenium-webdriver/edge.d.ts @@ -0,0 +1,74 @@ +import * as webdriver from './index'; +import * as remote from './remote'; + +export class Driver extends webdriver.WebDriver { + /** + * Creates a new browser session for Microsoft's Edge browser. + * + * @param {(capabilities.Capabilities|Options)=} opt_config The configuration + * options. + * @param {remote.DriverService=} opt_service The session to use; will use + * the {@linkplain #getDefaultService default service} by default. + * @return {!Driver} A new driver instance. + */ + static createSession( + opt_config?: webdriver.CreateSessionCapabilities, opt_service?: remote.DriverService): Driver; + + /** + * This function is a no-op as file detectors are not supported by this + * implementation. + * @override + */ + setFileDetector(): void; +} + +/** + * Class for managing MicrosoftEdgeDriver specific options. + */ +export class Options extends webdriver.Capabilities { + /** + * Sets the proxy settings for the new session. + * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. + * @return {!Options} A self reference. + */ + setProxy(proxy: webdriver.ProxyConfig): Options; + + /** + * Sets the page load strategy for Edge. + * Supported values are 'normal', 'eager', and 'none'; + * + * @param {string} pageLoadStrategy The page load strategy to use. + * @return {!Options} A self reference. + */ + setPageLoadStrategy(pageLoadStrategy: string): Options; +} + +/** + * Creates {@link remote.DriverService} instances that manage a + * MicrosoftEdgeDriver server in a child process. + */ +export class ServiceBuilder extends remote.DriverService.Builder { + /** + * @param {string=} opt_exe Path to the server executable to use. If omitted, + * the builder will attempt to locate the MicrosoftEdgeDriver on the current + * PATH. + * @throws {Error} If provided executable does not exist, or the + * MicrosoftEdgeDriver cannot be found on the PATH. + */ + constructor(opt_exe?: string); +} + +/** + * Returns the default MicrosoftEdgeDriver service. If such a service has + * not been configured, one will be constructed using the default configuration + * for an MicrosoftEdgeDriver executable found on the system PATH. + * @return {!remote.DriverService} The default MicrosoftEdgeDriver service. + */ +export function getDefaultService(): remote.DriverService; + +/** + * Sets the default service to use for new MicrosoftEdgeDriver instances. + * @param {!remote.DriverService} service The service to use. + * @throws {Error} If the default service is currently running. + */ +export function setDefaultService(service: remote.DriverService): void; diff --git a/lib/selenium-webdriver/firefox.d.ts b/lib/selenium-webdriver/firefox.d.ts new file mode 100644 index 000000000..e9f96ee13 --- /dev/null +++ b/lib/selenium-webdriver/firefox.d.ts @@ -0,0 +1,136 @@ +import * as http from './http'; +import * as webdriver from './index'; +import * as remote from './remote'; + + + +/** + * Configuration options for the FirefoxDriver. + */ +export class Options extends webdriver.Capabilities { + /** + * Sets the profile to use. The profile may be specified as a + * {@link Profile} object or as the path to an existing Firefox profile to use + * as a template. + * + * @param {(string|!Profile)} profile The profile to use. + * @return {!Options} A self reference. + */ + setProfile(profile: string): Options; + + /** + * Sets the binary to use. The binary may be specified as the path to a + * Firefox executable, or as a {@link Binary} object. + * + * @param {(string|!Binary)} binary The binary to use. + * @return {!Options} A self reference. + */ + setBinary(binary: string|any): Options; + + /** + * Sets the proxy to use. + * + * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. + * @return {!Options} A self reference. + */ + setProxy(proxy: webdriver.ProxyConfig): Options; + + /** + * Sets whether to use Mozilla's geckodriver to drive the browser. This option + * is enabled by default and required for Firefox 47+. + * + * @param {boolean} enable Whether to enable the geckodriver. + * @see https://github.com/mozilla/geckodriver + */ + useGeckoDriver(enable: boolean): Options; +} + +/** + * @return {string} . + * @throws {Error} + */ +export function findWires(): string; + +/** + * @param {(string|!Binary)} binary . + * @return {!remote.DriverService} . + */ +export function createWiresService(binary: string|any): remote.DriverService; + +/** + * @param {(Profile|string)} profile The profile to prepare. + * @param {number} port The port the FirefoxDriver should listen on. + * @return {!Promise} a promise for the path to the profile directory. + */ +export function prepareProfile(profile: string|any, port: number): any; + +/** + * A WebDriver client for Firefox. + */ +export class Driver extends webdriver.WebDriver { + /** + * Creates a new Firefox session. + * + * @param {(Options|capabilities.Capabilities|Object)=} opt_config The + * configuration options for this driver, specified as either an + * {@link Options} or {@link capabilities.Capabilities}, or as a raw hash + * object. + * @param {(http.Executor|remote.DriverService)=} opt_executor Either a + * pre-configured command executor to use for communicating with an + * externally managed remote end (which is assumed to already be running), + * or the `DriverService` to use to start the geckodriver in a child + * process. + * + * If an executor is provided, care should e taken not to use reuse it with + * other clients as its internal command mappings will be updated to support + * Firefox-specific commands. + * + * _This parameter may only be used with Mozilla's GeckoDriver._ + * @throws {Error} If a custom command executor is provided and the driver is + * configured to use the legacy FirefoxDriver from the Selenium project. + * @return {!Driver} A new driver instance. + */ + static createSession( + opt_config?: Options|webdriver.Capabilities, + opt_executor?: http.Executor|remote.DriverService): Driver; + + /** + * This function is a no-op as file detectors are not supported by this + * implementation. + * @override + */ + setFileDetector(): void; +} + +/** + * Creates {@link selenium-webdriver/remote.DriverService} instances that manage + * a [geckodriver](https://github.com/mozilla/geckodriver) server in a child + * process. + */ +export class ServiceBuilder extends remote.DriverService.Builder { + /** + * @param {string=} opt_exe Path to the server executable to use. If omitted, + * the builder will attempt to locate the geckodriver on the system PATH. + */ + constructor(opt_exe?: string); + + /** + * Enables verbose logging. + * + * @param {boolean=} opt_trace Whether to enable trace-level logging. By + * default, only debug logging is enabled. + * @return {!ServiceBuilder} A self reference. + */ + enableVerboseLogging(opt_trace?: boolean): this; + + /** + * Sets the path to the executable Firefox binary that the geckodriver should + * use. If this method is not called, this builder will attempt to locate + * Firefox in the default installation location for the current platform. + * + * @param {(string|!Binary)} binary Path to the executable Firefox binary to use. + * @return {!ServiceBuilder} A self reference. + * @see Binary#locate() + */ + setFirefoxBinary(binary: string): this; +} diff --git a/typings/http.d.ts b/lib/selenium-webdriver/http.d.ts similarity index 50% rename from typings/http.d.ts rename to lib/selenium-webdriver/http.d.ts index 72fa1b2c5..bbbe9eb37 100644 --- a/typings/http.d.ts +++ b/lib/selenium-webdriver/http.d.ts @@ -14,15 +14,15 @@ export function headersToString(headers: any): string; * @final */ export class Request { - /** - * @param {string} method The HTTP method to use for the request. - * @param {string} path The path on the server to send the request to. - * @param {Object=} opt_data This request's non-serialized JSON payload data. - */ - constructor(method: string, path: string, opt_data?: Object); + /** + * @param {string} method The HTTP method to use for the request. + * @param {string} path The path on the server to send the request to. + * @param {Object=} opt_data This request's non-serialized JSON payload data. + */ + constructor(method: string, path: string, opt_data?: Object); - /** @override */ - toString(): string; + /** @override */ + toString(): string; } /** @@ -30,16 +30,16 @@ export class Request { * @final */ export class Response { - /** - * @param {number} status The response code. - * @param {!Object} headers The response headers. All header names - * will be converted to lowercase strings for consistent lookups. - * @param {string} body The response body. - */ - constructor(status: number, headers: Object, body: string); + /** + * @param {number} status The response code. + * @param {!Object} headers The response headers. All header names + * will be converted to lowercase strings for consistent lookups. + * @param {string} body The response body. + */ + constructor(status: number, headers: Object, body: string); - /** @override */ - toString(): string; + /** @override */ + toString(): string; } export function post(path: string): any; @@ -51,25 +51,25 @@ export function resource(method: string, path: string): any; * A basic HTTP client used to send messages to a remote end. */ export class HttpClient { - /** - * @param {string} serverUrl URL for the WebDriver server to send commands to. - * @param {http.Agent=} opt_agent The agent to use for each request. - * Defaults to `http.globalAgent`. - * @param {?string=} opt_proxy The proxy to use for the connection to the - * server. Default is to use no proxy. - */ - constructor(serverUrl: string, opt_agent?: any, opt_proxy?: string); + /** + * @param {string} serverUrl URL for the WebDriver server to send commands to. + * @param {http.Agent=} opt_agent The agent to use for each request. + * Defaults to `http.globalAgent`. + * @param {?string=} opt_proxy The proxy to use for the connection to the + * server. Default is to use no proxy. + */ + constructor(serverUrl: string, opt_agent?: any, opt_proxy?: string); - /** - * Sends a request to the server. The client will automatically follow any - * redirects returned by the server, fulfilling the returned promise with the - * final response. - * - * @param {!HttpRequest} httpRequest The request to send. - * @return {!promise.Promise} A promise that will be fulfilled - * with the server's response. - */ - send(httpRequest: Request): webdriver.promise.Promise; + /** + * Sends a request to the server. The client will automatically follow any + * redirects returned by the server, fulfilling the returned promise with + * the final response. + * + * @param {!HttpRequest} httpRequest The request to send. + * @return {!Promise} A promise that will be fulfilled + * with the server's response. + */ + send(httpRequest: Request): Promise; } /** @@ -81,7 +81,8 @@ export class HttpClient { * @param {?string=} opt_data The data to send with the request. * @param {?string=} opt_proxy The proxy server to use for the request. */ -export function sendRequest(options: Object, onOk: any, onError: any, opt_data?: string, opt_proxy?: string): any; +export function sendRequest( + options: Object, onOk: any, onError: any, opt_data?: string, opt_proxy?: string): any; /** * A command executor that communicates with the server using HTTP + JSON. @@ -97,30 +98,30 @@ export function sendRequest(options: Object, onOk: any, onError: any, opt_data?: * @implements {cmd.Executor} */ export class Executor { - /** - * @param {!(HttpClient|IThenable)} client The client to use for sending - * requests to the server, or a promise-like object that will resolve to - * to the client. - */ - constructor(client: HttpClient | webdriver.promise.IThenable); + /** + * @param {!(HttpClient|IThenable)} client The client to use for sending + * requests to the server, or a promise-like object that will resolve to + * to the client. + */ + constructor(client: HttpClient|Promise); - /** - * Defines a new command for use with this executor. When a command is sent, - * the {@code path} will be preprocessed using the command's parameters; any - * path segments prefixed with ':' will be replaced by the parameter of the - * same name. For example, given '/person/:name' and the parameters - * '{name: 'Bob'}', the final command path will be '/person/Bob'. - * - * @param {string} name The command name. - * @param {string} method The HTTP method to use when sending this command. - * @param {string} path The path to send the command to, relative to - * the WebDriver server's command root and of the form - * '/path/:variable/segment'. - */ - defineCommand(name: string, method: string, path: string): void; + /** + * Defines a new command for use with this executor. When a command is sent, + * the {@code path} will be preprocessed using the command's parameters; any + * path segments prefixed with ':' will be replaced by the parameter of the + * same name. For example, given '/person/:name' and the parameters + * '{name: 'Bob'}', the final command path will be '/person/Bob'. + * + * @param {string} name The command name. + * @param {string} method The HTTP method to use when sending this command. + * @param {string} path The path to send the command to, relative to + * the WebDriver server's command root and of the form + * '/path/:variable/segment'. + */ + defineCommand(name: string, method: string, path: string): void; - /** @override */ - execute(command: any): any; + /** @override */ + execute(command: any): any; } /** diff --git a/lib/selenium-webdriver/ie.d.ts b/lib/selenium-webdriver/ie.d.ts new file mode 100644 index 000000000..53aa26f67 --- /dev/null +++ b/lib/selenium-webdriver/ie.d.ts @@ -0,0 +1,192 @@ +import * as webdriver from './index'; + +/** + * A WebDriver client for Microsoft's Internet Explorer. + */ +export class Driver extends webdriver.WebDriver { + /** + * Creates a new session for Microsoft's Internet Explorer. + * + * @param {(capabilities.Capabilities|Options)=} opt_config The configuration + * options. + * @return {!Driver} A new driver instance. + */ + static createSession(opt_config?: webdriver.Capabilities|Options): Driver; + + /** + * This function is a no-op as file detectors are not supported by this + * implementation. + * @override + */ + setFileDetector(): void; +} + +/** + * Class for managing IEDriver specific options. + */ +export class Options extends webdriver.Capabilities { + constructor(); + + + /** + * Whether to disable the protected mode settings check when the session is + * created. Disbling this setting may lead to significant instability as the + * browser may become unresponsive/hang. Only 'best effort' support is + * provided when using this capability. + * + * For more information, refer to the IEDriver's + * [required system configuration](http://goo.gl/eH0Yi3). + * + * @param {boolean} ignoreSettings Whether to ignore protected mode settings. + * @return {!Options} A self reference. + */ + introduceFlakinessByIgnoringProtectedModeSettings(ignoreSettings: boolean): Options; + + /** + * Indicates whether to skip the check that the browser's zoom level is set to + * 100%. + * + * @param {boolean} ignore Whether to ignore the browser's zoom level + * settings. + * @return {!Options} A self reference. + */ + ignoreZoomSetting(ignore: boolean): Options; + + /** + * Sets the initial URL loaded when IE starts. This is intended to be used + * with + * {@link #ignoreProtectedModeSettings} to allow the user to initialize IE in + * the proper Protected Mode zone. Setting this option may cause browser + * instability or flaky and unresponsive code. Only 'best effort' support is + * provided when using this option. + * + * @param {string} url The initial browser URL. + * @return {!Options} A self reference. + */ + initialBrowserUrl(url: string): Options; + + /** + * Configures whether to enable persistent mouse hovering (true by default). + * Persistent hovering is achieved by continuously firing mouse over events at + * the last location the mouse cursor has been moved to. + * + * @param {boolean} enable Whether to enable persistent hovering. + * @return {!Options} A self reference. + */ + enablePersistentHover(enable: boolean): Options; + + /** + * Configures whether the driver should attempt to remove obsolete + * {@linkplain webdriver.WebElement WebElements} from its internal cache on + * page navigation (true by default). Disabling this option will cause the + * driver to run with a larger memory footprint. + * + * @param {boolean} enable Whether to enable element reference cleanup. + * @return {!Options} A self reference. + */ + enableElementCacheCleanup(enable: boolean): Options; + + /** + * Configures whether to require the IE window to have input focus before + * performing any user interactions (i.e. mouse or keyboard events). This + * option is disabled by default, but delivers much more accurate interaction + * events when enabled. + * + * @param {boolean} require Whether to require window focus. + * @return {!Options} A self reference. + */ + requireWindowFocus(require: boolean): Options; + + /** + * Configures the timeout, in milliseconds, that the driver will attempt to + * located and attach to a newly opened instance of Internet Explorer. The + * default is zero, which indicates waiting indefinitely. + * + * @param {number} timeout How long to wait for IE. + * @return {!Options} A self reference. + */ + browserAttachTimeout(timeout: number): Options; + + /** + * Configures whether to launch Internet Explorer using the CreateProcess API. + * If this option is not specified, IE is launched using IELaunchURL, if + * available. For IE 8 and above, this option requires the TabProcGrowth + * registry value to be set to 0. + * + * @param {boolean} force Whether to use the CreateProcess API. + * @return {!Options} A self reference. + */ + forceCreateProcessApi(force: boolean): Options; + + /** + * Specifies command-line switches to use when launching Internet Explorer. + * This is only valid when used with {@link #forceCreateProcessApi}. + * + * @param {...(string|!Array.)} var_args The arguments to add. + * @return {!Options} A self reference. + */ + addArguments(...var_args: string[]): Options; + + /** + * Configures whether proxies should be configured on a per-process basis. If + * not set, setting a {@linkplain #setProxy proxy} will configure the system + * proxy. The default behavior is to use the system proxy. + * + * @param {boolean} enable Whether to enable per-process proxy settings. + * @return {!Options} A self reference. + */ + usePerProcessProxy(enable: boolean): Options; + + /** + * Configures whether to clear the cache, cookies, history, and saved form + * data before starting the browser. _Using this capability will clear session + * data for all running instances of Internet Explorer, including those + * started manually._ + * + * @param {boolean} cleanSession Whether to clear all session data on startup. + * @return {!Options} A self reference. + */ + ensureCleanSession(cleanSession: boolean): Options; + + /** + * Sets the path to the log file the driver should log to. + * @param {string} file The log file path. + * @return {!Options} A self reference. + */ + setLogFile(file: string): Options; + + /** + * Sets the IEDriverServer's logging {@linkplain Level level}. + * @param {Level} level The logging level. + * @return {!Options} A self reference. + */ + setLogLevel(level: webdriver.logging.Level): Options; + + /** + * Sets the IP address of the driver's host adapter. + * @param {string} host The IP address to use. + * @return {!Options} A self reference. + */ + setHost(host: string): Options; + + /** + * Sets the path of the temporary data directory to use. + * @param {string} path The log file path. + * @return {!Options} A self reference. + */ + setExtractPath(path: string): Options; + + /** + * Sets whether the driver should start in silent mode. + * @param {boolean} silent Whether to run in silent mode. + * @return {!Options} A self reference. + */ + silent(silent: boolean): Options; + + /** + * Sets the proxy settings for the new session. + * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. + * @return {!Options} A self reference. + */ + setProxy(proxy: webdriver.ProxyConfig): Options; +} diff --git a/typings/index.d.ts b/lib/selenium-webdriver/index.d.ts similarity index 53% rename from typings/index.d.ts rename to lib/selenium-webdriver/index.d.ts index d2cf50da1..f77eccfe6 100644 --- a/typings/index.d.ts +++ b/lib/selenium-webdriver/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for Selenium WebDriverJS 3.0 +// Type definitions for Selenium WebDriverJS 4.0 // Project: https://github.com/SeleniumHQ/selenium/tree/master/javascript/node/selenium-webdriver // Definitions by: Bill Armstrong , // Yuki Kokubun , @@ -8,22 +8,32 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.3 +// tslint:disable:variable-name 3rd party +// tslint:disable:interface-name 3rd party + import * as chrome from './chrome'; import * as edge from './edge'; import * as firefox from './firefox'; import * as ie from './ie'; -import * as opera from './opera'; +import {By, ByHash} from './lib/by'; +import {Command, ICommandName, Name} from './lib/command'; +import {Actions, Button, Key, Origin} from './lib/input'; +import {promise} from './lib/promise'; +import * as until from './lib/until'; import * as safari from './safari'; -// google3 local modification: -// Add namespace webdriver in the global namespace for backwards compatibility. -declare global { -namespace webdriver { -// end google3 local modification. +export {By, ByHash} from './lib/by'; +export {Actions, Button, Key, Origin} from './lib/input'; +export {promise} from './lib/promise'; +export {until as until}; +/** + * Typings for lib/error + */ export namespace error { class IError extends Error { - constructor(opt_error?: string); + constructor(message?: string); + message: string; } /** @@ -31,33 +41,52 @@ export namespace error { * more appropriate category is not defined for the offending error. */ class WebDriverError extends IError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); + remoteStacktrace?: string; + } + + + /** + * Indicates a {@linkplain ./webdriver.WebElement#click click command} could + * not completed because the click target is obscured by other elements on the + * page. + */ + class ElementClickInterceptedError extends WebDriverError { + constructor(message?: string); } /** * An attempt was made to select an element that cannot be selected. */ class ElementNotSelectableError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); + } + + + /** + * Indicates a command could not be completed because the target element is + * not pointer or keyboard interactable. This will often occur if an element + * is present in the DOM, but not rendered (i.e. its CSS style has + * "display: none"). + */ + + class ElementNotInteractableError extends WebDriverError { + constructor(message?: string); } /** - * An element command could not be completed because the element is not visible - * on the page. + * Indicates a navigation event caused the browser to generate a certificate + * warning. This is usually caused by an expired or invalid TLS certificate. */ - class ElementNotVisibleError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + class InsecureCertificateError extends WebDriverError { + constructor(message?: string); } /** * The arguments passed to a command are either invalid or malformed. */ class InvalidArgumentError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** @@ -65,67 +94,67 @@ export namespace error { * the current page. */ class InvalidCookieDomainError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * The coordinates provided to an interactions operation are invalid. */ - class InvalidElementCoordinatesError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + class InvalidCoordinatesError extends WebDriverError { + constructor(message?: string); } /** * An element command could not be completed because the element is in an - * invalid state, e.g. attempting to click an element that is no longer attached - * to the document. + * invalid state, e.g. attempting to click an element that is no longer + * attached to the document. */ class InvalidElementStateError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * Argument was an invalid selector. */ class InvalidSelectorError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * Occurs when a command is directed to a session that does not exist. */ class NoSuchSessionError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * An error occurred while executing JavaScript supplied by the user. */ class JavascriptError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** - * The target for mouse interaction is not in the browser’s viewport and cannot - * be brought into that viewport. + * The target for mouse interaction is not in the browser’s viewport and + * cannot be brought into that viewport. */ class MoveTargetOutOfBoundsError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * An attempt was made to operate on a modal dialog when one was not open. */ class NoSuchAlertError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); + } + + /** + * Indicates a named cookie could not be found in the cookie jar for the + * currently selected document. + */ + class NoSuchCookieError extends WebDriverError { + constructor(message?: string); } /** @@ -133,8 +162,7 @@ export namespace error { * parameters. */ class NoSuchElementError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** @@ -142,8 +170,7 @@ export namespace error { * could not be found. */ class NoSuchFrameError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** @@ -151,24 +178,21 @@ export namespace error { * could not be found. */ class NoSuchWindowError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * A script did not complete before its timeout expired. */ class ScriptTimeoutError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * A new session could not be created. */ class SessionNotCreatedError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** @@ -176,44 +200,35 @@ export namespace error { * attached to the DOM. */ class StaleElementReferenceError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * An operation did not completErrorCodee before its timeout expired. */ class TimeoutError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * A request to set a cookie’s value could not be satisfied. */ class UnableToSetCookieError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * A screen capture operation was not possible. */ class UnableToCaptureScreenError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * A modal dialog was open, blocking this operation. */ class UnexpectedAlertOpenError extends WebDriverError { - /** - * @param {string=} opt_error the error message, if any. - * @param {string=} opt_text the text of the open dialog, if available. - */ - constructor(opt_error?: string, opt_text?: string); - + constructor(message?: string, openAlertText?: string); /** * @return {(string|undefined)} The text displayed with the unhandled alert, * if available. @@ -225,8 +240,7 @@ export namespace error { * A command could not be executed because the remote end is not aware of it. */ class UnknownCommandError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** @@ -234,27 +248,76 @@ export namespace error { * that URL. */ class UnknownMethodError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); } /** * Reports an unsupport operation. */ class UnsupportedOperationError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + constructor(message?: string); + } + + interface Response { + error: string|number; + message: string; + } + /** + * Checks a response object from a server that adheres to the W3C WebDriver + * protocol. + */ + function checkResponse(data: Response): Response; + + interface MaybeLegacyResponse { + status?: number; + value?: {message: string}; + message?: string; + getAlertText?(): string; + } + + + /** + * Checks a legacy response from the Selenium 2.0 wire protocol for an error. + */ + function checkLegacyResponse(response: MaybeLegacyResponse): MaybeLegacyResponse; + + interface ErrorData { + error: string|number; + message: string; + [key: string]: string|number; + } + + /** + * Throws an error coded from the W3C protocol. A generic error will be thrown + * if the provided `data` is not a valid encoded error. + */ + function throwDecodedError(data: ErrorData|string): never; + + interface ErrorCodeType { + [key: string]: number; } + + const ErrorCode: ErrorCodeType; + + /** + * Lookup the err in table of errors. + */ + // tslint:disable-next-line:no-any Runtime type testing. + function encodeError(err: any): {error: string, message: string}; } + +/** + * Typings for lib/logging.js + */ export namespace logging { /** * A hash describing log preferences. * @typedef {Object.} */ class Preferences { - setLevel(type: string, level: Level | string | number): void; - toJSON(): { [key: string]: string }; + setLevel(type: string, level: Level|string|number): void; + toJSON(): {[key: string]: string}; } interface IType { @@ -354,7 +417,7 @@ export namespace logging { * convert . * @return {!logging.Level} The converted level. */ - function getLevel(nameOrValue: string | number): Level; + function getLevel(nameOrValue: string|number): Level; interface IEntryJSON { level: string; @@ -376,7 +439,9 @@ export namespace logging { * @param {string=} opt_type The log type, if known. * @constructor */ - constructor(level: Level | string | number, message: string, opt_timestamp?: number, opt_type?: string | IType); + constructor( + level: Level|string|number, message: string, opt_timestamp?: number, + opt_type?: string|IType); /** @type {!logging.Level} */ level: Level; @@ -399,8 +464,8 @@ export namespace logging { /** * An object used to log debugging messages. Loggers use a hierarchical, - * dot-separated naming scheme. For instance, 'foo' is considered the parent of - * the 'foo.bar' and an ancestor of 'foo.bar.baz'. + * dot-separated naming scheme. For instance, 'foo' is considered the parent + * of the 'foo.bar' and an ancestor of 'foo.bar.baz'. * * Each logger may be assigned a {@linkplain #setLevel log level}, which * controls which level of messages will be reported to the @@ -427,14 +492,14 @@ export namespace logging { /** @private {Logger} */ parent_: Logger; /** @private {Set} */ - handlers_: any; + handlers_: Set<(entry: Entry) => void>; /** @return {string} the name of this logger. */ getName(): string; /** - * @param {Level} level the new level for this logger, or `null` if the logger - * should inherit its level from its parent logger. + * @param {Level} level the new level for this logger, or `null` if the + * logger should inherit its level from its parent logger. */ setLevel(level: Level): void; @@ -448,18 +513,18 @@ export namespace logging { /** * @param {!Level} level the level to check. - * @return {boolean} whether messages recorded at the given level are loggable - * by this instance. + * @return {boolean} whether messages recorded at the given level are + * loggable by this instance. */ isLoggable(level: Level): boolean; /** - * Adds a handler to this logger. The handler will be invoked for each message - * logged with this instance, or any of its descendants. + * Adds a handler to this logger. The handler will be invoked for each + * message logged with this instance, or any of its descendants. * * @param {function(!Entry)} handler the handler to add. */ - addHandler(handler: any): void; + addHandler(handler: (entry: Entry) => void): void; /** * Removes a handler from this logger. @@ -467,7 +532,7 @@ export namespace logging { * @param {function(!Entry)} handler the handler to remove. * @return {boolean} whether a handler was successfully removed. */ - removeHandler(handler: any): void; + removeHandler(handler: (entry: Entry) => void): void; /** * Logs a message at the given level. The message may be defined as a string @@ -480,56 +545,56 @@ export namespace logging { * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - log(level: Level, loggable: string | Function): void; + log(level: Level, loggable: string|Function): void; /** * Logs a message at the {@link Level.SEVERE} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - severe(loggable: string | Function): void; + severe(loggable: string|Function): void; /** * Logs a message at the {@link Level.WARNING} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - warning(loggable: string | Function): void; + warning(loggable: string|Function): void; /** * Logs a message at the {@link Level.INFO} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - info(loggable: string | Function): void; + info(loggable: string|Function): void; /** * Logs a message at the {@link Level.DEBUG} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - debug(loggable: string | Function): void; + debug(loggable: string|Function): void; /** * Logs a message at the {@link Level.FINE} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - fine(loggable: string | Function): void; + fine(loggable: string|Function): void; /** * Logs a message at the {@link Level.FINER} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - finer(loggable: string | Function): void; + finer(loggable: string|Function): void; /** * Logs a message at the {@link Level.FINEST} log level. * @param {(string|function(): string)} loggable the message to log, or a * function that will return the message. */ - finest(loggable: string | Function): void; + finest(loggable: string|Function): void; } /** @@ -558,695 +623,11 @@ export namespace logging { */ createLogger_(name: string, parent: Logger): Logger; } -} - -export namespace promise { - // region Functions - - /** - * Set `USE_PROMISE_MANAGER` to `false` to disable the promise manager. - * This is useful, if you use async/await (see https://github.com/SeleniumHQ/selenium/issues/2969 - * and https://github.com/SeleniumHQ/selenium/issues/3037). - */ - let USE_PROMISE_MANAGER: boolean; - - /** - * Given an array of promises, will return a promise that will be fulfilled - * with the fulfillment values of the input array's values. If any of the - * input array's promises are rejected, the returned promise will be rejected - * with the same reason. - * - * @param {!Array<(T|!ManagedPromise)>} arr An array of - * promises to wait on. - * @return {!ManagedPromise} A promise that is - * fulfilled with an array containing the fulfilled values of the - * input array, or rejected with the same reason as the first - * rejected value. - * @template T - */ - function all(arr: Array>): Promise; - - /** - * Invokes the appropriate callback function as soon as a promised - * {@code value} is resolved. This function is similar to - * {@link promise.when}, except it does not return a new promise. - * @param {*} value The value to observe. - * @param {Function} callback The function to call when the value is - * resolved successfully. - * @param {Function=} opt_errback The function to call when the value is - * rejected. - */ - function asap(value: any, callback: Function, opt_errback?: Function): void; - - /** - * @return {!promise.ControlFlow} The currently active control flow. - */ - function controlFlow(): ControlFlow; - - /** - * Creates a new control flow. The provided callback will be invoked as the - * first task within the new flow, with the flow as its sole argument. Returns - * a promise that resolves to the callback result. - * @param {function(!ControlFlow)} callback The entry point - * to the newly created flow. - * @return {!ManagedPromise} A promise that resolves to the callback - * result. - */ - function createFlow(callback: (flow: ControlFlow) => R): Promise; - - /** - * Determines whether a {@code value} should be treated as a promise. - * Any object whose 'then' property is a function will be considered a promise. - * - * @param {*} value The value to test. - * @return {boolean} Whether the value is a promise. - */ - function isPromise(value: any): boolean; - - /** - * Tests is a function is a generator. - * @param {!Function} fn The function to test. - * @return {boolean} Whether the function is a generator. - */ - function isGenerator(fn: Function): boolean; - - /** - * Creates a promise that will be resolved at a set time in the future. - * @param {number} ms The amount of time, in milliseconds, to wait before - * resolving the promise. - * @return {!ManagedPromise} The promise. - */ - function delayed(ms: number): Promise; - - /** - * Calls a function for each element in an array, and if the function returns - * true adds the element to a new array. - * - * If the return value of the filter function is a promise, this function - * will wait for it to be fulfilled before determining whether to insert the - * element into the new array. - * - * If the filter function throws or returns a rejected promise, the promise - * returned by this function will be rejected with the same reason. Only the - * first failure will be reported; all subsequent errors will be silently - * ignored. - * - * @param {!(Array|ManagedPromise>)} arr The - * array to iterator over, or a promise that will resolve to said array. - * @param {function(this: SELF, TYPE, number, !Array): ( - * boolean|ManagedPromise)} fn The function - * to call for each element in the array. - * @param {SELF=} opt_self The object to be used as the value of 'this' within - * {@code fn}. - * @template TYPE, SELF - */ - function filter(arr: T[] | Promise, fn: (element: T, type: any, index: number, array: T[]) => any, opt_self?: any): Promise; - - /** - * Creates a new deferred object. - * @return {!promise.Deferred} The new deferred object. - */ - function defer(): Deferred; - - /** - * Creates a promise that has been resolved with the given value. - * @param {T=} opt_value The resolved value. - * @return {!Promise} The resolved promise. - * @deprecated Use {@link Promise#resolve Promise.resolve(value)}. - * @template T - */ - function fulfilled(opt_value?: T): Promise; - - /** - * Calls a function for each element in an array and inserts the result into a - * new array, which is used as the fulfillment value of the promise returned - * by this function. - * - * If the return value of the mapping function is a promise, this function - * will wait for it to be fulfilled before inserting it into the new array. - * - * If the mapping function throws or returns a rejected promise, the - * promise returned by this function will be rejected with the same reason. - * Only the first failure will be reported; all subsequent errors will be - * silently ignored. - * - * @param {!(Array|ManagedPromise>)} arr The - * array to iterator over, or a promise that will resolve to said array. - * @param {function(this: SELF, TYPE, number, !Array): ?} fn The - * function to call for each element in the array. This function should - * expect three arguments (the element, the index, and the array itself. - * @param {SELF=} opt_self The object to be used as the value of 'this' within - * {@code fn}. - * @template TYPE, SELF - */ - function map(arr: T[] | Promise, fn: (self: any, type: any, index: number, array: T[]) => any, opt_self?: any): Promise; - - /** - * Creates a promise that has been rejected with the given reason. - * @param {*=} opt_reason The rejection reason; may be any value, but is - * usually an Error or a string. - * @return {!Promise} The rejected promise. - * @deprecated Use {@link Promise#reject Promise.Promise(reason)}. - */ - function rejected(opt_reason?: any): Promise; - - /** - * Wraps a function that expects a node-style callback as its final - * argument. This callback expects two arguments: an error value (which will be - * null if the call succeeded), and the success value as the second argument. - * The callback will the resolve or reject the returned promise, based on its - * arguments. - * @param {!Function} fn The function to wrap. - * @param {...?} var_args The arguments to apply to the function, excluding the - * final callback. - * @return {!ManagedPromise} A promise that will be resolved with the - * result of the provided function's callback. - */ - function checkedNodeCall(fn: Function, ...var_args: any[]): Promise; - - /** - * Consumes a {@code GeneratorFunction}. Each time the generator yields a - * promise, this function will wait for it to be fulfilled before feeding the - * fulfilled value back into {@code next}. Likewise, if a yielded promise is - * rejected, the rejection error will be passed to {@code throw}. - * - * __Example 1:__ the Fibonacci Sequence. - * - * promise.consume(function* fibonacci() { - * var n1 = 1, n2 = 1; - * for (var i = 0; i < 4; ++i) { - * var tmp = yield n1 + n2; - * n1 = n2; - * n2 = tmp; - * } - * return n1 + n2; - * }).then(function(result) { - * console.log(result); // 13 - * }); - * - * __Example 2:__ a generator that throws. - * - * promise.consume(function* () { - * yield promise.delayed(250).then(function() { - * throw Error('boom'); - * }); - * }).catch(function(e) { - * console.log(e.toString()); // Error: boom - * }); - * - * @param {!Function} generatorFn The generator function to execute. - * @param {Object=} opt_self The object to use as 'this' when invoking the - * initial generator. - * @param {...*} var_args Any arguments to pass to the initial generator. - * @return {!ManagedPromise} A promise that will resolve to the - * generator's final result. - * @throws {TypeError} If the given function is not a generator. - */ - function consume(generatorFn: Function, opt_self?: any, ...var_args: any[]): Promise; - - /** - * Registers an observer on a promised {@code value}, returning a new promise - * that will be resolved when the value is. If {@code value} is not a promise, - * then the return promise will be immediately resolved. - * @param {*} value The value to observe. - * @param {Function=} opt_callback The function to call when the value is - * resolved successfully. - * @param {Function=} opt_errback The function to call when the value is - * rejected. - * @return {!ManagedPromise} A new promise. - */ - function when(value: T | Promise, opt_callback?: (value: T) => any, opt_errback?: (error: any) => any): Promise; - - /** - * Returns a promise that will be resolved with the input value in a - * fully-resolved state. If the value is an array, each element will be fully - * resolved. Likewise, if the value is an object, all keys will be fully - * resolved. In both cases, all nested arrays and objects will also be - * fully resolved. All fields are resolved in place; the returned promise will - * resolve on {@code value} and not a copy. - * - * Warning: This function makes no checks against objects that contain - * cyclical references: - * - * var value = {}; - * value['self'] = value; - * promise.fullyResolved(value); // Stack overflow. - * - * @param {*} value The value to fully resolve. - * @return {!ManagedPromise} A promise for a fully resolved version - * of the input value. - */ - function fullyResolved(value: any): Promise; - - /** - * Changes the default flow to use when no others are active. - * @param {!ControlFlow} flow The new default flow. - * @throws {Error} If the default flow is not currently active. - */ - function setDefaultFlow(flow: ControlFlow): void; - - // endregion - - /** - * Error used when the computation of a promise is cancelled. - */ - class CancellationError extends Error { - /** - * @param {string=} opt_msg The cancellation message. - */ - constructor(opt_msg?: string); - } - - interface IThenable extends PromiseLike { - /** - * Registers listeners for when this instance is resolved. - * - * @param onfulfilled - * The function to call if this promise is successfully resolved. The function - * should expect a single argument: the promise's resolved value. - * @param onrejected - * The function to call if this promise is rejected. The function should - * expect a single argument: the rejection reason. - * @return A new promise which will be resolved with the result - * of the invoked callback. - * @template R - */ - then( - onfulfilled?: ((value: T) => TResult1 | PromiseLike) | undefined | null, - onrejected?: ((reason: any) => TResult2 | PromiseLike) | undefined | null): PromiseLike; - - /** - * Registers a listener for when this promise is rejected. This is synonymous - * with the {@code catch} clause in a synchronous API: - * - * // Synchronous API: - * try { - * doSynchronousWork(); - * } catch (ex) { - * console.error(ex); - * } - * - * // Asynchronous promise API: - * doAsynchronousWork().catch(function(ex) { - * console.error(ex); - * }); - * - * @param {function(*): (R|IThenable)} errback The - * function to call if this promise is rejected. The function should - * expect a single argument: the rejection reason. - * @return {!ManagedPromise} A new promise which will be - * resolved with the result of the invoked callback. - * @template R - */ - catch(onrejected?: ((reason: any) => TResult | PromiseLike) | undefined | null): Promise; - } - - /** - * Thenable is a promise-like object with a {@code then} method which may be - * used to schedule callbacks on a promised value. - * - * @interface - * @template T - */ - interface Thenable extends IThenable {} - class Thenable { - /** - * Registers a listener to invoke when this promise is resolved, regardless - * of whether the promise's value was successfully computed. This function - * is synonymous with the {@code finally} clause in a synchronous API: - * - * // Synchronous API: - * try { - * doSynchronousWork(); - * } finally { - * cleanUp(); - * } - * - * // Asynchronous promise API: - * doAsynchronousWork().finally(cleanUp); - * - * __Note:__ similar to the {@code finally} clause, if the registered - * callback returns a rejected promise or throws an error, it will silently - * replace the rejection error (if any) from this promise: - * - * try { - * throw Error('one'); - * } finally { - * throw Error('two'); // Hides Error: one - * } - * - * promise.rejected(Error('one')) - * .finally(function() { - * throw Error('two'); // Hides Error: one - * }); - * - * @param {function(): (R|IThenable)} callback The function to call when - * this promise is resolved. - * @return {!ManagedPromise} A promise that will be fulfilled - * with the callback result. - * @template R - */ - finally(callback: Function): Promise; - - /** - * Adds a property to a class prototype to allow runtime checks of whether - * instances of that class implement the Thenable interface. This function - * will also ensure the prototype's {@code then} function is exported from - * compiled code. - * @param {function(new: Thenable, ...?)} ctor The - * constructor whose prototype to modify. - */ - static addImplementation(ctor: Function): void; - - /** - * Checks if an object has been tagged for implementing the Thenable - * interface as defined by {@link Thenable.addImplementation}. - * @param {*} object The object to test. - * @return {boolean} Whether the object is an implementation of the Thenable - * interface. - */ - static isImplementation(object: any): boolean; - } - interface IFulfilledCallback { - (value: T | IThenable | Thenable | undefined): void; - } - - interface IRejectedCallback { - (reason: any): void; - } - - /** - * Represents the eventual value of a completed operation. Each promise may be - * in one of three states: pending, fulfilled, or rejected. Each promise starts - * in the pending state and may make a single transition to either a - * fulfilled or rejected state, at which point the promise is considered - * resolved. - * - * @implements {promise.Thenable} - * @template T - * @see http://promises-aplus.github.io/promises-spec/ - */ - class Promise implements IThenable, PromiseLike { - /** - * @param {function( - * function((T|IThenable|Thenable)=), - * function(*=))} resolver - * Function that is invoked immediately to begin computation of this - * promise's value. The function should accept a pair of callback - * functions, one for fulfilling the promise and another for rejecting it. - * @param {ControlFlow=} opt_flow The control flow - * this instance was created under. Defaults to the currently active flow. - */ - constructor(resolver: (resolve: IFulfilledCallback, reject: IRejectedCallback) => void, opt_flow?: ControlFlow); - - /** - * Creates a promise that is immediately resolved with the given value. - * - * @param {T=} opt_value The value to resolve. - * @return {!ManagedPromise} A promise resolved with the given value. - * @template T - */ - static resolve(opt_value?: T): Promise; - - /** - * Creates a promise that is immediately rejected with the given reason. - * - * @param {*=} opt_reason The rejection reason. - * @return {!ManagedPromise} A new rejected promise. - */ - static reject(opt_reason?: any): Promise; - - /** - * Registers listeners for when this instance is resolved. - * - * @param onfulfilled - * The function to call if this promise is successfully resolved. The function - * should expect a single argument: the promise's resolved value. - * @param onrejected - * The function to call if this promise is rejected. The function should - * expect a single argument: the rejection reason. - * @return A new promise which will be resolved with the result - * of the invoked callback. - */ - then( - onfulfilled?: ((value: T) => TResult1 | PromiseLike) | undefined | null, - onrejected?: ((reason: any) => TResult2 | PromiseLike) | undefined | null): Promise; - - /** - * Registers a listener for when this promise is rejected. This is synonymous - * with the {@code catch} clause in a synchronous API: - * - * // Synchronous API: - * try { - * doSynchronousWork(); - * } catch (ex) { - * console.error(ex); - * } - * - * // Asynchronous promise API: - * doAsynchronousWork().catch(function(ex) { - * console.error(ex); - * }); - * - * @param onrejected - * The function to call if this promise is rejected. The function should - * expect a single argument: the rejection reason. - * @return A new promise which will be resolved with the result of the invoked callback. - */ - catch(onrejected?: ((reason: any) => TResult | PromiseLike) | undefined | null): Promise; - } - - /** - * Represents a value that will be resolved at some point in the future. This - * class represents the protected 'producer' half of a Promise - each Deferred - * has a {@code promise} property that may be returned to consumers for - * registering callbacks, reserving the ability to resolve the deferred to the - * producer. - * - *

If this Deferred is rejected and there are no listeners registered before - * the next turn of the event loop, the rejection will be passed to the - * {@link promise.ControlFlow} as an unhandled failure. - * - */ - class Deferred { - // region Constructors - - /** - * - * @param {promise.ControlFlow=} opt_flow The control flow - * this instance was created under. This should only be provided during - * unit tests. - * @constructor - */ - constructor(opt_flow?: ControlFlow); - - // endregion - - static State_: { - BLOCKED: number; - PENDING: number; - REJECTED: number; - RESOLVED: number; - }; - - // region Properties - - /** - * The consumer promise for this instance. Provides protected access to the - * callback registering functions. - * @type {!promise.Promise} - */ - promise: Promise; - - // endregion - - // region Methods - - /** - * Rejects this promise. If the error is itself a promise, this instance will - * be chained to it and be rejected with the error's resolved value. - * @param {*=} opt_error The rejection reason, typically either a - * {@code Error} or a {@code string}. - */ - reject(opt_error?: any): void; - errback(opt_error?: any): void; - - /** - * Resolves this promise with the given value. If the value is itself a - * promise and not a reference to this deferred, this instance will wait for - * it before resolving. - * @param {*=} opt_value The resolved value. - */ - fulfill(opt_value?: T): void; - - /** - * Removes all of the listeners previously registered on this deferred. - * @throws {Error} If this deferred has already been resolved. - */ - removeAll(): void; - - // endregion - } - - interface IControlFlowTimer { - clearInterval(ms: number): void; - clearTimeout(ms: number): void; - setInterval(fn: Function, ms: number): number; - setTimeout(fn: Function, ms: number): number; - } - - interface IEventType { - /** Emitted when all tasks have been successfully executed. */ - IDLE: string; - - /** Emitted when a ControlFlow has been reset. */ - RESET: string; - - /** Emitted whenever a new task has been scheduled. */ - SCHEDULE_TASK: string; - - /** - * Emitted whenever a control flow aborts due to an unhandled promise - * rejection. This event will be emitted along with the offending rejection - * reason. Upon emitting this event, the control flow will empty its task - * queue and revert to its initial state. - */ - UNCAUGHT_EXCEPTION: string; - } - - /** - * Handles the execution of scheduled tasks, each of which may be an - * asynchronous operation. The control flow will ensure tasks are executed in - * the ordered scheduled, starting each task only once those before it have - * completed. - * - * Each task scheduled within this flow may return a - * {@link promise.Promise} to indicate it is an asynchronous - * operation. The ControlFlow will wait for such promises to be resolved before - * marking the task as completed. - * - * Tasks and each callback registered on a {@link promise.Promise} - * will be run in their own ControlFlow frame. Any tasks scheduled within a - * frame will take priority over previously scheduled tasks. Furthermore, if any - * of the tasks in the frame fail, the remainder of the tasks in that frame will - * be discarded and the failure will be propagated to the user through the - * callback/task's promised result. - * - * Each time a ControlFlow empties its task queue, it will fire an - * {@link promise.ControlFlow.EventType.IDLE IDLE} event. Conversely, - * whenever the flow terminates due to an unhandled error, it will remove all - * remaining tasks in its queue and fire an - * {@link promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION - * UNCAUGHT_EXCEPTION} event. If there are no listeners registered with the - * flow, the error will be rethrown to the global error handler. - * - * @extends {EventEmitter} - * @final - */ - class ControlFlow extends EventEmitter { - /** - * @constructor - */ - constructor(); - - /** - * Events that may be emitted by an {@link promise.ControlFlow}. - * @enum {string} - */ - static EventType: IEventType; - - /** - * Returns a string representation of this control flow, which is its current - * {@link #getSchedule() schedule}, sans task stack traces. - * @return {string} The string representation of this contorl flow. - * @override - */ - toString(): string; - - /** - * Resets this instance, clearing its queue and removing all event listeners. - */ - reset(): void; - - /** - * Generates an annotated string describing the internal state of this control - * flow, including the currently executing as well as pending tasks. If - * {@code opt_includeStackTraces === true}, the string will include the - * stack trace from when each task was scheduled. - * @param {string=} opt_includeStackTraces Whether to include the stack traces - * from when each task was scheduled. Defaults to false. - * @return {string} String representation of this flow's internal state. - */ - getSchedule(opt_includeStackTraces?: boolean): string; - - /** - * Schedules a task for execution. If there is nothing currently in the - * queue, the task will be executed in the next turn of the event loop. If - * the task function is a generator, the task will be executed using - * {@link promise.consume}. - * - * @param {function(): (T|promise.Promise)} fn The function to - * call to start the task. If the function returns a - * {@link promise.Promise}, this instance will wait for it to be - * resolved before starting the next task. - * @param {string=} opt_description A description of the task. - * @return {!promise.Promise} A promise that will be resolved - * with the result of the action. - * @template T - */ - execute(fn: () => (T | Promise), opt_description?: string): Promise; + function getLogger(name: string): Logger; +} - /** - * Inserts a {@code setTimeout} into the command queue. This is equivalent to - * a thread sleep in a synchronous programming language. - * - * @param {number} ms The timeout delay, in milliseconds. - * @param {string=} opt_description A description to accompany the timeout. - * @return {!promise.Promise} A promise that will be resolved with - * the result of the action. - */ - timeout(ms: number, opt_description?: string): Promise; - /** - * Schedules a task that shall wait for a condition to hold. Each condition - * function may return any value, but it will always be evaluated as a boolean. - * - * Condition functions may schedule sub-tasks with this instance, however, - * their execution time will be factored into whether a wait has timed out. - * - * In the event a condition returns a Promise, the polling loop will wait for - * it to be resolved before evaluating whether the condition has been satisfied. - * The resolution time for a promise is factored into whether a wait has timed - * out. - * - * If the condition function throws, or returns a rejected promise, the - * wait task will fail. - * - * If the condition is defined as a promise, the flow will wait for it to - * settle. If the timeout expires before the promise settles, the promise - * returned by this function will be rejected. - * - * If this function is invoked with `timeout === 0`, or the timeout is omitted, - * the flow will wait indefinitely for the condition to be satisfied. - * - * @param {(!promise.Promise|function())} condition The condition to poll, - * or a promise to wait on. - * @param {number=} opt_timeout How long to wait, in milliseconds, for the - * condition to hold before timing out. If omitted, the flow will wait - * indefinitely. - * @param {string=} opt_message An optional error message to include if the - * wait times out; defaults to the empty string. - * @return {!promise.Promise} A promise that will be fulfilled - * when the condition has been satisified. The promise shall be rejected if - * the wait times out waiting for the condition. - * @throws {TypeError} If condition is not a function or promise or if timeout - * is not a number >= 0. - * @template T - */ - wait(condition: Promise | Function, opt_timeout?: number, opt_message?: string): Promise; - } -} /** * Defines a condition for use with WebDriver's WebDriver#wait wait command. @@ -1259,13 +640,13 @@ export class Condition { * evaluate on each iteration of the wait loop. * @constructor */ - constructor(message: string, fn: (webdriver: WebDriver) => any); + constructor(message: string, fn: (webdriver: WebDriver) => T); /** @return {string} A description of this condition. */ description(): string; /** @type {function(!WebDriver): OUT} */ - fn(webdriver: WebDriver): any; + fn(webdriver: WebDriver): T; } /** @@ -1279,523 +660,31 @@ export class WebElementCondition extends Condition { private _nominal: undefined; } -export namespace until { - /** - * Creates a condition that will wait until the input driver is able to switch - * to the designated frame. The target frame may be specified as - * - * 1. a numeric index into - * [window.frames](https://developer.mozilla.org/en-US/docs/Web/API/Window.frames) - * for the currently selected frame. - * 2. a {@link ./WebElement}, which must reference a FRAME or IFRAME - * element on the current page. - * 3. a locator which may be used to first locate a FRAME or IFRAME on the - * current page before attempting to switch to it. - * - * Upon successful resolution of this condition, the driver will be left - * focused on the new frame. - * - * @param {!(number|./WebElement|By| - * function(!./WebDriver): !./WebElement)} frame - * The frame identifier. - * @return {!Condition} A new condition. - */ - function ableToSwitchToFrame(frame: number | WebElement | By | ((webdriver: WebDriver) => WebElement) | ByHash): Condition; - - /** - * Creates a condition that waits for an alert to be opened. Upon success, the - * returned promise will be fulfilled with the handle for the opened alert. - * - * @return {!Condition} The new condition. - */ - function alertIsPresent(): Condition; - - /** - * Creates a condition that will wait for the given element to be disabled. - * - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isEnabled - */ - function elementIsDisabled(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will wait for the given element to be enabled. - * - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isEnabled - */ - function elementIsEnabled(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will wait for the given element to be deselected. - * - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isSelected - */ - function elementIsNotSelected(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will wait for the given element to be in the DOM, - * yet not visible to the user. - * - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isDisplayed - */ - function elementIsNotVisible(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will wait for the given element to be selected. - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isSelected - */ - function elementIsSelected(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will wait for the given element to become visible. - * - * @param {!WebElement} element The element to test. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#isDisplayed - */ - function elementIsVisible(element: WebElement): WebElementCondition; - - /** - * Creates a condition that will loop until an element is - * {@link ./WebDriver#findElement found} with the given locator. - * - * @param {!(By|Function)} locator The locator to use. - * @return {!WebElementCondition} The new condition. - */ - function elementLocated(locator: Locator): WebElementCondition; - - /** - * Creates a condition that will wait for the given element's - * {@link WebDriver#getText visible text} to contain the given - * substring. - * - * @param {!WebElement} element The element to test. - * @param {string} substr The substring to search for. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#getText - */ - function elementTextContains(element: WebElement, substr: string): WebElementCondition; - - /** - * Creates a condition that will wait for the given element's - * {@link WebDriver#getText visible text} to match the given - * {@code text} exactly. - * - * @param {!WebElement} element The element to test. - * @param {string} text The expected text. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#getText - */ - function elementTextIs(element: WebElement, text: string): WebElementCondition; - - /** - * Creates a condition that will wait for the given element's - * {@link WebDriver#getText visible text} to match a regular - * expression. - * - * @param {!WebElement} element The element to test. - * @param {!RegExp} regex The regular expression to test against. - * @return {!WebElementCondition} The new condition. - * @see WebDriver#getText - */ - function elementTextMatches(element: WebElement, regex: RegExp): WebElementCondition; - - /** - * Creates a condition that will loop until at least one element is - * {@link WebDriver#findElement found} with the given locator. - * - * @param {!(Locator|By.Hash|Function)} locator The locator - * to use. - * @return {!Condition.>} The new - * condition. - */ - function elementsLocated(locator: Locator): Condition; - - /** - * Creates a condition that will wait for the given element to become stale. An - * element is considered stale once it is removed from the DOM, or a new page - * has loaded. - * - * @param {!WebElement} element The element that should become stale. - * @return {!Condition} The new condition. - */ - function stalenessOf(element: WebElement): Condition; - - /** - * Creates a condition that will wait for the current page's title to contain - * the given substring. - * - * @param {string} substr The substring that should be present in the page - * title. - * @return {!Condition.} The new condition. - */ - function titleContains(substr: string): Condition; - - /** - * Creates a condition that will wait for the current page's title to match the - * given value. - * - * @param {string} title The expected page title. - * @return {!Condition} The new condition. - */ - function titleIs(title: string): Condition; - - /** - * Creates a condition that will wait for the current page's title to match the - * given regular expression. - * - * @param {!RegExp} regex The regular expression to test against. - * @return {!Condition.} The new condition. - */ - function titleMatches(regex: RegExp): Condition; - - /** - * Creates a condition that will wait for the current page's url to contain - * the given substring. - * - * @param {string} substrUrl The substring that should be present in the current - * URL. - * @return {!Condition} The new condition. - */ - function urlContains(substrUrl: string): Condition; - - /** - * Creates a condition that will wait for the current page's url to match the - * given value. - * - * @param {string} url The expected page url. - * @return {!Condition} The new condition. - */ - function urlIs(url: string): Condition; - - /** - * Creates a condition that will wait for the current page's url to match the - * given regular expression. - * - * @param {!RegExp} regex The regular expression to test against. - * @return {!Condition} The new condition. - */ - function urlMatches(regex: RegExp): Condition; -} - -export interface ILocation { - x: number; - y: number; -} - -export interface ISize { - width: number; - height: number; -} - -export interface IRectangle { - x: number; - y: number; - width: number; - height: number; -} - -export interface IButton { - LEFT: string; - MIDDLE: string; - RIGHT: string; -} - -/** - * Representations of pressable keys that aren't text. These are stored in - * the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. Refer to - * http://www.google.com.au/search?&q=unicode+pua&btnG=Search - * - * @enum {string} - */ -export const Button: IButton; - -export interface IKey { - NULL: string; - CANCEL: string; // ^break - HELP: string; - BACK_SPACE: string; - TAB: string; - CLEAR: string; - RETURN: string; - ENTER: string; - SHIFT: string; - CONTROL: string; - ALT: string; - PAUSE: string; - ESCAPE: string; - SPACE: string; - PAGE_UP: string; - PAGE_DOWN: string; - END: string; - HOME: string; - ARROW_LEFT: string; - LEFT: string; - ARROW_UP: string; - UP: string; - ARROW_RIGHT: string; - RIGHT: string; - ARROW_DOWN: string; - DOWN: string; - INSERT: string; - DELETE: string; - SEMICOLON: string; - EQUALS: string; - - NUMPAD0: string; // number pad keys - NUMPAD1: string; - NUMPAD2: string; - NUMPAD3: string; - NUMPAD4: string; - NUMPAD5: string; - NUMPAD6: string; - NUMPAD7: string; - NUMPAD8: string; - NUMPAD9: string; - MULTIPLY: string; - ADD: string; - SEPARATOR: string; - SUBTRACT: string; - DECIMAL: string; - DIVIDE: string; - - F1: string; // function keys - F2: string; - F3: string; - F4: string; - F5: string; - F6: string; - F7: string; - F8: string; - F9: string; - F10: string; - F11: string; - F12: string; - - COMMAND: string; // Apple command key - META: string; // alias for Windows key - - /** - * Simulate pressing many keys at once in a 'chord'. Takes a sequence of - * keys or strings, appends each of the values to a string, - * and adds the chord termination key ({@link Key.NULL}) and returns - * the resulting string. - * - * Note: when the low-level webdriver key handlers see Keys.NULL, active - * modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event. - * - * @param {...string} var_args The key sequence to concatenate. - * @return {string} The null-terminated key sequence. - */ - chord(...var_args: Array): string; -} - -/** - * Representations of pressable keys that aren't text. These are stored in - * the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. Refer to - * http://www.google.com.au/search?&q=unicode+pua&btnG=Search - * - * @enum {string} - */ -export const Key: IKey; - -/** - * Class for defining sequences of complex user interactions. Each sequence - * will not be executed until {@link #perform} is called. - * - * Example: - * - * new ActionSequence(driver). - * keyDown(Key.SHIFT). - * click(element1). - * click(element2). - * dragAndDrop(element3, element4). - * keyUp(Key.SHIFT). - * perform(); - * - */ -export class ActionSequence { - // region Constructors - - /** - * @param {!WebDriver} driver The driver instance to use. - * @constructor - */ - constructor(driver: WebDriver); - - // endregion - - // region Methods - - /** - * Executes this action sequence. - * @return {!promise.Promise} A promise that will be resolved once - * this sequence has completed. - */ - perform(): promise.Promise; - - /** - * Moves the mouse. The location to move to may be specified in terms of the - * mouse's current location, an offset relative to the top-left corner of an - * element, or an element (in which case the middle of the element is used). - * - * @param {(!./WebElement|{x: number, y: number})} location The - * location to drag to, as either another WebElement or an offset in - * pixels. - * @param {{x: number, y: number}=} opt_offset If the target {@code location} - * is defined as a {@link ./WebElement}, this parameter defines - * an offset within that element. The offset should be specified in pixels - * relative to the top-left corner of the element's bounding box. If - * omitted, the element's center will be used as the target offset. - * @return {!ActionSequence} A self reference. - */ - mouseMove(location: WebElement | ILocation, opt_offset?: ILocation): ActionSequence; - - /** - * Presses a mouse button. The mouse button will not be released until - * {@link #mouseUp} is called, regardless of whether that call is made in this - * sequence or another. The behavior for out-of-order events (e.g. mouseDown, - * click) is undefined. - * - * If an element is provided, the mouse will first be moved to the center - * of that element. This is equivalent to: - * - * sequence.mouseMove(element).mouseDown() - * - * Warning: this method currently only supports the left mouse button. See - * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). - * - * @param {(./WebElement|input.Button)=} opt_elementOrButton Either - * the element to interact with or the button to click with. - * Defaults to {@link input.Button.LEFT} if neither an element nor - * button is specified. - * @param {input.Button=} opt_button The button to use. Defaults to - * {@link input.Button.LEFT}. Ignored if a button is provided as the - * first argument. - * @return {!ActionSequence} A self reference. - */ - mouseDown(opt_elementOrButton?: WebElement | string, opt_button?: string): ActionSequence; - - /** - * Releases a mouse button. Behavior is undefined for calling this function - * without a previous call to {@link #mouseDown}. - * - * If an element is provided, the mouse will first be moved to the center - * of that element. This is equivalent to: - * - * sequence.mouseMove(element).mouseUp() - * - * Warning: this method currently only supports the left mouse button. See - * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). - * - * @param {(./WebElement|input.Button)=} opt_elementOrButton Either - * the element to interact with or the button to click with. - * Defaults to {@link input.Button.LEFT} if neither an element nor - * button is specified. - * @param {input.Button=} opt_button The button to use. Defaults to - * {@link input.Button.LEFT}. Ignored if a button is provided as the - * first argument. - * @return {!ActionSequence} A self reference. - */ - mouseUp(opt_elementOrButton?: WebElement | string, opt_button?: string): ActionSequence; - - /** - * Convenience function for performing a 'drag and drop' manuever. The target - * element may be moved to the location of another element, or by an offset (in - * pixels). - * - * @param {!./WebElement} element The element to drag. - * @param {(!./WebElement|{x: number, y: number})} location The - * location to drag to, either as another WebElement or an offset in - * pixels. - * @return {!ActionSequence} A self reference. - */ - dragAndDrop(element: WebElement, location: WebElement | ILocation): ActionSequence; - - /** - * Clicks a mouse button. - * - * If an element is provided, the mouse will first be moved to the center - * of that element. This is equivalent to: - * - * sequence.mouseMove(element).click() - * - * @param {(./WebElement|input.Button)=} opt_elementOrButton Either - * the element to interact with or the button to click with. - * Defaults to {@link input.Button.LEFT} if neither an element nor - * button is specified. - * @param {input.Button=} opt_button The button to use. Defaults to - * {@link input.Button.LEFT}. Ignored if a button is provided as the - * first argument. - * @return {!ActionSequence} A self reference. - */ - click(opt_elementOrButton?: WebElement | string, opt_button?: string): ActionSequence; - - /** - * Double-clicks a mouse button. - * - * If an element is provided, the mouse will first be moved to the center of - * that element. This is equivalent to: - * - * sequence.mouseMove(element).doubleClick() - * - * Warning: this method currently only supports the left mouse button. See - * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). - * - * @param {(./WebElement|input.Button)=} opt_elementOrButton Either - * the element to interact with or the button to click with. - * Defaults to {@link input.Button.LEFT} if neither an element nor - * button is specified. - * @param {input.Button=} opt_button The button to use. Defaults to - * {@link input.Button.LEFT}. Ignored if a button is provided as the - * first argument. - * @return {!ActionSequence} A self reference. - */ - doubleClick(opt_elementOrButton?: WebElement | string, opt_button?: string): ActionSequence; - - /** - * Performs a modifier key press. The modifier key is not released - * until {@link #keyUp} or {@link #sendKeys} is called. The key press will be - * targetted at the currently focused element. - * @param {!Key} key The modifier key to push. Must be one of - * {ALT, CONTROL, SHIFT, COMMAND, META}. - * @return {!ActionSequence} A self reference. - * @throws {Error} If the key is not a valid modifier key. - */ - keyDown(key: string): ActionSequence; - /** - * Performs a modifier key release. The release is targetted at the currently - * focused element. - * @param {!Key} key The modifier key to release. Must be one of - * {ALT, CONTROL, SHIFT, COMMAND, META}. - * @return {!ActionSequence} A self reference. - * @throws {Error} If the key is not a valid modifier key. - */ - keyUp(key: string): ActionSequence; +/** + * x,y + */ +export interface ILocation { + x: number; + y: number; +} - /** - * Simulates typing multiple keys. Each modifier key encountered in the - * sequence will not be released until it is encountered again. All key events - * will be targeted at the currently focused element. - * - * @param {...(string|!input.Key|!Array<(string|!input.Key)>)} var_args - * The keys to type. - * @return {!ActionSequence} A self reference. - * @throws {Error} If the key is not a valid modifier key. - */ - sendKeys(...var_args: Array>): ActionSequence; +/** + * width, height + */ +export interface ISize { + width: number; + height: number; +} - // endregion +/** + * x,y,w,h + */ +export interface IRectangle { + x: number; + y: number; + width: number; + height: number; } /** @@ -1812,17 +701,17 @@ export class ActionSequence { */ export class TouchSequence { /* - * @param {!WebDriver} driver The driver instance to use. - * @constructor - */ + * @param {!WebDriver} driver The driver instance to use. + * @constructor + */ constructor(driver: WebDriver); /** * Executes this action sequence. - * @return {!promise.Promise} A promise that will be resolved once + * @return {!Promise} A promise that will be resolved once * this sequence has completed. */ - perform(): promise.Promise; + perform(): Promise; /** * Taps an element. @@ -1894,7 +783,7 @@ export class TouchSequence { * Flick, starting anywhere on the screen, at speed xspeed and yspeed. * * @param {{xspeed: number, yspeed: number}} speed The speed to flick in each - direction, in pixels per second. + * direction, in pixels per second. * @return {!TouchSequence} A self reference. */ flick(speed: ISpeed): TouchSequence; @@ -1910,11 +799,17 @@ export class TouchSequence { flickElement(elem: WebElement, offset: IOffset, speed: number): TouchSequence; } +/** + * x.y again + */ export interface IOffset { x: number; y: number; } +/** + * delta x,y + */ export interface ISpeed { xspeed: number; yspeed: number; @@ -1939,10 +834,10 @@ export class Alert { /** * Retrieves the message text displayed with this alert. For instance, if the * alert were opened with alert('hello'), then this would return 'hello'. - * @return {!promise.Promise} A promise that will be resolved to the + * @return {!Promise} A promise that will be resolved to the * text displayed with this alert. */ - getText(): promise.Promise; + getText(): Promise; /** * Sets the username and password in an alert prompting for credentials (such @@ -1951,34 +846,34 @@ export class Alert { * * @param {string} username The username to send. * @param {string} password The password to send. - * @return {!promise.Promise} A promise that will be resolved when this + * @return {!Promise} A promise that will be resolved when this * command has completed. */ - authenticateAs(username: string, password: string): promise.Promise; + authenticateAs(username: string, password: string): Promise; /** * Accepts this alert. - * @return {!promise.Promise} A promise that will be resolved when + * @return {!Promise} A promise that will be resolved when * this command has completed. */ - accept(): promise.Promise; + accept(): Promise; /** * Dismisses this alert. - * @return {!promise.Promise} A promise that will be resolved when + * @return {!Promise} A promise that will be resolved when * this command has completed. */ - dismiss(): promise.Promise; + dismiss(): Promise; /** * Sets the response text on this alert. This command will return an error if * the underlying alert does not support response text (e.g. window.alert and * window.confirm). * @param {string} text The text to set. - * @return {!promise.Promise} A promise that will be resolved when + * @return {!Promise} A promise that will be resolved when * this command has completed. */ - sendKeys(text: string): promise.Promise; + sendKeys(text: string): Promise; // endregion } @@ -1997,7 +892,11 @@ export class Alert { * @implements {promise.Thenable.} * @final */ -export interface AlertPromise extends promise.IThenable {} +export interface AlertPromise extends Promise {} + +/** + * Implement AlertPromise + */ export class AlertPromise extends Alert { /** * @param {!WebDriver} driver The driver controlling the browser this @@ -2005,7 +904,7 @@ export class AlertPromise extends Alert { * @param {!promise.Thenable} alert A thenable * that will be fulfilled with the promised alert. */ - constructor(driver: WebDriver, alert: promise.Promise); + constructor(driver: WebDriver, alert: Promise); } /** @@ -2027,8 +926,14 @@ export interface IBrowser { HTMLUNIT: string; } +/** + * Instace of + */ export const Browser: IBrowser; +/** + * ProxyConfig + */ export interface ProxyConfig { proxyType: string; proxyAutoconfigUrl?: string; @@ -2120,9 +1025,9 @@ export class Builder { * Any calls to {@link #withCapabilities} after this function will * overwrite these settings. * - *

You may also define the target browser using the {@code SELENIUM_BROWSER} - * environment variable. If set, this environment variable should be of the - * form {@code browser[:[version][:platform]]}. + *

You may also define the target browser using the {@code + * SELENIUM_BROWSER} environment variable. If set, this environment variable + * should be of the form {@code browser[:[version][:platform]]}. * * @param {(string|Browser)} name The name of the target browser; * common defaults are available on the {@link Browser} enum. @@ -2142,8 +1047,8 @@ export class Builder { getCapabilities(): Capabilities; /** - * @return {string} The URL of the WebDriver server this instance is configured - * to use. + * @return {string} The URL of the WebDriver server this instance is + * configured to use. */ getServerUrl(): string; @@ -2156,8 +1061,8 @@ export class Builder { /** * Sets the default action to take with an unexpected alert before returning * an error. - * @param {string} beahvior The desired behavior; should be 'accept', 'dismiss', - * or 'ignore'. Defaults to 'dismiss'. + * @param {string} beahvior The desired behavior; should be 'accept', + * 'dismiss', or 'ignore'. Defaults to 'dismiss'. * @return {!Builder} A self reference. */ setAlertBehavior(behavior: string): Builder; @@ -2173,16 +1078,6 @@ export class Builder { */ setChromeOptions(options: chrome.Options): Builder; - /** - * Sets the control flow that created drivers should execute actions in. If - * the flow is never set, or is set to {@code null}, it will use the active - * flow at the time {@link #build()} is called. - * @param {promise.ControlFlow} flow The control flow to use, or - * {@code null} to - * @return {!Builder} A self reference. - */ - setControlFlow(flow: promise.ControlFlow): Builder; - /** * Set {@linkplain edge.Options options} specific to Microsoft's Edge browser * for drivers created by this builder. Any proxy settings defined on the @@ -2194,13 +1089,6 @@ export class Builder { */ setEdgeOptions(options: edge.Options): Builder; - /** - * Sets whether native events should be used. - * @param {boolean} enabled Whether to enable native events. - * @return {!Builder} A self reference. - */ - setEnableNativeEvents(enabled: boolean): Builder; - /** * Sets Firefox-specific options for drivers created by this builder. Any * logging or proxy settings defined on the given options will take precedence @@ -2229,18 +1117,7 @@ export class Builder { * desired logging preferences. * @return {!Builder} A self reference. */ - setLoggingPrefs(prefs: logging.Preferences | Object): Builder; - - /** - * Sets Opera specific {@linkplain opera.Options options} for drivers created - * by this builder. Any logging or proxy settings defined on the given options - * will take precedence over those set through {@link #setLoggingPrefs} and - * {@link #setProxy}, respectively. - * - * @param {!opera.Options} options The OperaDriver options to use. - * @return {!Builder} A self reference. - */ - setOperaOptions(options: opera.Options): Builder; + setLoggingPrefs(prefs: logging.Preferences|{}): Builder; /** * Sets the proxy configuration to use for WebDriver clients created by this @@ -2261,17 +1138,10 @@ export class Builder { */ setSafari(options: safari.Options): Builder; - /** - * Sets how elements should be scrolled into view for interaction. - * @param {number} behavior The desired scroll behavior: either 0 to align with - * the top of the viewport or 1 to align with the bottom. - * @return {!Builder} A self reference. - */ - setScrollBehavior(behavior: number): Builder; - /** * Sets the http agent to use for each request. - * If this method is not called, the Builder will use http.globalAgent by default. + * If this method is not called, the Builder will use http.globalAgent by + * default. * * @param {http.Agent} agent The agent to use for each request. * @return {!Builder} A self reference. @@ -2279,9 +1149,10 @@ export class Builder { usingHttpAgent(agent: any): Builder; /** - * Sets the URL of a remote WebDriver server to use. Once a remote URL has been - * specified, the builder direct all new clients to that server. If this method - * is never called, the Builder will attempt to create all clients locally. + * Sets the URL of a remote WebDriver server to use. Once a remote URL has + * been specified, the builder direct all new clients to that server. If this + * method is never called, the Builder will attempt to create all clients + * locally. * *

As an alternative to this method, you may also set the * {@code SELENIUM_REMOTE_URL} environment variable. @@ -2308,150 +1179,15 @@ export class Builder { * capabilities for a new session. * @return {!Builder} A self reference. */ - withCapabilities(capabilities: Object | Capabilities): Builder; + withCapabilities(capabilities: {}|Capabilities): Builder; // endregion } -/** - * Describes a mechanism for locating an element on the page. - * @final - */ -export class By { - /** - * @param {string} using the name of the location strategy to use. - * @param {string} value the value to search for. - */ - constructor(using: string, value: string); - - /** - * Locates elements that have a specific class name. - * - * @param {string} name The class name to search for. - * @return {!By} The new locator. - * @see http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes - * @see http://www.w3.org/TR/CSS2/selector.html#class-html - */ - static className(name: string): By; - - /** - * Locates elements using a CSS selector. - * - * @param {string} selector The CSS selector to use. - * @return {!By} The new locator. - * @see http://www.w3.org/TR/CSS2/selector.html - */ - static css(selector: string): By; - - /** - * Locates eleemnts by the ID attribute. This locator uses the CSS selector - * `*[id='$ID']`, _not_ `document.getElementById`. - * - * @param {string} id The ID to search for. - * @return {!By} The new locator. - */ - static id(id: string): By; - - /** - * Locates link elements whose - * {@linkplain WebElement#getText visible text} matches the given - * string. - * - * @param {string} text The link text to search for. - * @return {!By} The new locator. - */ - static linkText(text: string): By; - - /** - * Locates an elements by evaluating a - * {@linkplain WebDriver#executeScript JavaScript expression}. - * The result of this expression must be an element or list of elements. - * - * @param {!(string|Function)} script The script to execute. - * @param {...*} var_args The arguments to pass to the script. - * @return {function(!./WebDriver): !./promise.Promise} - * A new JavaScript-based locator function. - */ - static js(script: string | Function, ...var_args: any[]): (webdriver: WebDriver) => promise.Promise; - - /** - * Locates elements whose `name` attribute has the given value. - * - * @param {string} name The name attribute to search for. - * @return {!By} The new locator. - */ - static name(name: string): By; - - /** - * Locates link elements whose - * {@linkplain WebElement#getText visible text} contains the given - * substring. - * - * @param {string} text The substring to check for in a link's visible text. - * @return {!By} The new locator. - */ - static partialLinkText(text: string): By; - - /** - * Locates elements with a given tag name. - * - * @param {string} name The tag name to search for. - * @return {!By} The new locator. - * @deprecated Use {@link By.css() By.css(tagName)} instead. - */ - static tagName(name: string): By; - - /** - * Locates elements matching a XPath selector. Care should be taken when - * using an XPath selector with a {@link WebElement} as WebDriver - * will respect the context in the specified in the selector. For example, - * given the selector `//div`, WebDriver will search from the document root - * regardless of whether the locator was used with a WebElement. - * - * @param {string} xpath The XPath selector to use. - * @return {!By} The new locator. - * @see http://www.w3.org/TR/xpath/ - */ - static xpath(xpath: string): By; - - /** @override */ - toString(): string; -} - -/** - * Short-hand expressions for the primary element locator strategies. - * For example the following two statements are equivalent: - * - * var e1 = driver.findElement(By.id('foo')); - * var e2 = driver.findElement({id: 'foo'}); - * - * Care should be taken when using JavaScript minifiers (such as the - * Closure compiler), as locator hashes will always be parsed using - * the un-obfuscated properties listed. - * - * @typedef {( - * {className: string}| - * {css: string}| - * {id: string}| - * {js: string}| - * {linkText: string}| - * {name: string}| - * {partialLinkText: string}| - * {tagName: string}| - * {xpath: string})} - */ -export type ByHash = { className: string } | - { css: string } | - { id: string } | - { js: string } | - { linkText: string } | - { name: string } | - { partialLinkText: string } | - { tagName: string } | - { xpath: string }; export type Locator = By | Function | ByHash; + /** * Common webdriver capability keys. * @enum {string} @@ -2492,7 +1228,7 @@ export interface ICapability { LOGGING_PREFS: string; /** - * Whether this session generates native events when simulating user input. + * Whether this session generates native events when simulating user input. */ NATIVE_EVENTS: string; @@ -2544,8 +1280,14 @@ export interface ICapability { VERSION: string; } +/** + * The standard WebDriver capability keys. + */ export const Capability: ICapability; +/** + * Describes a set of capabilities for a WebDriver session. + */ export class Capabilities { // region Constructors @@ -2554,13 +1296,14 @@ export class Capabilities { * capabilities to merge into this instance. * @constructor */ - constructor(opt_other?: Capabilities | Object); + constructor(opt_other?: Capabilities|{}); // endregion // region Methods /** @return {!Object} The JSON representation of this instance. */ + // tslint:disable-next-line:no-any TS does not support typing JSON toJSON(): any; /** @@ -2570,7 +1313,7 @@ export class Capabilities { * merge into this instance. * @return {!Capabilities} A self reference. */ - merge(other: Capabilities | Object): Capabilities; + merge(other: Capabilities|{}): Capabilities; /** * @param {string} key The capability to set. @@ -2578,6 +1321,7 @@ export class Capabilities { * serializable. Pass {@code null} to unset the capability. * @return {!Capabilities} A self reference. */ + // tslint:disable-next-line:no-any TS does not support typing JSON set(key: string, value: any): Capabilities; /** @@ -2588,7 +1332,7 @@ export class Capabilities { * logging preferences. * @return {!Capabilities} A self reference. */ - setLoggingPrefs(prefs: logging.Preferences | Object): Capabilities; + setLoggingPrefs(prefs: logging.Preferences|{}): Capabilities; /** * Sets the proxy configuration for this instance. @@ -2606,8 +1350,8 @@ export class Capabilities { /** * Sets how elements should be scrolled into view for interaction. - * @param {number} behavior The desired scroll behavior: either 0 to align with - * the top of the viewport or 1 to align with the bottom. + * @param {number} behavior The desired scroll behavior: either 0 to align + * with the top of the viewport or 1 to align with the bottom. * @return {!Capabilities} A self reference. */ setScrollBehavior(behavior: number): Capabilities; @@ -2615,8 +1359,8 @@ export class Capabilities { /** * Sets the default action to take with an unexpected alert before returning * an error. - * @param {string} behavior The desired behavior; should be 'accept', 'dismiss', - * or 'ignore'. Defaults to 'dismiss'. + * @param {string} behavior The desired behavior; should be 'accept', + * 'dismiss', or 'ignore'. Defaults to 'dismiss'. * @return {!Capabilities} A self reference. */ setAlertBehavior(behavior: string): Capabilities; @@ -2626,6 +1370,7 @@ export class Capabilities { * @return {*} The capability with the given key, or {@code null} if it has * not been set. */ + // tslint:disable-next-line:no-any TS does not support typing JSON get(key: string): any; /** @@ -2704,186 +1449,6 @@ export class Capabilities { // endregion } -/** - * An enumeration of valid command string. - */ -export interface ICommandName { - GET_SERVER_STATUS: string; - - NEW_SESSION: string; - GET_SESSIONS: string; - DESCRIBE_SESSION: string; - - CLOSE: string; - QUIT: string; - - GET_CURRENT_URL: string; - GET: string; - GO_BACK: string; - GO_FORWARD: string; - REFRESH: string; - - ADD_COOKIE: string; - GET_COOKIE: string; - GET_ALL_COOKIES: string; - DELETE_COOKIE: string; - DELETE_ALL_COOKIES: string; - - GET_ACTIVE_ELEMENT: string; - FIND_ELEMENT: string; - FIND_ELEMENTS: string; - FIND_CHILD_ELEMENT: string; - FIND_CHILD_ELEMENTS: string; - - CLEAR_ELEMENT: string; - CLICK_ELEMENT: string; - SEND_KEYS_TO_ELEMENT: string; - SUBMIT_ELEMENT: string; - - GET_CURRENT_WINDOW_HANDLE: string; - GET_WINDOW_HANDLES: string; - GET_WINDOW_POSITION: string; - SET_WINDOW_POSITION: string; - GET_WINDOW_SIZE: string; - SET_WINDOW_SIZE: string; - MAXIMIZE_WINDOW: string; - - SWITCH_TO_WINDOW: string; - SWITCH_TO_FRAME: string; - GET_PAGE_SOURCE: string; - GET_TITLE: string; - - EXECUTE_SCRIPT: string; - EXECUTE_ASYNC_SCRIPT: string; - - GET_ELEMENT_TEXT: string; - GET_ELEMENT_TAG_NAME: string; - IS_ELEMENT_SELECTED: string; - IS_ELEMENT_ENABLED: string; - IS_ELEMENT_DISPLAYED: string; - GET_ELEMENT_LOCATION: string; - GET_ELEMENT_LOCATION_IN_VIEW: string; - GET_ELEMENT_SIZE: string; - GET_ELEMENT_ATTRIBUTE: string; - GET_ELEMENT_VALUE_OF_CSS_PROPERTY: string; - ELEMENT_EQUALS: string; - - SCREENSHOT: string; - IMPLICITLY_WAIT: string; - SET_SCRIPT_TIMEOUT: string; - SET_TIMEOUT: string; - - ACCEPT_ALERT: string; - DISMISS_ALERT: string; - GET_ALERT_TEXT: string; - SET_ALERT_TEXT: string; - - EXECUTE_SQL: string; - GET_LOCATION: string; - SET_LOCATION: string; - GET_APP_CACHE: string; - GET_APP_CACHE_STATUS: string; - CLEAR_APP_CACHE: string; - IS_BROWSER_ONLINE: string; - SET_BROWSER_ONLINE: string; - - GET_LOCAL_STORAGE_ITEM: string; - GET_LOCAL_STORAGE_KEYS: string; - SET_LOCAL_STORAGE_ITEM: string; - REMOVE_LOCAL_STORAGE_ITEM: string; - CLEAR_LOCAL_STORAGE: string; - GET_LOCAL_STORAGE_SIZE: string; - - GET_SESSION_STORAGE_ITEM: string; - GET_SESSION_STORAGE_KEYS: string; - SET_SESSION_STORAGE_ITEM: string; - REMOVE_SESSION_STORAGE_ITEM: string; - CLEAR_SESSION_STORAGE: string; - GET_SESSION_STORAGE_SIZE: string; - - SET_SCREEN_ORIENTATION: string; - GET_SCREEN_ORIENTATION: string; - - // These belong to the Advanced user interactions - an element is - // optional for these commands. - CLICK: string; - DOUBLE_CLICK: string; - MOUSE_DOWN: string; - MOUSE_UP: string; - MOVE_TO: string; - SEND_KEYS_TO_ACTIVE_ELEMENT: string; - - // These belong to the Advanced Touch API - TOUCH_SINGLE_TAP: string; - TOUCH_DOWN: string; - TOUCH_UP: string; - TOUCH_MOVE: string; - TOUCH_SCROLL: string; - TOUCH_DOUBLE_TAP: string; - TOUCH_LONG_PRESS: string; - TOUCH_FLICK: string; - - GET_AVAILABLE_LOG_TYPES: string; - GET_LOG: string; - GET_SESSION_LOGS: string; - - UPLOAD_FILE: string; -} - -export const CommandName: ICommandName; - -/** - * Describes a command to be executed by the WebDriverJS framework. - * @param {!CommandName} name The name of this command. - * @constructor - */ -export class Command { - // region Constructors - - /** - * @param {!CommandName} name The name of this command. - * @constructor - */ - constructor(name: string); - - // endregion - - // region Methods - - /** - * @return {!CommandName} This command's name. - */ - getName(): string; - - /** - * Sets a parameter to send with this command. - * @param {string} name The parameter name. - * @param {*} value The parameter value. - * @return {!Command} A self reference. - */ - setParameter(name: string, value: any): Command; - - /** - * Sets the parameters for this command. - * @param {!Object.<*>} parameters The command parameters. - * @return {!Command} A self reference. - */ - setParameters(parameters: any): Command; - - /** - * Returns a named command parameter. - * @param {string} key The parameter key to look up. - * @return {*} The parameter value, or undefined if it has not been set. - */ - getParameter(key: string): any; - - /** - * @return {!Object.<*>} The parameters to send with this command. - */ - getParameters(): any; - - // endregion -} /** * Handles the execution of WebDriver {@link Command commands}. @@ -2897,10 +1462,11 @@ export class Executor { * response object. * * @param {!Command} command The command to execute. - * @return {!promise.Promise} A promise that will be fulfilled with + * @return {!Promise} A promise that will be fulfilled with * the command result. */ - execute(command: Command): promise.Promise + // tslint:disable-next-line:no-any TS does not support typing JSON + execute(command: Command): Promise; } /** @@ -2913,7 +1479,7 @@ export class Listener { * listener. * @param {boolean} oneshot Whether this listener should only be used once. */ - constructor(fn: Function, scope: Object, oneshot: boolean); + constructor(fn: Function, scope: {}, oneshot: boolean); } /** @@ -2953,7 +1519,8 @@ export class EventEmitter { * @param {string} type The type of event to listen for. * @param {!Function} fn The function to invoke when the event is fired. * @param {Object=} opt_self The object in whose scope to invoke the listener. - * @param {boolean=} opt_oneshot Whether the listener should b (e removed after + * @param {boolean=} opt_oneshot Whether the listener should b (e removed + * after * the first event is fired. * @return {!EventEmitter} A self reference. * @private @@ -2965,7 +1532,8 @@ export class EventEmitter { * event is emitted, after which it will be removed. * @param {string} type The type of event to listen for. * @param {!Function} fn The function to invoke when the event is fired. - * @param {Object=} opt_scope The object in whose scope to invoke the listener. + * @param {Object=} opt_scope The object in whose scope to invoke the + * listener. * @return {!EventEmitter} A self reference. */ once(type: string, fn: any, opt_scope?: any): EventEmitter; @@ -2974,7 +1542,8 @@ export class EventEmitter { * An alias for {@code #addListener()}. * @param {string} type The type of event to listen for. * @param {!Function} fn The function to invoke when the event is fired. - * @param {Object=} opt_scope The object in whose scope to invoke the listener. + * @param {Object=} opt_scope The object in whose scope to invoke the + * listener. * @return {!EventEmitter} A self reference. */ on(type: string, fn: Function, opt_scope?: any): EventEmitter; @@ -3007,8 +1576,8 @@ export class Navigation { /** * Interface for navigating back and forth in the browser history. * - * This class should never be instantiated directly. Insead, obtain an instance - * with + * This class should never be instantiated directly. Insead, obtain an + * instance with * * navigate() * @@ -3023,31 +1592,31 @@ export class Navigation { /** * Schedules a command to navigate to a new URL. * @param {string} url The URL to navigate to. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the URL has been loaded. */ - to(url: string): promise.Promise; + to(url: string): Promise; /** * Schedules a command to move backwards in the browser history. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the navigation event has completed. */ - back(): promise.Promise; + back(): Promise; /** * Schedules a command to move forwards in the browser history. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the navigation event has completed. */ - forward(): promise.Promise; + forward(): Promise; /** * Schedules a command to refresh the current page. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the navigation event has completed. */ - refresh(): promise.Promise; + refresh(): Promise; // endregion } @@ -3089,28 +1658,28 @@ export interface IWebDriverOptionsCookie { /** * When the cookie expires. * - * When {@linkplain Options#addCookie() adding a cookie}, this may be specified - * in _seconds_ since Unix epoch (January 1, 1970). The expiry will default to - * 20 years in the future if omitted. + * When {@linkplain Options#addCookie() adding a cookie}, this may be + * specified in _seconds_ since Unix epoch (January 1, 1970). The expiry will + * default to 20 years in the future if omitted. * * The expiry is always returned in seconds since epoch when * {@linkplain Options#getCookies() retrieving cookies} from the browser. * * @type {(!Date|number|undefined)} */ - expiry?: number | Date; + expiry?: number|Date; } export interface IWebDriverCookie extends IWebDriverOptionsCookie { - /** - * When the cookie expires. - * - * The expiry is always returned in seconds since epoch when - * {@linkplain Options#getCookies() retrieving cookies} from the browser. - * - * @type {(!number|undefined)} - */ - expiry?: number; + /** + * When the cookie expires. + * + * The expiry is always returned in seconds since epoch when + * {@linkplain Options#getCookies() retrieving cookies} from the browser. + * + * @type {(!number|undefined)} + */ + expiry?: number; } /** @@ -3132,51 +1701,51 @@ export class Options { /** * Schedules a command to add a cookie. * @param {IWebDriverOptionsCookie} spec Defines the cookie to add. - * @return {!promise.Promise} A promise that will be resolved + * @return {!Promise} A promise that will be resolved * when the cookie has been added to the page. * @throws {error.InvalidArgumentError} if any of the cookie parameters are * invalid. * @throws {TypeError} if `spec` is not a cookie object. */ - addCookie(spec: IWebDriverOptionsCookie): promise.Promise; + addCookie(spec: IWebDriverOptionsCookie): Promise; /** * Schedules a command to delete all cookies visible to the current page. - * @return {!promise.Promise} A promise that will be resolved when all + * @return {!Promise} A promise that will be resolved when all * cookies have been deleted. */ - deleteAllCookies(): promise.Promise; + deleteAllCookies(): Promise; /** - * Schedules a command to delete the cookie with the given name. This command is - * a no-op if there is no cookie with the given name visible to the current + * Schedules a command to delete the cookie with the given name. This command + * is a no-op if there is no cookie with the given name visible to the current * page. * @param {string} name The name of the cookie to delete. - * @return {!promise.Promise} A promise that will be resolved when the + * @return {!Promise} A promise that will be resolved when the * cookie has been deleted. */ - deleteCookie(name: string): promise.Promise; + deleteCookie(name: string): Promise; /** * Schedules a command to retrieve all cookies visible to the current page. * Each cookie will be returned as a JSON object as described by the WebDriver * wire protocol. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * cookies visible to the current page. * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object */ - getCookies(): promise.Promise; + getCookies(): Promise; /** - * Schedules a command to retrieve the cookie with the given name. Returns null - * if there is no such cookie. The cookie will be returned as a JSON object as - * described by the WebDriver wire protocol. + * Schedules a command to retrieve the cookie with the given name. Returns + * null if there is no such cookie. The cookie will be returned as a JSON + * object as described by the WebDriver wire protocol. * @param {string} name The name of the cookie to retrieve. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * named cookie, or {@code null} if there is no such cookie. * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object */ - getCookie(name: string): promise.Promise; + getCookie(name: string): Promise; /** * @return {!Logs} The interface for managing driver @@ -3185,10 +1754,15 @@ export class Options { logs(): Logs; /** - * @return {!Timeouts} The interface for managing driver - * timeouts. + * The current timeouts + */ + getTimeouts(): Promise; + + /** + * Set current timeouts */ - timeouts(): Timeouts; + setTimeouts(timeouts: ITimeouts): Promise; + /** * @return {!Window} The interface for managing the @@ -3199,25 +1773,22 @@ export class Options { // endregion } -/** - * An interface for managing timeout behavior for WebDriver instances. - */ -export class Timeouts { - // region Constructors - +interface ITimeouts { /** - * @param {!WebDriver} driver The parent driver. - * @constructor + * Sets the amount of time to wait, in milliseconds, for an asynchronous + * script to finish execution before returning an error. If the timeout is + * less than or equal to 0, the script will be allowed to run indefinitely. */ - constructor(driver: WebDriver); - - // endregion - - // region Methods - + script?: number; + /** + * Sets the amount of time to wait, in milliseconds, for a page load to + * complete before returning an error. If the timeout is negative, + * page loads may be indefinite. + */ + pageLoad?: number; /** - * Specifies the amount of time the driver should wait when searching for an - * element if it is not immediately present. + * Specifies the amount of time in milliseconds the driver should wait when + * searching for an element if it is not immediately present. *

* When searching for a single element, the driver should poll the page * until the element has been found, or this timeout expires before failing @@ -3231,36 +1802,11 @@ export class Timeouts { * Increasing the implicit wait timeout should be used judiciously as it * will have an adverse effect on test run time, especially when used with * slower location strategies like XPath. - * - * @param {number} ms The amount of time to wait, in milliseconds. - * @return {!promise.Promise} A promise that will be resolved when the - * implicit wait timeout has been set. - */ - implicitlyWait(ms: number): promise.Promise; - - /** - * Sets the amount of time to wait, in milliseconds, for an asynchronous script - * to finish execution before returning an error. If the timeout is less than or - * equal to 0, the script will be allowed to run indefinitely. - * - * @param {number} ms The amount of time to wait, in milliseconds. - * @return {!promise.Promise} A promise that will be resolved when the - * script timeout has been set. - */ - setScriptTimeout(ms: number): promise.Promise; - - /** - * Sets the amount of time to wait for a page load to complete before returning - * an error. If the timeout is negative, page loads may be indefinite. - * @param {number} ms The amount of time to wait, in milliseconds. - * @return {!promise.Promise} A promise that will be resolved when - * the timeout has been set. */ - pageLoadTimeout(ms: number): promise.Promise; - - // endregion + implicit?: number; } + /** * An interface for managing the current window. */ @@ -3280,38 +1826,38 @@ export class Window { /** * Retrieves the window's current position, relative to the top left corner of * the screen. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * window's position in the form of a {x:number, y:number} object literal. */ - getPosition(): promise.Promise; + getPosition(): Promise; /** * Repositions the current window. - * @param {number} x The desired horizontal position, relative to the left side - * of the screen. + * @param {number} x The desired horizontal position, relative to the left + * side of the screen. * @param {number} y The desired vertical position, relative to the top of the * of the screen. - * @return {!promise.Promise} A promise that will be resolved when the + * @return {!Promise} A promise that will be resolved when the * command has completed. */ - setPosition(x: number, y: number): promise.Promise; + setPosition(x: number, y: number): Promise; /** * Retrieves the window's current size. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * window's size in the form of a {width:number, height:number} object * literal. */ - getSize(): promise.Promise; + getSize(): Promise; /** * Resizes the current window. * @param {number} width The desired window width. * @param {number} height The desired window height. - * @return {!promise.Promise} A promise that will be resolved when the + * @return {!Promise} A promise that will be resolved when the * command has completed. */ - setSize(width: number, height: number): promise.Promise; + setSize(width: number, height: number): Promise; /** * Google3 modification for v4 API backport. @@ -3329,10 +1875,10 @@ export class Window { /** * Maximizes the current window. - * @return {!promise.Promise} A promise that will be resolved when the + * @return {!Promise} A promise that will be resolved when the * command has completed. */ - maximize(): promise.Promise; + maximize(): Promise; // endregion } @@ -3363,18 +1909,18 @@ export class Logs { * session. * * @param {!logging.Type} type The desired log type. - * @return {!promise.Promise.>} A + * @return {!Promise.>} A * promise that will resolve to a list of log entries for the specified * type. */ - get(type: string): promise.Promise; + get(type: string): Promise; /** * Retrieves the log types available to this driver. - * @return {!promise.Promise.>} A + * @return {!Promise.>} A * promise that will resolve to a list of available log types. */ - getAvailableLogTypes(): promise.Promise; + getAvailableLogTypes(): Promise; // endregion } @@ -3404,12 +1950,12 @@ export class TargetLocator { activeElement(): WebElementPromise; /** - * Schedules a command to switch focus of all future commands to the first frame - * on the page. - * @return {!promise.Promise} A promise that will be resolved when the + * Schedules a command to switch focus of all future commands to the first + * frame on the page. + * @return {!Promise} A promise that will be resolved when the * driver has changed focus to the default content. */ - defaultContent(): promise.Promise; + defaultContent(): Promise; /** * Schedules a command to switch the focus of all future commands to another @@ -3427,11 +1973,10 @@ export class TargetLocator { * rejected with a {@linkplain error.NoSuchFrameError}. * * @param {(number|WebElement|null)} id The frame locator. - * @return {!promise.Promise} A promise that will be resolved + * @return {!Promise} A promise that will be resolved * when the driver has changed focus to the specified frame. */ - // google3 local modification. TargetLocator.frame accepts the null type. - frame(nameOrIndex: number | WebElement | null): promise.Promise; + frame(nameOrIndex: number|WebElement): Promise; /** * Schedules a command to switch the focus of all future commands to another @@ -3443,10 +1988,10 @@ export class TargetLocator { * * @param {string} nameOrHandle The name or window handle of the window to * switch focus to. - * @return {!promise.Promise} A promise that will be resolved + * @return {!Promise} A promise that will be resolved * when the driver has changed focus to the specified window. */ - window(nameOrHandle: string): promise.Promise; + window(nameOrHandle: string): Promise; /** * Schedules a command to change focus to the active modal dialog, such as @@ -3489,22 +2034,20 @@ export class FileDetector { * * @param {!WebDriver} driver The driver for the current browser. * @param {string} path The path to process. - * @return {!promise.Promise} A promise for the processed + * @return {!Promise} A promise for the processed * file path. * @package */ - handleFile(driver: WebDriver, path: string): promise.Promise; + handleFile(driver: WebDriver, path: string): Promise; } -export type CreateSessionCapabilities = Capabilities | { - desired?: Capabilities, - required?: Capabilities -}; +export type CreateSessionCapabilities = + Capabilities | {desired?: Capabilities, required?: Capabilities}; /** * Creates a new WebDriver client, which provides control over a browser. * - * Every WebDriver command returns a {@code promise.Promise} that + * Every WebDriver command returns a {@code 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 @@ -3524,31 +2067,17 @@ export class WebDriver { // region Constructors /** - * @param {!(Session|promise.Promise)} session Either a + * @param {!(Session|Promise)} session Either a * known session or a promise that will be resolved to a session. * @param {!command.Executor} executor The executor to use when sending * commands to the browser. - * @param {promise.ControlFlow=} opt_flow The flow to - * schedule commands through. Defaults to the active flow object. */ - constructor(session: Session | promise.Promise, executor: Executor, opt_flow?: promise.ControlFlow); + constructor(session: Session|Promise, executor: Executor); // endregion // region StaticMethods - /** - * Creates a new WebDriver client for an existing session. - * @param {!command.Executor} executor Command executor to use when querying - * for session details. - * @param {string} sessionId ID of the session to attach to. - * @param {promise.ControlFlow=} opt_flow The control flow all - * driver commands should execute under. Defaults to the - * {@link promise.controlFlow() currently active} control flow. - * @return {!WebDriver} A new client for the specified session. - */ - static attachToSession(executor: Executor, sessionId: string, opt_flow?: promise.ControlFlow): WebDriver; - /** * Creates a new WebDriver session. * @@ -3605,31 +2134,26 @@ export class WebDriver { * up any resources associated with the session. * @return {!WebDriver} The driver for the newly created session. */ - // This method's arguments are untyped so that its overloads can have correct types. - // Typescript doesn't allow static methods to be overridden with incompatible signatures. + // This method's arguments are untyped so that its overloads can have correct + // types. Typescript doesn't allow static methods to be overridden with + // incompatible signatures. static createSession(...var_args: any[]): WebDriver; // endregion // region Methods - /** - * @return {!promise.ControlFlow} The control flow used by this - * instance. - */ - controlFlow(): promise.ControlFlow; - /** * Schedules a {@link command.Command} to be executed by this driver's * {@link command.Executor}. * * @param {!command.Command} command The command to schedule. * @param {string} description A description of the command for debugging. - * @return {!promise.Promise} A promise that will be resolved + * @return {!Promise} A promise that will be resolved * with the command result. * @template T */ - schedule(command: Command, description: string): promise.Promise; + execute(command: Command, description?: string): Promise; /** * Sets the {@linkplain input.FileDetector file detector} that should be @@ -3638,45 +2162,30 @@ export class WebDriver { */ setFileDetector(detector: FileDetector): void; + getExecutor(): Executor; + /** - * @return {!promise.Promise.} A promise for this + * @return {!Promise.} A promise for this * client's session. */ - getSession(): promise.Promise; + getSession(): Promise; /** - * @return {!promise.Promise.} A promise + * @return {!Promise.} A promise * that will resolve with the this instance's capabilities. */ - getCapabilities(): promise.Promise; + getCapabilities(): Promise; /** * 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. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the command has completed. */ - quit(): promise.Promise; - - /** - * Creates a new action sequence using this driver. The sequence will not be - * scheduled for execution until {@link actions.ActionSequence#perform} is - * called. Example: - * - * driver.actions(). - * mouseDown(element1). - * mouseMove(element2). - * mouseUp(). - * perform(); - * - * @return {!actions.ActionSequence} A new action sequence for this instance. - */ - actions(): ActionSequence; + quit(): Promise; /** - * TEMPORARY API returns old ActionSequence so we can use actions() to - * return the new Actions object. * Creates a new action sequence using this driver. The sequence will not be * scheduled for execution until {@link actions.ActionSequence#perform} is * called. Example: @@ -3689,21 +2198,8 @@ export class WebDriver { * * @return {!actions.ActionSequence} A new action sequence for this instance. */ - axtions(): ActionSequence; + actions(options?: {async: boolean, bridge: boolean}|{async: boolean}|{bridge: boolean}): Actions; - /** - * Creates a new touch sequence using this driver. The sequence will not be - * scheduled for execution until {@link actions.TouchSequence#perform} is - * called. Example: - * - * driver.touchActions(). - * tap(element1). - * doubleTap(element2). - * perform(); - * - * @return {!actions.TouchSequence} A new touch sequence for this instance. - */ - touchActions(): TouchSequence; /** * Schedules a command to execute JavaScript in the context of the currently @@ -3715,8 +2211,8 @@ export class WebDriver { * 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 WebElement}. - * Arrays and objects may also be used as script arguments as long as each item - * adheres to the types previously mentioned. + * 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 @@ -3738,32 +2234,32 @@ export class WebDriver { * * @param {!(string|Function)} script The script to execute. * @param {...*} var_args The arguments to pass to the script. - * @return {!promise.Promise.} A promise that will resolve to the + * @return {!Promise.} A promise that will resolve to the * scripts return value. * @template T */ - executeScript(script: string | Function, ...var_args: any[]): promise.Promise; + executeScript(script: string|Function, ...var_args: any[]): Promise; /** - * 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. + * 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 WebElement}. - * Arrays and objects may also be used as script arguments as long as each item - * adheres to the types previously mentioned. + * 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 {@link #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: + * 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: * * - For a HTML element, the value will resolve to a * {@link WebElement} @@ -3796,9 +2292,9 @@ export class WebDriver { * * __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. + * 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]; @@ -3816,33 +2312,22 @@ export class WebDriver { * * @param {!(string|Function)} script The script to execute. * @param {...*} var_args The arguments to pass to the script. - * @return {!promise.Promise.} A promise that will resolve to the + * @return {!Promise.} A promise that will resolve to the * scripts return value. * @template T */ - executeAsyncScript(script: string | Function, ...var_args: any[]): promise.Promise; + executeAsyncScript(script: string|Function, ...var_args: any[]): Promise; - /** - * Schedules a command to execute a custom function. - * @param {function(...): (T|promise.Promise.)} fn The function to - * execute. - * @param {Object=} opt_scope The object in whose scope to execute the function. - * @param {...*} var_args Any arguments to pass to the function. - * @return {!promise.Promise.} A promise that will be resolved' - * with the function's result. - * @template T - */ - call(fn: (...var_args: any[]) => (T | promise.Promise), opt_scope?: any, ...var_args: any[]): promise.Promise; /** * Schedules a command to wait for a condition to hold. The condition may be * specified by a {@link Condition}, as a custom function, or - * as a {@link promise.Promise}. + * as a {@link Promise}. * * For a {@link Condition} or function, the wait will repeatedly * evaluate the condition until it returns a truthy value. If any errors occur * while evaluating the condition, they will be allowed to propagate. In the - * event a condition returns a {@link promise.Promise promise}, the + * event a condition returns a {@link Promise promise}, the * polling loop will wait for it to be resolved and use the resolved value for * whether the condition has been satisified. Note the resolution time for * a promise is factored into whether a wait has timed out. @@ -3851,21 +2336,21 @@ export class WebDriver { * the wait will return a {@link WebElementPromise} that will resolve to the * element that satisified the condition. * - * *Example:* waiting up to 10 seconds for an element to be present and visible - * on the page. + * *Example:* waiting up to 10 seconds for an element to be present and + * visible on the page. * * var button = driver.wait(until.elementLocated(By.id('foo'), 10000); * button.click(); * * This function may also be used to block the command flow on the resolution - * of a {@link promise.Promise promise}. When given a promise, the - * command will simply wait for its resolution before completing. A timeout may - * be provided to fail the command if the promise does not resolve before the - * timeout expires. + * of a {@link Promise promise}. When given a promise, the + * command will simply wait for its resolution before completing. A timeout + * may be provided to fail the command if the promise does not resolve before + * the timeout expires. * * *Example:* Suppose you have a function, `startTestServer`, that returns a - * promise for when a server is ready for requests. You can block a `WebDriver` - * client on this promise with: + * promise for when a server is ready for requests. You can block a + * `WebDriver` client on this promise with: * * var started = startTestServer(); * driver.wait(started, 5 * 1000, 'Server should start within 5 seconds'); @@ -3882,17 +2367,18 @@ export class WebDriver { * rejected if the condition times out. * @template T */ - wait(condition: WebElementCondition, opt_timeout?: number, opt_message?: string): WebElementPromise; + wait(condition: WebElementCondition, opt_timeout?: number, opt_message?: string): + WebElementPromise; /** * Schedules a command to wait for a condition to hold. The condition may be * specified by a {@link webdriver.Condition}, as a custom function, or - * as a {@link webdriver.promise.Promise}. + * as a {@link Promise}. * * For a {@link webdriver.Condition} or function, the wait will repeatedly * evaluate the condition until it returns a truthy value. If any errors occur * while evaluating the condition, they will be allowed to propagate. In the - * event a condition returns a {@link webdriver.promise.Promise promise}, the + * event a condition returns a {@link Promise promise}, the * polling loop will wait for it to be resolved and use the resolved value for * whether the condition has been satisified. Note the resolution time for * a promise is factored into whether a wait has timed out. @@ -3901,27 +2387,27 @@ export class WebDriver { * the wait will return a {@link WebElementPromise} that will resolve to the * element that satisified the condition. * - * *Example:* waiting up to 10 seconds for an element to be present and visible - * on the page. + * *Example:* waiting up to 10 seconds for an element to be present and + * visible on the page. * * var button = driver.wait(until.elementLocated(By.id('foo'), 10000); * button.click(); * * This function may also be used to block the command flow on the resolution - * of a {@link webdriver.promise.Promise promise}. When given a promise, the - * command will simply wait for its resolution before completing. A timeout may - * be provided to fail the command if the promise does not resolve before the - * timeout expires. + * of a {@link Promise promise}. When given a promise, the + * command will simply wait for its resolution before completing. A timeout + * may be provided to fail the command if the promise does not resolve before + * the timeout expires. * * *Example:* Suppose you have a function, `startTestServer`, that returns a - * promise for when a server is ready for requests. You can block a `WebDriver` - * client on this promise with: + * promise for when a server is ready for requests. You can block a + * `WebDriver` client on this promise with: * * var started = startTestServer(); * driver.wait(started, 5 * 1000, 'Server should start within 5 seconds'); * driver.get(getServerUrl()); * - * @param {!(promise.Promise| + * @param {!(Promise| * Condition| * function(!WebDriver): T)} condition The condition to * wait on, defined as a promise, condition object, or a function to @@ -3929,73 +2415,76 @@ export class WebDriver { * @param {number=} opt_timeout How long to wait for the condition to be true. * @param {string=} opt_message An optional message to use if the wait times * out. - * @return {!promise.Promise} A promise that will be fulfilled + * @return {!Promise} A promise that will be fulfilled * with the first truthy value returned by the condition function, or * rejected if the condition times out. * @template T */ - wait(condition: PromiseLike | Condition | ((driver: WebDriver) => T | PromiseLike) | Function, opt_timeout?: number, opt_message?: string): promise.Promise; + wait( + condition: PromiseLike|Condition|((driver: WebDriver) => T | PromiseLike)|Function, + opt_timeout?: number, opt_message?: string): Promise; /** * Schedules a command to make the driver sleep for the given amount of time. * @param {number} ms The amount of time, in milliseconds, to sleep. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the sleep has finished. */ - sleep(ms: number): promise.Promise; + sleep(ms: number): Promise; /** * Schedules a command to retrieve they current window handle. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the current window handle. */ - getWindowHandle(): promise.Promise; + getWindowHandle(): Promise; /** - * Schedules a command to retrieve the current list of available window handles. - * @return {!promise.Promise.>} A promise that will + * Schedules a command to retrieve the current list of available window + * handles. + * @return {!Promise.>} A promise that will * be resolved with an array of window handles. */ - getAllWindowHandles(): promise.Promise; + getAllWindowHandles(): Promise; /** * 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. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the current page source. */ - getPageSource(): promise.Promise; + getPageSource(): Promise; /** * Schedules a command to close the current window. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when this command has completed. */ - close(): promise.Promise; + close(): Promise; /** * Schedules a command to navigate to the given URL. * @param {string} url The fully qualified URL to open. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the document has finished loading. */ - get(url: string): promise.Promise; + get(url: string): Promise; /** * Schedules a command to retrieve the URL of the current page. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the current URL. */ - getCurrentUrl(): promise.Promise; + getCurrentUrl(): Promise; /** * Schedules a command to retrieve the current page's title. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the current page's title. */ - getTitle(): promise.Promise; + getTitle(): Promise; /** * Schedule a command to find an element on the page. If the element cannot be @@ -4039,10 +2528,10 @@ export class WebDriver { * Schedule a command to search for multiple elements on the page. * * @param {!(by.By|Function)} locator The locator to use. - * @return {!promise.Promise.>} A + * @return {!Promise.>} A * promise that will resolve to an array of WebElements. */ - findElements(locator: Locator): promise.Promise; + findElements(locator: Locator): Promise; /** * Schedule a command to take a screenshot. The driver makes a best effort to @@ -4053,10 +2542,10 @@ export class WebDriver { * 3. Visible portion of the current frame * 4. The entire display containing the browser * - * @return {!promise.Promise} A promise that will be + * @return {!Promise} A promise that will be * resolved to the screenshot as a base-64 encoded PNG. */ - takeScreenshot(): promise.Promise; + takeScreenshot(): Promise; /** * @return {!Options} The options interface for this @@ -4092,14 +2581,12 @@ export class WebDriver { * every issued command will fail. * * @extends {webdriver.IWebDriver} - * @extends {promise.IThenable} + * @extends {Promise} * @interface */ -export interface ThenableWebDriver extends WebDriver, promise.IThenable { } +export interface ThenableWebDriver extends WebDriver, Promise {} -export interface IWebElementId { - [ELEMENT: string]: string; -} +export interface IWebElementId { [ELEMENT: string]: string; } /** * Represents a DOM element. WebElements can be found by searching from the @@ -4129,10 +2616,10 @@ export interface IWebElement { /** * Schedules a command to click on this element. - * @return {!promise.Promise} A promise that will be resolved when + * @return {!Promise} A promise that will be resolved when * the click command has completed. */ - click(): promise.Promise; + click(): Promise; /** * Schedules a command to type a sequence on the DOM element represented by @@ -4164,8 +2651,8 @@ export interface IWebElement { * * If this element is a file input ({@code }), the * specified key sequence should specify the path to the file to attach to - * the element. This is analogous to the user clicking 'Browse...' and entering - * the path into the file select dialog. + * the element. This is analogous to the user clicking 'Browse...' and + * entering the path into the file select dialog. * * var form = driver.findElement(By.css('form')); * var element = form.findElement(By.css('input[type=file]')); @@ -4187,51 +2674,50 @@ export interface IWebElement { * sequence of keys to type. Number keys may be referenced numerically or * by string (1 or '1'). All arguments will be joined into a single * sequence. - * @return {!promise.Promise} A promise that will be resolved when all + * @return {!Promise} A promise that will be resolved when all * keys have been typed. */ - sendKeys(...var_args: Array>): promise.Promise; + sendKeys(...var_args: Array>): Promise; /** * Schedules a command to query for the tag/node name of this element. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * element's tag name. */ - getTagName(): promise.Promise; + getTagName(): Promise; /** * Schedules a command to query for the computed style of the element * represented by this instance. If the element inherits the named style from - * its parent, the parent will be queried for its value. Where possible, color - * values will be converted to their hex representation (e.g. #00ff00 instead of - * rgb(0, 255, 0)). - *

- * Warning: the value returned will be as the browser interprets it, so - * it may be tricky to form a proper assertion. + * its parent, the parent will be queried for its value. Where possible, + * color values will be converted to their hex representation (e.g. #00ff00 + * instead of rgb(0, 255, 0)).

Warning: the value returned will + * be as the browser interprets it, so it may be tricky to form a proper + * assertion. * * @param {string} cssStyleProperty The name of the CSS style property to look * up. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * requested CSS value. */ - getCssValue(cssStyleProperty: string): promise.Promise; + getCssValue(cssStyleProperty: string): Promise; /** * Schedules a command to query for the value of the given attribute of the - * element. Will return the current value even if it has been modified after the - * page has been loaded. More exactly, this method will return the value of the - * given attribute, unless that attribute is not present, in which case the - * value of the property with the same name is returned. If neither value is - * set, null is returned. The 'style' attribute is converted as best can be to a - * text representation with a trailing semi-colon. The following are deemed to - * be 'boolean' attributes and will be returned as thus: - * - *

async, autofocus, autoplay, checked, compact, complete, controls, declare, - * defaultchecked, defaultselected, defer, disabled, draggable, ended, - * formnovalidate, hidden, indeterminate, iscontenteditable, ismap, itemscope, - * loop, multiple, muted, nohref, noresize, noshade, novalidate, nowrap, open, - * paused, pubdate, readonly, required, reversed, scoped, seamless, seeking, - * selected, spellcheck, truespeed, willvalidate + * element. Will return the current value even if it has been modified after + * the page has been loaded. More exactly, this method will return the value + * of the given attribute, unless that attribute is not present, in which case + * the value of the property with the same name is returned. If neither value + * is set, null is returned. The 'style' attribute is converted as best can be + * to a text representation with a trailing semi-colon. The following are + * deemed to be 'boolean' attributes and will be returned as thus: + * + *

async, autofocus, autoplay, checked, compact, complete, controls, + * declare, defaultchecked, defaultselected, defer, disabled, draggable, + * ended, formnovalidate, hidden, indeterminate, iscontenteditable, ismap, + * itemscope, loop, multiple, muted, nohref, noresize, noshade, novalidate, + * nowrap, open, paused, pubdate, readonly, required, reversed, scoped, + * seamless, seeking, selected, spellcheck, truespeed, willvalidate * *

Finally, the following commonly mis-capitalized attribute/property names * are evaluated as expected: @@ -4240,81 +2726,87 @@ export interface IWebElement { *

  • 'readonly' * * @param {string} attributeName The name of the attribute to query. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * attribute's value. */ - getAttribute(attributeName: string): promise.Promise; + getAttribute(attributeName: string): Promise; /** - * Get the visible (i.e. not hidden by CSS) innerText of this element, including - * sub-elements, without any leading or trailing whitespace. - * @return {!promise.Promise} A promise that will be resolved with the + * Get the visible (i.e. not hidden by CSS) innerText of this element, + * including sub-elements, without any leading or trailing whitespace. + * @return {!Promise} A promise that will be resolved with the * element's visible text. */ - getText(): promise.Promise; + getText(): Promise; /** * Schedules a command to compute the size of this element's bounding box, in * pixels. - * @return {!promise.Promise} A promise that will be resolved with the + * @return {!Promise} A promise that will be resolved with the * element's size as a {@code {width:number, height:number}} object. */ - getSize(): promise.Promise; + getSize(): Promise; + + /** + * Returns an object describing an element's location, in pixels relative to + * the document element, and the element's size in pixels. + */ + getRect(): Promise; /** * Schedules a command to compute the location of this element in page space. - * @return {!promise.Promise} A promise that will be resolved to the + * @return {!Promise} A promise that will be resolved to the * element's location as a {@code {x:number, y:number}} object. */ - getLocation(): promise.Promise; + getLocation(): Promise; /** * Schedules a command to query whether the DOM element represented by this * instance is enabled, as dicted by the {@code disabled} attribute. - * @return {!promise.Promise} A promise that will be resolved with + * @return {!Promise} A promise that will be resolved with * whether this element is currently enabled. */ - isEnabled(): promise.Promise; + isEnabled(): Promise; /** * Schedules a command to query whether this element is selected. - * @return {!promise.Promise} A promise that will be resolved with + * @return {!Promise} A promise that will be resolved with * whether this element is currently selected. */ - isSelected(): promise.Promise; + isSelected(): Promise; /** * Schedules a command to submit the form containing this element (or this * element if it is a FORM element). This command is a no-op if the element is * not contained in a form. - * @return {!promise.Promise} A promise that will be resolved when + * @return {!Promise} A promise that will be resolved when * the form has been submitted. */ - submit(): promise.Promise; + submit(): Promise; /** - * Schedules a command to clear the {@code value} of this element. This command - * has no effect if the underlying DOM element is neither a text INPUT element - * nor a TEXTAREA element. - * @return {!promise.Promise} A promise that will be resolved when + * Schedules a command to clear the {@code value} of this element. This + * command has no effect if the underlying DOM element is neither a text INPUT + * element nor a TEXTAREA element. + * @return {!Promise} A promise that will be resolved when * the element has been cleared. */ - clear(): promise.Promise; + clear(): Promise; /** * Schedules a command to test whether this element is currently displayed. - * @return {!promise.Promise} A promise that will be resolved with + * @return {!Promise} A promise that will be resolved with * whether this element is currently visible on the page. */ - isDisplayed(): promise.Promise; + isDisplayed(): Promise; /** - * @return {!promise.Promise.} A promise + * @return {!Promise.} A promise * that resolves to this element's JSON representation as defined by the * WebDriver wire protocol. * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol */ - getId(): promise.Promise; + getId(): Promise; // endregion } @@ -4368,10 +2860,10 @@ export interface IWebElementFinders { * * @param {!(Locator|By.Hash|Function)} locator The * locator strategy to use when searching for the elements. - * @return {!promise.Promise.>} A + * @return {!Promise.>} A * promise that will resolve to an array of WebElements. */ - findElements(locator: Locator): promise.Promise; + findElements(locator: Locator): Promise; } /** @@ -4391,9 +2883,10 @@ export interface Serializable { * * @return {!(T|IThenable.)} This instance's serialized wire format. */ - serialize(): T | promise.IThenable; + serialize(): T|Promise; } + /** * Represents a DOM element. WebElements can be found by searching from the * document root using a {@link WebDriver} instance, or by searching @@ -4423,14 +2916,14 @@ export class WebElement implements Serializable { * @param {(!IThenable|string)} id The server-assigned opaque ID for * the underlying DOM element. */ - constructor(driver: WebDriver, id: promise.Promise | string); + constructor(driver: WebDriver, id: Promise|string); /** * @param {string} id The raw ID. * @param {boolean=} opt_noLegacy Whether to exclude the legacy element key. * @return {!Object} The element ID for use with WebDriver's wire protocol. */ - static buildId(id: string, opt_noLegacy?: boolean): Object; + static buildId(id: string, opt_noLegacy?: boolean): IWebElementId; /** * Extracts the encoded WebElement ID from the object. @@ -4452,10 +2945,10 @@ export class WebElement implements Serializable { * * @param {!WebElement} a A WebElement. * @param {!WebElement} b A WebElement. - * @return {!promise.Promise} A promise that will be + * @return {!Promise} A promise that will be * resolved to whether the two WebElements are equal. */ - static equals(a: WebElement, b: WebElement): promise.Promise; + static equals(a: WebElement, b: WebElement): Promise; /** * @return {!WebDriver} The parent driver for this instance. @@ -4463,10 +2956,10 @@ export class WebElement implements Serializable { getDriver(): WebDriver; /** - * @return {!promise.Promise} A promise that resolves to + * @return {!Promise} A promise that resolves to * the server-assigned opaque ID assigned to this element. */ - getId(): promise.Promise; + getId(): Promise; /** * Schedule a command to find a descendant of this element. If the element @@ -4514,28 +3007,29 @@ export class WebElement implements Serializable { * * @param {!(by.By|Function)} locator The locator strategy to use when * searching for the element. - * @return {!promise.Promise>} A + * @return {!Promise>} A * promise that will resolve to an array of WebElements. */ - findElements(locator: Locator): promise.Promise; + findElements(locator: Locator): Promise; /** * Schedules a command to click on this element. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the click command has completed. */ - click(): promise.Promise; + click(): Promise; /** - * Schedules a command to type a sequence on the DOM element represented by this - * promsieinstance. + * Schedules a command to type a sequence on the DOM element represented by + * this promsieinstance. * * Modifier keys (SHIFT, CONTROL, ALT, META) are stateful; once a modifier is * processed in the keysequence, that key state is toggled until one of the * following occurs: * * - The modifier key is encountered again in the sequence. At this point the - * state of the key is toggled (along with the appropriate keyup/down events). + * state of the key is toggled (along with the appropriate keyup/down + * events). * - The {@link Key.NULL} key is encountered in the sequence. When * this key is encountered, all modifier keys current in the down state are * released (with accompanying keyup events). The NULL key can be used to @@ -4550,8 +3044,8 @@ export class WebElement implements Serializable { * 'now text is'); * * - The end of the keysequence is encountered. When there are no more keys - * to type, all depressed modifier keys are released (with accompanying keyup - * events). + * to type, all depressed modifier keys are released (with accompanying + * keyup events). * * If this element is a file input ({@code }), the * specified key sequence should specify the path to the file to attach to @@ -4574,44 +3068,44 @@ export class WebElement implements Serializable { * punctionation keys will be synthesized according to a standard QWERTY en-us * keyboard layout. * - * @param {...(string|!promise.Promise)} var_args The sequence + * @param {...(string|!Promise)} var_args The sequence * of keys to type. All arguments will be joined into a single sequence. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when all keys have been typed. */ - sendKeys(...var_args: Array>): promise.Promise; + sendKeys(...var_args: Array>): Promise; /** * Schedules a command to query for the tag/node name of this element. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the element's tag name. */ - getTagName(): promise.Promise; + getTagName(): Promise; /** * Schedules a command to query for the computed style of the element * represented by this instance. If the element inherits the named style from - * its parent, the parent will be queried for its value. Where possible, color - * values will be converted to their hex representation (e.g. #00ff00 instead of - * rgb(0, 255, 0)). + * its parent, the parent will be queried for its value. Where possible, + * color values will be converted to their hex representation (e.g. #00ff00 + * instead of rgb(0, 255, 0)). * * _Warning:_ the value returned will be as the browser interprets it, so * it may be tricky to form a proper assertion. * * @param {string} cssStyleProperty The name of the CSS style property to look * up. - * @return {!promise.Promise} A promise that will be + * @return {!Promise} A promise that will be * resolved with the requested CSS value. */ - getCssValue(cssStyleProperty: string): promise.Promise; + getCssValue(cssStyleProperty: string): Promise; /** * Schedules a command to query for the value of the given attribute of the * element. Will return the current value, even if it has been modified after - * the page has been loaded. More exactly, this method will return the value of - * the given attribute, unless that attribute is not present, in which case the - * value of the property with the same name is returned. If neither value is - * set, null is returned (for example, the 'value' property of a textarea + * the page has been loaded. More exactly, this method will return the value + * of the given attribute, unless that attribute is not present, in which case + * the value of the property with the same name is returned. If neither value + * is set, null is returned (for example, the 'value' property of a textarea * element). The 'style' attribute is converted as best can be to a * text representation with a trailing semi-colon. The following are deemed to * be 'boolean' attributes and will return either 'true' or null: @@ -4630,76 +3124,84 @@ export class WebElement implements Serializable { * - 'readonly' * * @param {string} attributeName The name of the attribute to query. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with the attribute's value. The returned value will always be * either a string or null. */ - getAttribute(attributeName: string): promise.Promise; + getAttribute(attributeName: string): Promise; /** - * Get the visible (i.e. not hidden by CSS) innerText of this element, including - * sub-elements, without any leading or trailing whitespace. - * @return {!promise.Promise.} A promise that will be + * Get the visible (i.e. not hidden by CSS) innerText of this element, + * including sub-elements, without any leading or trailing whitespace. + * @return {!Promise.} A promise that will be * resolved with the element's visible text. */ - getText(): promise.Promise; + getText(): Promise; /** + * DEPRECATED 3.0 * Schedules a command to compute the size of this element's bounding box, in * pixels. - * @return {!promise.Promise.<{width: number, height: number}>} A + * @return {!Promise.<{width: number, height: number}>} A * promise that will be resolved with the element's size as a * {@code {width:number, height:number}} object. */ - getSize(): promise.Promise; + getSize(): Promise; /** + * Returns an object describing an element's location, in pixels relative to + * the document element, and the element's size in pixels. + */ + getRect(): Promise; + + /** + * DEPRECATED 3.0 * Schedules a command to compute the location of this element in page space. - * @return {!promise.Promise.<{x: number, y: number}>} A promise that + * @return {!Promise.<{x: number, y: number}>} A promise that * will be resolved to the element's location as a * {@code {x:number, y:number}} object. */ - getLocation(): promise.Promise; + getLocation(): Promise; /** * Schedules a command to query whether the DOM element represented by this * instance is enabled, as dicted by the {@code disabled} attribute. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with whether this element is currently enabled. */ - isEnabled(): promise.Promise; + isEnabled(): Promise; /** * Schedules a command to query whether this element is selected. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with whether this element is currently selected. */ - isSelected(): promise.Promise; + isSelected(): Promise; /** * Schedules a command to submit the form containing this element (or this * element if it is a FORM element). This command is a no-op if the element is * not contained in a form. - * @return {!promise.Promise.} A promise that will be resolved + * @return {!Promise.} A promise that will be resolved * when the form has been submitted. */ - submit(): promise.Promise; + submit(): Promise; /** * Schedules a command to clear the `value` of this element. This command has * no effect if the underlying DOM element is neither a text INPUT element * nor a TEXTAREA element. - * @return {!promise.Promise} A promise that will be resolved + * @return {!Promise} A promise that will be resolved * when the element has been cleared. */ - clear(): promise.Promise; + clear(): Promise; /** * Schedules a command to test whether this element is currently displayed. - * @return {!promise.Promise.} A promise that will be + * @return {!Promise.} A promise that will be * resolved with whether this element is currently visible on the page. */ - isDisplayed(): promise.Promise; + isDisplayed(): Promise; /** * Take a screenshot of the visible region encompassed by this element's @@ -4708,13 +3210,13 @@ export class WebElement implements Serializable { * @param {boolean=} opt_scroll Optional argument that indicates whether the * element should be scrolled into view before taking a screenshot. * Defaults to false. - * @return {!promise.Promise} A promise that will be + * @return {!Promise} A promise that will be * resolved to the screenshot as a base-64 encoded PNG. */ - takeScreenshot(opt_scroll?: boolean): promise.Promise; + takeScreenshot(opt_scroll?: boolean): Promise; /** @override */ - serialize(): promise.Promise; + serialize(): Promise; } /** @@ -4732,22 +3234,26 @@ export class WebElement implements Serializable { * * @param {!WebDriver} driver The parent WebDriver instance for this * element. - * @param {!promise.Promise.} el A promise + * @param {!Promise.} el A promise * that will resolve to the promised element. * @constructor * @extends {WebElement} * @implements {promise.Thenable.} * @final */ -export interface WebElementPromise extends promise.IThenable {} +export interface WebElementPromise extends Promise {} + +/** + * Implement WebElementPromise + */ export class WebElementPromise extends WebElement { /** * @param {!WebDriver} driver The parent WebDriver instance for this * element. - * @param {!promise.Promise} el A promise + * @param {!Promise} el A promise * that will resolve to the promised element. */ - constructor(driver: WebDriver, el: promise.Promise); + constructor(driver: WebDriver, el: Promise); } /** @@ -4762,7 +3268,7 @@ export class Session { * capabilities. * @constructor */ - constructor(id: string, capabilities: Capabilities | Object); + constructor(id: string, capabilities: Capabilities|{}); // endregion @@ -4794,9 +3300,3 @@ export class Session { // endregion } - -// google3 local modification: -} // The close brace for "namespace webdriver" -} // The closing brace for "declare global" -export = webdriver; -// end google3 local modification. diff --git a/lib/selenium-webdriver/lib/by.d.ts b/lib/selenium-webdriver/lib/by.d.ts new file mode 100644 index 000000000..67eca22ae --- /dev/null +++ b/lib/selenium-webdriver/lib/by.d.ts @@ -0,0 +1,140 @@ +import {Locator, WebDriver} from '../'; + +/** + * Typings for lib/by.js + * Describes a mechanism for locating an element on the page. + * @final + */ +export class By { + /** + * @param {string} using the name of the location strategy to use. + * @param {string} value the value to search for. + */ + constructor(using: string, value: string); + + using: string; + value: string; + + /** + * Locates elements that have a specific class name. + * + * @param {string} name The class name to search for. + * @return {!By} The new locator. + * @see http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes + * @see http://www.w3.org/TR/CSS2/selector.html#class-html + */ + static className(name: string): By; + + /** + * Locates elements using a CSS selector. + * + * @param {string} selector The CSS selector to use. + * @return {!By} The new locator. + * @see http://www.w3.org/TR/CSS2/selector.html + */ + static css(selector: string): By; + + /** + * Locates eleemnts by the ID attribute. This locator uses the CSS selector + * `*[id='$ID']`, _not_ `document.getElementById`. + * + * @param {string} id The ID to search for. + * @return {!By} The new locator. + */ + static id(id: string): By; + + /** + * Locates link elements whose + * {@linkplain WebElement#getText visible text} matches the given + * string. + * + * @param {string} text The link text to search for. + * @return {!By} The new locator. + */ + static linkText(text: string): By; + + /** + * Locates an elements by evaluating a + * {@linkplain WebDriver#executeScript JavaScript expression}. + * The result of this expression must be an element or list of elements. + * + * @param {!(string|Function)} script The script to execute. + * @param {...*} var_args The arguments to pass to the script. + * @return {function(!./WebDriver): !./Promise} + * A new JavaScript-based locator function. + */ + static js(script: string|Function, ...var_args: any[]): (webdriver: WebDriver) => Promise; + + /** + * Locates elements whose `name` attribute has the given value. + * + * @param {string} name The name attribute to search for. + * @return {!By} The new locator. + */ + static name(name: string): By; + + /** + * Locates link elements whose + * {@linkplain WebElement#getText visible text} contains the given + * substring. + * + * @param {string} text The substring to check for in a link's visible text. + * @return {!By} The new locator. + */ + static partialLinkText(text: string): By; + + /** + * Locates elements with a given tag name. + * + * @param {string} name The tag name to search for. + * @return {!By} The new locator. + * @deprecated Use {@link By.css() By.css(tagName)} instead. + */ + static tagName(name: string): By; + + /** + * Locates elements matching a XPath selector. Care should be taken when + * using an XPath selector with a {@link WebElement} as WebDriver + * will respect the context in the specified in the selector. For example, + * given the selector `//div`, WebDriver will search from the document root + * regardless of whether the locator was used with a WebElement. + * + * @param {string} xpath The XPath selector to use. + * @return {!By} The new locator. + * @see http://www.w3.org/TR/xpath/ + */ + static xpath(xpath: string): By; + + /** @override */ + toString(): string; +} + +/** + * Short-hand expressions for the primary element locator strategies. + * For example the following two statements are equivalent: + * + * var e1 = driver.findElement(By.id('foo')); + * var e2 = driver.findElement({id: 'foo'}); + * + * Care should be taken when using JavaScript minifiers (such as the + * Closure compiler), as locator hashes will always be parsed using + * the un-obfuscated properties listed. + * + * @typedef {( + * {className: string}| + * {css: string}| + * {id: string}| + * {js: string}| + * {linkText: string}| + * {name: string}| + * {partialLinkText: string}| + * {tagName: string}| + * {xpath: string})} + */ +export type ByHash = { + className: string +} | {css: string} | + {id: string} | {js: string} | {linkText: string} | {name: string} | {partialLinkText: string} | + {tagName: string} | {xpath: string}; + +export function checkedLocator(locator: Locator): By; diff --git a/lib/selenium-webdriver/lib/command.d.ts b/lib/selenium-webdriver/lib/command.d.ts new file mode 100644 index 000000000..31fc463c2 --- /dev/null +++ b/lib/selenium-webdriver/lib/command.d.ts @@ -0,0 +1,204 @@ +// tslint:disable:variable-name third_party + + +/** + * An enumeration of valid command string. + */ +export interface ICommandName { + GET_SERVER_STATUS: string; + + NEW_SESSION: string; + GET_SESSIONS: string; + DESCRIBE_SESSION: string; + + CLOSE: string; + QUIT: string; + + GET_CURRENT_URL: string; + GET: string; + GO_BACK: string; + GO_FORWARD: string; + REFRESH: string; + + ADD_COOKIE: string; + GET_COOKIE: string; + GET_ALL_COOKIES: string; + DELETE_COOKIE: string; + DELETE_ALL_COOKIES: string; + + GET_ACTIVE_ELEMENT: string; + FIND_ELEMENT: string; + FIND_ELEMENTS: string; + FIND_CHILD_ELEMENT: string; + FIND_CHILD_ELEMENTS: string; + + CLEAR_ELEMENT: string; + CLICK_ELEMENT: string; + SEND_KEYS_TO_ELEMENT: string; + SUBMIT_ELEMENT: string; + + GET_CURRENT_WINDOW_HANDLE: string; + GET_WINDOW_HANDLES: string; + GET_WINDOW_POSITION: string; + SET_WINDOW_POSITION: string; + GET_WINDOW_SIZE: string; + SET_WINDOW_SIZE: string; + MAXIMIZE_WINDOW: string; + + SWITCH_TO_WINDOW: string; + SWITCH_TO_FRAME: string; + GET_PAGE_SOURCE: string; + GET_TITLE: string; + + EXECUTE_SCRIPT: string; + EXECUTE_ASYNC_SCRIPT: string; + + GET_ELEMENT_TEXT: string; + GET_ELEMENT_TAG_NAME: string; + IS_ELEMENT_SELECTED: string; + IS_ELEMENT_ENABLED: string; + IS_ELEMENT_DISPLAYED: string; + GET_ELEMENT_LOCATION: string; + GET_ELEMENT_LOCATION_IN_VIEW: string; + GET_ELEMENT_SIZE: string; + GET_ELEMENT_ATTRIBUTE: string; + GET_ELEMENT_VALUE_OF_CSS_PROPERTY: string; + ELEMENT_EQUALS: string; + + SCREENSHOT: string; + IMPLICITLY_WAIT: string; + SET_SCRIPT_TIMEOUT: string; + SET_TIMEOUT: string; + + ACCEPT_ALERT: string; + DISMISS_ALERT: string; + GET_ALERT_TEXT: string; + SET_ALERT_TEXT: string; + + EXECUTE_SQL: string; + GET_LOCATION: string; + SET_LOCATION: string; + GET_APP_CACHE: string; + GET_APP_CACHE_STATUS: string; + CLEAR_APP_CACHE: string; + IS_BROWSER_ONLINE: string; + SET_BROWSER_ONLINE: string; + + GET_LOCAL_STORAGE_ITEM: string; + GET_LOCAL_STORAGE_KEYS: string; + SET_LOCAL_STORAGE_ITEM: string; + REMOVE_LOCAL_STORAGE_ITEM: string; + CLEAR_LOCAL_STORAGE: string; + GET_LOCAL_STORAGE_SIZE: string; + + GET_SESSION_STORAGE_ITEM: string; + GET_SESSION_STORAGE_KEYS: string; + SET_SESSION_STORAGE_ITEM: string; + REMOVE_SESSION_STORAGE_ITEM: string; + CLEAR_SESSION_STORAGE: string; + GET_SESSION_STORAGE_SIZE: string; + + SET_SCREEN_ORIENTATION: string; + GET_SCREEN_ORIENTATION: string; + + // These belong to the Advanced user interactions - an element is + // optional for these commands. + CLICK: string; + DOUBLE_CLICK: string; + MOUSE_DOWN: string; + MOUSE_UP: string; + MOVE_TO: string; + SEND_KEYS_TO_ACTIVE_ELEMENT: string; + + // These belong to the Advanced Touch API + TOUCH_SINGLE_TAP: string; + TOUCH_DOWN: string; + TOUCH_UP: string; + TOUCH_MOVE: string; + TOUCH_SCROLL: string; + TOUCH_DOUBLE_TAP: string; + TOUCH_LONG_PRESS: string; + TOUCH_FLICK: string; + + GET_AVAILABLE_LOG_TYPES: string; + GET_LOG: string; + GET_SESSION_LOGS: string; + + UPLOAD_FILE: string; + + ACTIONS: string; + CLEAR_ACTIONS: string; + + LEGACY_ACTION_CLICK: string; + LEGACY_ACTION_DOUBLE_CLICK: string; + LEGACY_ACTION_MOUSE_DOWN: string; + LEGACY_ACTION_MOUSE_UP: string; + LEGACY_ACTION_MOUSE_MOVE: string; + LEGACY_ACTION_SEND_KEYS: string; + LEGACY_ACTION_TOUCH_DOWN: string; + LEGACY_ACTION_TOUCH_UP: string; + LEGACY_ACTION_TOUCH_MOVE: string; + LEGACY_ACTION_TOUCH_SCROLL: string; + LEGACY_ACTION_TOUCH_LONG_PRESS: string; + LEGACY_ACTION_TOUCH_FLICK: string; + LEGACY_ACTION_TOUCH_SINGLE_TAP: string; + LEGACY_ACTION_TOUCH_DOUBLE_TAP: string; +} + +/** + * The names of Command-s + */ +export const Name: ICommandName; + +/** + * Describes a command to be executed by the WebDriverJS framework. + * @param {!CommandName} name The name of this command. + * @constructor + */ +export class Command { + // region Constructors + + /** + * @param {!CommandName} name The name of this command. + * @constructor + */ + constructor(name: string); + + // endregion + + // region Methods + + /** + * @return {!CommandName} This command's name. + */ + getName(): string; + + /** + * Sets a parameter to send with this command. + * @param {string} name The parameter name. + * @param {*} value The parameter value. + * @return {!Command} A self reference. + */ + setParameter(name: string, value: any): Command; + + /** + * Sets the parameters for this command. + * @param {!Object.<*>} parameters The command parameters. + * @return {!Command} A self reference. + */ + setParameters(parameters: any): Command; + + /** + * Returns a named command parameter. + * @param {string} key The parameter key to look up. + * @return {*} The parameter value, or undefined if it has not been set. + */ + getParameter(key: string): any; + + /** + * @return {!Object.<*>} The parameters to send with this command. + */ + getParameters(): any; + + // endregion +} diff --git a/lib/selenium-webdriver/lib/input.d.ts b/lib/selenium-webdriver/lib/input.d.ts new file mode 100644 index 000000000..4884c39e8 --- /dev/null +++ b/lib/selenium-webdriver/lib/input.d.ts @@ -0,0 +1,360 @@ +/** selenium-webdriver lib/inputjs Typings */ +import {Executor, ILocation, WebDriver, WebElement} from '../'; + +// tslint:disable:variable-name third_party + +/** + * Defines the reference point from which to compute offsets for + * {@linkplain ./input.Pointer#move pointer move} actions. + */ +export enum Origin { + /** Compute offsets relative to the pointer's current position. */ + POINTER = 'pointer', + /** Compute offsets relative to the viewport. */ + VIEWPORT = 'viewport', +} + +/** + * Enumeration of the buttons used in the advanced interactions API. + */ +export enum Button { + LEFT = 0, + MIDDLE = 1, + RIGHT = 2, +} + +export interface IKey { + NULL: string; + CANCEL: string; // ^break + HELP: string; + BACK_SPACE: string; + TAB: string; + CLEAR: string; + RETURN: string; + ENTER: string; + SHIFT: string; + CONTROL: string; + ALT: string; + PAUSE: string; + ESCAPE: string; + SPACE: string; + PAGE_UP: string; + PAGE_DOWN: string; + END: string; + HOME: string; + ARROW_LEFT: string; + LEFT: string; + ARROW_UP: string; + UP: string; + ARROW_RIGHT: string; + RIGHT: string; + ARROW_DOWN: string; + DOWN: string; + INSERT: string; + DELETE: string; + SEMICOLON: string; + EQUALS: string; + + NUMPAD0: string; // number pad keys + NUMPAD1: string; + NUMPAD2: string; + NUMPAD3: string; + NUMPAD4: string; + NUMPAD5: string; + NUMPAD6: string; + NUMPAD7: string; + NUMPAD8: string; + NUMPAD9: string; + MULTIPLY: string; + ADD: string; + SEPARATOR: string; + SUBTRACT: string; + DECIMAL: string; + DIVIDE: string; + + F1: string; // function keys + F2: string; + F3: string; + F4: string; + F5: string; + F6: string; + F7: string; + F8: string; + F9: string; + F10: string; + F11: string; + F12: string; + + COMMAND: string; // Apple command key + META: string; // alias for Windows key + + /** + * Simulate pressing many keys at once in a 'chord'. Takes a sequence of + * keys or strings, appends each of the values to a string, + * and adds the chord termination key ({@link Key.NULL}) and returns + * the resulting string. + * + * Note: when the low-level webdriver key handlers see Keys.NULL, active + * modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event. + * + * @param {...string} var_args The key sequence to concatenate. + * @return {string} The null-terminated key sequence. + */ + chord(...var_args: Array): string; +} + +/** + * Representations of pressable keys that aren't text. These are stored in + * the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF. Refer to + * http://www.google.com.au/search?&q=unicode+pua&btnG=Search + * + * @enum {string} + */ +export const Key: IKey; + + +interface IDirection { + x?: number|undefined; + y?: number|undefined; + duration?: number|undefined; + origin?: Origin|WebElement|undefined; +} + +export const INTERNAL_COMPUTE_OFFSET_SCRIPT: string; + + +export class Device { constructor(type: string, id: string); } + +export class Pointer extends Device {} +export class Keyboard extends Device {} + +/** + * Class for defining sequences of complex user interactions. Each sequence + * will not be executed until {@link #perform} is called. + * + * Example: + * + * new Actions(driver). + * keyDown(Key.SHIFT). + * click(element1). + * click(element2). + * dragAndDrop(element3, element4). + * keyUp(Key.SHIFT). + * perform(); + * + */ +export class Actions { + // region Constructors + + constructor(executor: Executor, options?: {async: boolean, + bridge: boolean}|{async: boolean}|{bridge: boolean}); + + // endregion + + // region Methods + keyboard(): Keyboard; + mouse(): Pointer; + /** + * Executes this action sequence. + * @return {!Promise} A promise that will be resolved once + * this sequence has completed. + */ + clear(): Promise; + + /** + * Executes this action sequence. + * @return {!Promise} A promise that will be resolved once + * this sequence has completed. + */ + perform(): Promise; + + pause(duration?: number|Device, ...devices: Device[]): Actions; + + /** + * Inserts an action to press a mouse button at the mouse's current location. + * Defaults to `LEFT`. + */ + press(button?: Button): Actions; + + /** + * Inserts an action to release a mouse button at the mouse's current + * location. Defaults to `LEFT`. + */ + release(button?: Button): Actions; + + /** + * Inserts an action for moving the mouse `x` and `y` pixels relative to the + * specified `origin`. The `origin` may be defined as the mouse's + * {@linkplain ./input.Origin.POINTER current position}, the + * {@linkplain ./input.Origin.VIEWPORT viewport}, or the center of a specific + * {@linkplain ./webdriver.WebElement WebElement}. + * + * You may adjust how long the remote end should take, in milliseconds, to + * perform the move using the `duration` parameter (defaults to 100 ms). + * The number of incremental move events generated over this duration is an + * implementation detail for the remote end. + * + * Defaults to moving the mouse to the top-left + * corner of the viewport over 100ms. + */ + move(direction: IDirection): Actions; + + /** + * Moves the mouse. The location to move to may be specified in terms of the + * mouse's current location, an offset relative to the top-left corner of an + * element, or an element (in which case the middle of the element is used). + * + * @param {(!./WebElement|{x: number, y: number})} location The + * location to drag to, as either another WebElement or an offset in + * pixels. + * @param {{x: number, y: number}=} opt_offset If the target {@code location} + * is defined as a {@link ./WebElement}, this parameter defines + * an offset within that element. The offset should be specified in pixels + * relative to the top-left corner of the element's bounding box. If + * omitted, the element's center will be used as the target offset. + * @return {!Actions} A self reference. + */ + mouseMove(location: WebElement|ILocation, opt_offset?: ILocation): Actions; + + /** + * Presses a mouse button. The mouse button will not be released until + * {@link #mouseUp} is called, regardless of whether that call is made in this + * sequence or another. The behavior for out-of-order events (e.g. mouseDown, + * click) is undefined. + * + * If an element is provided, the mouse will first be moved to the center + * of that element. This is equivalent to: + * + * sequence.mouseMove(element).mouseDown() + * + * Warning: this method currently only supports the left mouse button. See + * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). + * + * @param {(./WebElement|input.Button)=} opt_elementOrButton Either + * the element to interact with or the button to click with. + * Defaults to {@link input.Button.LEFT} if neither an element nor + * button is specified. + * @param {input.Button=} opt_button The button to use. Defaults to + * {@link input.Button.LEFT}. Ignored if a button is provided as the + * first argument. + * @return {!Actions} A self reference. + */ + mouseDown(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions; + + /** + * Releases a mouse button. Behavior is undefined for calling this function + * without a previous call to {@link #mouseDown}. + * + * If an element is provided, the mouse will first be moved to the center + * of that element. This is equivalent to: + * + * sequence.mouseMove(element).mouseUp() + * + * Warning: this method currently only supports the left mouse button. See + * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). + * + * @param {(./WebElement|input.Button)=} opt_elementOrButton Either + * the element to interact with or the button to click with. + * Defaults to {@link input.Button.LEFT} if neither an element nor + * button is specified. + * @param {input.Button=} opt_button The button to use. Defaults to + * {@link input.Button.LEFT}. Ignored if a button is provided as the + * first argument. + * @return {!Actions} A self reference. + */ + mouseUp(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions; + + /** + * Convenience function for performing a 'drag and drop' manuever. The target + * element may be moved to the location of another element, or by an offset (in + * pixels). + */ + dragAndDrop(from: WebElement, to?: WebElement|{x?: number | string, y?: number|string}|null): + Actions; + + /** + * Clicks a mouse button. + * + * If an element is provided, the mouse will first be moved to the center + * of that element. This is equivalent to: + * + * sequence.mouseMove(element).click() + * + * @param {(./WebElement|input.Button)=} opt_elementOrButton Either + * the element to interact with or the button to click with. + * Defaults to {@link input.Button.LEFT} if neither an element nor + * button is specified. + * @param {input.Button=} opt_button The button to use. Defaults to + * {@link input.Button.LEFT}. Ignored if a button is provided as the + * first argument. + * @return {!Actions} A self reference. + */ + click(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions; + + /** + * Double-clicks a mouse button. + * + * If an element is provided, the mouse will first be moved to the center of + * that element. This is equivalent to: + * + * sequence.mouseMove(element).doubleClick() + * + * Warning: this method currently only supports the left mouse button. See + * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047). + * + * @param {(./WebElement|input.Button)=} opt_elementOrButton Either + * the element to interact with or the button to click with. + * Defaults to {@link input.Button.LEFT} if neither an element nor + * button is specified. + * @param {input.Button=} opt_button The button to use. Defaults to + * {@link input.Button.LEFT}. Ignored if a button is provided as the + * first argument. + * @return {!Actions} A self reference. + */ + doubleClick(opt_elementOrButton?: WebElement|string, opt_button?: string): Actions; + + /** + * Short-hand for performing a simple right-click (down/up) with the mouse. + * + * @param {./webdriver.WebElement=} element If specified, the mouse will + * first be moved to the center of the element before performing the + * click. + * @return {!Actions} a self reference. + */ + contextClick(opt_elementOrButton?: WebElement|string): Actions; + + /** + * Performs a modifier key press. The modifier key is not released + * until {@link #keyUp} or {@link #sendKeys} is called. The key press will be + * targetted at the currently focused element. + * @param {!Key} key The modifier key to push. Must be one of + * {ALT, CONTROL, SHIFT, COMMAND, META}. + * @return {!Actions} A self reference. + * @throws {Error} If the key is not a valid modifier key. + */ + keyDown(key: string): Actions; + + /** + * Performs a modifier key release. The release is targetted at the currently + * focused element. + * @param {!Key} key The modifier key to release. Must be one of + * {ALT, CONTROL, SHIFT, COMMAND, META}. + * @return {!Actions} A self reference. + * @throws {Error} If the key is not a valid modifier key. + */ + keyUp(key: string): Actions; + + /** + * Simulates typing multiple keys. Each modifier key encountered in the + * sequence will not be released until it is encountered again. All key events + * will be targeted at the currently focused element. + * + * @param {...(string|!input.Key|!Array<(string|!input.Key)>)} var_args + * The keys to type. + * @return {!Actions} A self reference. + * @throws {Error} If the key is not a valid modifier key. + */ + sendKeys(...var_args: Array>): Actions; + + // endregion +} diff --git a/lib/selenium-webdriver/lib/promise.d.ts b/lib/selenium-webdriver/lib/promise.d.ts new file mode 100644 index 000000000..6d8cb792e --- /dev/null +++ b/lib/selenium-webdriver/lib/promise.d.ts @@ -0,0 +1,129 @@ +/** + * Typings for lib/promise.js + */ + +// tslint:disable:interface-name 3rd party code +// tslint:disable:variable-name 3rd party code + + +import {EventEmitter} from '../'; + +/** + * promise + */ + +export namespace promise { + // region Functions + + /** + * Determines whether a {@code value} should be treated as a promise. + * Any object whose 'then' property is a function will be considered a + * promise. + */ + function isPromise(value: any): boolean; + + /** + * Creates a promise that will be resolved at a set time in the future. + */ + function delayed(ms: number): Promise; + + /** + * Calls a function for each element in an array, and if the function returns + * true adds the element to a new array. + * + * If the return value of the filter function is a promise, this function + * will wait for it to be fulfilled before determining whether to insert the + * element into the new array. + * + * If the filter function throws or returns a rejected promise, the promise + * returned by this function will be rejected with the same reason. Only the + * first failure will be reported; all subsequent errors will be silently + * ignored. + */ + function filter( + arr: T[]|Promise, fn: (element: T, index: number, array: T[]) => V, + // tslint:disable-next-line:no-any The type of archaic `self` adds no + // value + optSelf?: any): Promise; + + /** + * Calls a function for each element in an array and inserts the result into a + * new array, which is used as the fulfillment value of the promise returned + * by this function. + * + * If the return value of the mapping function is a promise, this function + * will wait for it to be fulfilled before inserting it into the new array. + * + * If the mapping function throws or returns a rejected promise, the + * promise returned by this function will be rejected with the same reason. + * Only the first failure will be reported; all subsequent errors will be + * silently ignored. + */ + // tslint:disable-next-line:no-any The type of archaic `self` adds no value + function map( + arr: T[]|Promise, fn: (self: any, type: T, index: number, array: T[]) => V, + optSelf?: any): Promise; + + /** + * Wraps a function that expects a node-style callback as its final + * argument. This callback expects two arguments: an error value (which will + * be null if the call succeeded), and the success value as the second + * argument. The callback will the resolve or reject the returned promise, + * based on its arguments. + */ + // tslint:disable-next-line:no-any Variable args have variable types. + function checkedNodeCall(fn: Function, ...varArgs: any[]): Promise; + + + /** + * Returns a promise that will be resolved with the input value in a + * fully-resolved state. If the value is an array, each element will be fully + * resolved. Likewise, if the value is an object, all keys will be fully + * resolved. In both cases, all nested arrays and objects will also be + * fully resolved. All fields are resolved in place; the returned promise + * will resolve on {@code value} and not a copy. + * + * Warning: This function makes no checks against objects that contain + * cyclical references: + * + * var value = {}; + * value['self'] = value; + * promise.fullyResolved(value); // Stack overflow. + */ + // tslint:disable-next-line:no-any Complex relation between input and output + function fullyResolved(value: any): Promise; + + /** + * Registers a listener to invoke when a promise is resolved, regardless + * of whether the promise's value was successfully computed. This function + * is synonymous with the {@code finally} clause in a synchronous API: + * + * // Synchronous API: + * try { + * doSynchronousWork(); + * } finally { + * cleanUp(); + * } + * + * // Asynchronous promise API: + * doAsynchronousWork().finally(cleanUp); + * + * __Note:__ similar to the {@code finally} clause, if the registered + * callback returns a rejected promise or throws an error, it will silently + * replace the rejection error (if any) from this promise: + * + * try { + * throw Error('one'); + * } finally { + * throw Error('two'); // Hides Error: one + * } + * + * let p = Promise.reject(Error('one')); + * promise.finally(p, function() { + * throw Error('two'); // Hides Error: one + * }); + */ + function thenFinally(promise: any, callback: () => R | Promise): Promise; + + // endregion +} diff --git a/lib/selenium-webdriver/lib/until.d.ts b/lib/selenium-webdriver/lib/until.d.ts new file mode 100644 index 000000000..d64b348eb --- /dev/null +++ b/lib/selenium-webdriver/lib/until.d.ts @@ -0,0 +1,208 @@ +import {Alert, By, ByHash, Condition, Locator, WebDriver, WebElement, WebElementCondition} from '../'; + + +/** + * Creates a condition that will wait until the input driver is able to switch + * to the designated frame. The target frame may be specified as + * + * 1. a numeric index into + * [window.frames](https://developer.mozilla.org/en-US/docs/Web/API/Window.frames) + * for the currently selected frame. + * 2. a {@link ./WebElement}, which must reference a FRAME or IFRAME + * element on the current page. + * 3. a locator which may be used to first locate a FRAME or IFRAME on the + * current page before attempting to switch to it. + * + * Upon successful resolution of this condition, the driver will be left + * focused on the new frame. + * + * @param {!(number|./WebElement|By|function(!./WebDriver): !./WebElement)} frame + * The frame identifier. + * @return {!Condition} A new condition. + */ +export function ableToSwitchToFrame( + frame: number|WebElement|By|((webdriver: WebDriver) => WebElement)|ByHash): Condition; + +/** + * Creates a condition that waits for an alert to be opened. Upon success, the + * returned promise will be fulfilled with the handle for the opened alert. + * + * @return {!Condition} The new condition. + */ +export function alertIsPresent(): Condition; + +/** + * Creates a condition that will wait for the given element to be disabled. + * + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isEnabled + */ +export function elementIsDisabled(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will wait for the given element to be enabled. + * + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isEnabled + */ +export function elementIsEnabled(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will wait for the given element to be deselected. + * + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isSelected + */ +export function elementIsNotSelected(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will wait for the given element to be in the DOM, + * yet not visible to the user. + * + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isDisplayed + */ +export function elementIsNotVisible(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will wait for the given element to be selected. + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isSelected + */ +export function elementIsSelected(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will wait for the given element to become visible. + * + * @param {!WebElement} element The element to test. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#isDisplayed + */ +export function elementIsVisible(element: WebElement): WebElementCondition; + +/** + * Creates a condition that will loop until an element is + * {@link ./WebDriver#findElement found} with the given locator. + * + * @param {!(By|Function)} locator The locator to use. + * @return {!WebElementCondition} The new condition. + */ +export function elementLocated(locator: Locator): WebElementCondition; + +/** + * Creates a condition that will wait for the given element's + * {@link WebDriver#getText visible text} to contain the given + * substring. + * + * @param {!WebElement} element The element to test. + * @param {string} substr The substring to search for. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#getText + */ +export function elementTextContains(element: WebElement, substr: string): WebElementCondition; + +/** + * Creates a condition that will wait for the given element's + * {@link WebDriver#getText visible text} to match the given + * {@code text} exactly. + * + * @param {!WebElement} element The element to test. + * @param {string} text The expected text. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#getText + */ +export function elementTextIs(element: WebElement, text: string): WebElementCondition; + +/** + * Creates a condition that will wait for the given element's + * {@link WebDriver#getText visible text} to match a regular + * expression. + * + * @param {!WebElement} element The element to test. + * @param {!RegExp} regex The regular expression to test against. + * @return {!WebElementCondition} The new condition. + * @see WebDriver#getText + */ +export function elementTextMatches(element: WebElement, regex: RegExp): WebElementCondition; + +/** + * Creates a condition that will loop until at least one element is + * {@link WebDriver#findElement found} with the given locator. + * + * @param {!(Locator|By.Hash|Function)} locator The locator + * to use. + * @return {!Condition.>} The new + * condition. + */ +export function elementsLocated(locator: Locator): Condition; + +/** + * Creates a condition that will wait for the given element to become stale. + * An element is considered stale once it is removed from the DOM, or a new + * page has loaded. + * + * @param {!WebElement} element The element that should become stale. + * @return {!Condition} The new condition. + */ +export function stalenessOf(element: WebElement): Condition; + +/** + * Creates a condition that will wait for the current page's title to contain + * the given substring. + * + * @param {string} substr The substring that should be present in the page + * title. + * @return {!Condition.} The new condition. + */ +export function titleContains(substr: string): Condition; + +/** + * Creates a condition that will wait for the current page's title to match + * the given value. + * + * @param {string} title The expected page title. + * @return {!Condition} The new condition. + */ +export function titleIs(title: string): Condition; + +/** + * Creates a condition that will wait for the current page's title to match + * the given regular expression. + * + * @param {!RegExp} regex The regular expression to test against. + * @return {!Condition.} The new condition. + */ +export function titleMatches(regex: RegExp): Condition; + +/** + * Creates a condition that will wait for the current page's url to contain + * the given substring. + * + * @param {string} substrUrl The substring that should be present in the + * current URL. + * @return {!Condition} The new condition. + */ +export function urlContains(substrUrl: string): Condition; + +/** + * Creates a condition that will wait for the current page's url to match the + * given value. + * + * @param {string} url The expected page url. + * @return {!Condition} The new condition. + */ +export function urlIs(url: string): Condition; + +/** + * Creates a condition that will wait for the current page's url to match the + * given regular expression. + * + * @param {!RegExp} regex The regular expression to test against. + * @return {!Condition} The new condition. + */ +export function urlMatches(regex: RegExp): Condition; diff --git a/lib/selenium-webdriver/remote.d.ts b/lib/selenium-webdriver/remote.d.ts new file mode 100644 index 000000000..5df3698ce --- /dev/null +++ b/lib/selenium-webdriver/remote.d.ts @@ -0,0 +1,234 @@ +import * as webdriver from './index'; + +/** + * A record object that defines the configuration options for a DriverService + * instance. + * + * @record + */ +export interface ServiceOptions {} + +/** + * Manages the life and death of a native executable WebDriver server. + * + * It is expected that the driver server implements the + * https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol. + * Furthermore, the managed server should support multiple concurrent sessions, + * so that this class may be reused for multiple clients. + */ +export class DriverService { + /** + * @param {string} executable Path to the executable to run. + * @param {!ServiceOptions} options Configuration options for the service. + */ + constructor(executable: string, options: ServiceOptions); + + /** + * @return {!promise.Promise} A promise that resolves to + * the server's address. + * @throws {Error} If the server has not been started. + */ + address(): Promise; + + /** + * Returns whether the underlying process is still running. This does not take + * into account whether the process is in the process of shutting down. + * @return {boolean} Whether the underlying service process is running. + */ + isRunning(): boolean; + + /** + * Starts the server if it is not already running. + * @param {number=} opt_timeoutMs How long to wait, in milliseconds, for the + * server to start accepting requests. Defaults to 30 seconds. + * @return {!promise.Promise} A promise that will resolve + * to the server's base URL when it has started accepting requests. If the + * timeout expires before the server has started, the promise will be + * rejected. + */ + start(opt_timeoutMs?: number): Promise; + + /** + * Stops the service if it is not currently running. This function will kill + * the server immediately. To synchronize with the active control flow, use + * {@link #stop()}. + * @return {!promise.Promise} A promise that will be resolved when + * the server has been stopped. + */ + kill(): Promise; +} + +export namespace DriverService { + /** + * Creates {@link DriverService} objects that manage a WebDriver server in a + * child process. + */ + class Builder { + /** + * @param {string} exe Path to the executable to use. This executable must + * accept the `--port` flag for defining the port to start the server on. + * @throws {Error} If the provided executable path does not exist. + */ + constructor(exe: string); + + /** + * Define additional command line arguments to use when starting the server. + * + * @param {...CommandLineFlag} var_args The arguments to include. + * @return {!THIS} A self reference. + * @this {THIS} + * @template THIS + */ + addArguments(...var_args: string[]): this; + + /** + * Sets the host name to access the server on. If specified, the + * {@linkplain #setLoopback() loopback} setting will be ignored. + * + * @param {string} hostname + * @return {!DriverService.Builder} A self reference. + */ + setHostname(hostname: string): this; + + /** + * Sets whether the service should be accessed at this host's loopback + * address. + * + * @param {boolean} loopback + * @return {!DriverService.Builder} A self reference. + */ + setLoopback(loopback: boolean): this; + + /** + * Sets the base path for WebDriver REST commands (e.g. "/wd/hub"). + * By default, the driver will accept commands relative to "/". + * + * @param {?string} basePath The base path to use, or `null` to use the + * default. + * @return {!DriverService.Builder} A self reference. + */ + setPath(basePath: string|null): this; + + /** + * Sets the port to start the server on. + * + * @param {number} port The port to use, or 0 for any free port. + * @return {!DriverService.Builder} A self reference. + * @throws {Error} If an invalid port is specified. + */ + setPort(port: number): this; + + /** + * Defines the environment to start the server under. This setting will be + * inherited by every browser session started by the server. By default, the + * server will inherit the enviroment of the current process. + * + * @param {(Map|Object|null)} env The desired + * environment to use, or `null` if the server should inherit the + * current environment. + * @return {!DriverService.Builder} A self reference. + */ + setEnvironment(env: Map|{[name: string]: string}|null): this; + + /** + * IO configuration for the spawned server process. For more information, + * refer to the documentation of `child_process.spawn`. + * + * @param {StdIoOptions} config The desired IO configuration. + * @return {!DriverService.Builder} A self reference. + * @see https://nodejs.org/dist/latest-v4.x/docs/api/child_process.html#child_process_options_stdio + */ + setStdio(config: any): this; + + /** + * Creates a new DriverService using this instance's current configuration. + * + * @return {!DriverService} A new driver service. + */ + build(): DriverService; + } +} + +/** + * Manages the life and death of the + * + * standalone Selenium server. + */ +export class SeleniumServer extends DriverService { + /** + * @param {string} jar Path to the Selenium server jar. + * @param {SeleniumServer.Options=} opt_options Configuration options for the + * server. + * @throws {Error} If the path to the Selenium jar is not specified or if an + * invalid port is specified. + **/ + constructor(jar: string, opt_options?: SeleniumServer.Options); +} + +export namespace SeleniumServer { + /** + * Options for the Selenium server + */ + interface Options { + /** Whether the server should only be accessed on this host's loopback address.*/ + loopback?: boolean; + + /** The port to start the server on (must be > 0). If the port is provided + as a promise, the service will wait for the promise to resolve before starting. */ + port?: number|Promise; + + /** The arguments to pass to the service. If a promise is provided, the + service will wait for it to resolve before starting. */ + args?: string[]|Promise; + + /** The arguments to pass to the JVM. If a promise is provided, the service + will wait for it to resolve before starting. */ + jvmArgs?: string[]|Promise; + + /** The environment variables that should be visible to the server process. + Defaults to inheriting the current process's environment.*/ + env?: {[key: string]: string}; + + /** IO configuration for the spawned server process. For more information, + refer to the documentation of `child_process.spawn`*/ + stdio?: string|Array; + } +} + +/** + * A {@link webdriver.FileDetector} that may be used when running + * against a remote + * [Selenium server](http://selenium-release.storage.googleapis.com/index.html). + * + * When a file path on the local machine running this script is entered with + * {@link webdriver.WebElement#sendKeys WebElement#sendKeys}, this file detector + * will transfer the specified file to the Selenium server's host; the sendKeys + * command will be updated to use the transfered file's path. + * + * __Note:__ This class depends on a non-standard command supported on the + * Java Selenium server. The file detector will fail if used with a server that + * only supports standard WebDriver commands (such as the ChromeDriver). + * + * @final + */ +export class FileDetector extends webdriver.FileDetector { + /** + * @constructor + **/ + constructor(); + + /** + * Prepares a `file` for use with the remote browser. If the provided path + * does not reference a normal file (i.e. it does not exist or is a + * directory), then the promise returned by this method will be resolved + * with the original file path. Otherwise, this method will upload the file + * to the remote server, which will return the file's path on the remote + * system so it may be referenced in subsequent commands. + * + * @param {!webdriver.WebDriver} driver The driver for the current browser. + * @param {string} file The path of the file to process. + * @return {!Promise} A promise for the processed + * file path. + */ + handleFile(driver: webdriver.WebDriver, file: string): Promise; +} diff --git a/lib/selenium-webdriver/safari.d.ts b/lib/selenium-webdriver/safari.d.ts new file mode 100644 index 000000000..eee4e567f --- /dev/null +++ b/lib/selenium-webdriver/safari.d.ts @@ -0,0 +1,63 @@ +import * as webdriver from './index'; + +export class Server {} + +/** + * @return {!Promise} A promise that will resolve with the path + * to Safari on the current system. + */ +export function findSafariDriver(): any; + +/** + * @param {string} serverUrl The URL to connect to. + * @return {!Promise} A promise for the path to a file that Safari can + * open on start-up to trigger a new connection to the WebSocket server. + */ +export function createConnectFile(serverUrl: string): any; + +/** + * Deletes all session data files if so desired. + * @param {!Object} desiredCapabilities . + * @return {!Array} A list of promises for the deleted files. + */ +export function cleanSession(desiredCapabilities: webdriver.Capabilities): any[]; + +/** @return {string} . */ +export function getRandomString(): string; + +/** + * @implements {command.Executor} + */ +export class CommandExecutor {} + +/** + * Configuration options specific to the {@link Driver SafariDriver}. + */ +export class Options extends webdriver.Capabilities { + /** + * Sets the logging preferences for the new session. + * @param {!./lib/logging.Preferences} prefs The logging preferences. + * @return {!Options} A self reference. + */ + setLoggingPrefs(prefs: webdriver.logging.Preferences): Options; +} + +/** + * A WebDriver client for Safari. This class should never be instantiated + * directly; instead, use the {@linkplain ./builder.Builder Builder}: + * + * var driver = new Builder() + * .forBrowser('safari') + * .build(); + * + */ +export class Driver extends webdriver.WebDriver { + /** + * Creates a new Safari session. + * + * @param {(Options|Capabilities)=} opt_config The configuration + * options for the new session. + * @return {!Driver} A new driver instance. + */ + static createSession(opt_config?: Options|webdriver.Capabilities): Driver; +} diff --git a/lib/util.ts b/lib/util.ts index a090e2fb1..58e34cc96 100644 --- a/lib/util.ts +++ b/lib/util.ts @@ -1,5 +1,5 @@ import * as path from 'path'; -import {error as wderror} from 'selenium-webdriver'; +import * as webdriver from 'selenium-webdriver'; let STACK_SUBSTRINGS_TO_FILTER = [ 'node_modules/jasmine/', 'node_modules/selenium-webdriver', 'at Module.', 'at Object.Module.', @@ -88,8 +88,8 @@ export function joinTestLogs(log1: any, log2: any): any { * @return {boolean} false, if it doesn't re-throw the error */ export function falseIfMissing(error: any) { - if ((error instanceof wderror.NoSuchElementError) || - (error instanceof wderror.StaleElementReferenceError)) { + if ((error instanceof webdriver.error.NoSuchElementError) || + (error instanceof webdriver.error.StaleElementReferenceError)) { return false; } else { throw error; @@ -104,4 +104,4 @@ export function falseIfMissing(error: any) { */ export function passBoolean(value: boolean) { return value; -} +} \ No newline at end of file diff --git a/package.json b/package.json index 587aec7ac..459361a71 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,6 @@ "saucelabs": "^1.5.0", "selenium-webdriver": "^4.0.0-alpha.1", "source-map-support": "~0.4.0", - "webdriver-js-extender": "2.1.0", "webdriver-manager": "13.0.0-beta" }, "devDependencies": { diff --git a/spec/ts/basic/element_spec.ts b/spec/ts/basic/element_spec.ts index 75716f73b..4c8a99bdf 100644 --- a/spec/ts/basic/element_spec.ts +++ b/spec/ts/basic/element_spec.ts @@ -1,5 +1,5 @@ // Based off of spec/basic/elements_spec.js -import {$, browser, by, element, ElementArrayFinder, ElementFinder, promise as ppromise, WebElement} from '../../..'; +import {$, browser, by, element, ElementArrayFinder, ElementFinder} from '../../..'; describe('ElementFinder', () => { it('should return the same result as browser.findElement', async() => { @@ -36,12 +36,12 @@ describe('ElementFinder', () => { expect(await name.getText()).toEqual('Jane'); }); - it('should run chained element actions in sequence', async(done: any) => { + it('should run chained element actions in sequence', async () => { // Testing private methods is bad :( let els = new ElementArrayFinder(browser, () => { - return Promise.resolve([null as WebElement]); + return Promise.resolve([null]); }); - let applyAction_: (actionFn: (value: WebElement, index: number, array: WebElement[]) => any) => + let applyAction_: (actionFn: (value: any, index: number, array: any) => any) => ElementArrayFinder = (ElementArrayFinder as any).prototype.applyAction_; let order: string[] = []; @@ -61,11 +61,10 @@ describe('ElementFinder', () => { }); await deferredB; - setTimeout(async function() { + setTimeout(async () => { await deferredA; await els; expect(order).toEqual(['a', 'b']); - done(); }, 100); }); diff --git a/spec/ts/basic/is_disabled_spec.ts b/spec/ts/basic/is_disabled_spec.ts deleted file mode 100644 index 1c95383f8..000000000 --- a/spec/ts/basic/is_disabled_spec.ts +++ /dev/null @@ -1,7 +0,0 @@ -import {promise as wdpromise} from '../../..'; - -describe('verify control flow is off', () => { - it('should have set webdriver.promise.USE_PROMISE_MANAGER', () => { - expect((wdpromise as any).USE_PROMISE_MANAGER).toBe(false); - }); -}); diff --git a/testapp/package-lock.json b/testapp/package-lock.json index 00c8cf57e..97fc502b1 100644 --- a/testapp/package-lock.json +++ b/testapp/package-lock.json @@ -1257,12 +1257,14 @@ "balanced-match": { "version": "1.0.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "brace-expansion": { "version": "1.1.11", "bundled": true, "dev": true, + "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -1277,17 +1279,20 @@ "code-point-at": { "version": "1.1.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "concat-map": { "version": "0.0.1", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "console-control-strings": { "version": "1.1.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "core-util-is": { "version": "1.0.2", @@ -1404,7 +1409,8 @@ "inherits": { "version": "2.0.3", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "ini": { "version": "1.3.5", @@ -1416,6 +1422,7 @@ "version": "1.0.0", "bundled": true, "dev": true, + "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -1430,6 +1437,7 @@ "version": "3.0.4", "bundled": true, "dev": true, + "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -1437,12 +1445,14 @@ "minimist": { "version": "0.0.8", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "minipass": { "version": "2.2.4", "bundled": true, "dev": true, + "optional": true, "requires": { "safe-buffer": "^5.1.1", "yallist": "^3.0.0" @@ -1461,6 +1471,7 @@ "version": "0.5.1", "bundled": true, "dev": true, + "optional": true, "requires": { "minimist": "0.0.8" } @@ -1541,7 +1552,8 @@ "number-is-nan": { "version": "1.0.1", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "object-assign": { "version": "4.1.1", @@ -1553,6 +1565,7 @@ "version": "1.4.0", "bundled": true, "dev": true, + "optional": true, "requires": { "wrappy": "1" } @@ -1674,6 +1687,7 @@ "version": "1.0.2", "bundled": true, "dev": true, + "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", diff --git a/ts_spec_config.json b/ts_spec_config.json index 22227ea50..d7a45d33a 100644 --- a/ts_spec_config.json +++ b/ts_spec_config.json @@ -7,7 +7,16 @@ "declaration": true, "removeComments": false, "noImplicitAny": true, - "outDir": "spec/built" + "outDir": "spec/built", + "baseUrl": ".", + "paths": { + "selenium-webdriver": ["lib/selenium-webdriver"], + "selenium-webdriver/chrome": ["lib/selenium-webdriver/chrome.d.ts"], + "selenium-webdriver/firefox": ["lib/selenium-webdriver/firefox.d.ts"], + "selenium-webdriver/http": ["lib/selenium-webdriver/http.d.ts"], + "selenium-webdriver/remote": ["lib/selenium-webdriver/remote.d.ts"], + "selenium-webdriver/lib/command": ["lib/selenium-webdriver/lib/command.d.ts"] + } }, "include": [ "spec/ts/**/*" diff --git a/tsconfig.json b/tsconfig.json index e49b0ebf6..b7bb19be0 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -7,7 +7,16 @@ "declaration": true, "removeComments": false, "noImplicitAny": true, - "outDir": "built/" + "outDir": "built/", + "baseUrl": ".", + "paths": { + "selenium-webdriver": ["lib/selenium-webdriver"], + "selenium-webdriver/chrome": ["lib/selenium-webdriver/chrome.d.ts"], + "selenium-webdriver/firefox": ["lib/selenium-webdriver/firefox.d.ts"], + "selenium-webdriver/http": ["lib/selenium-webdriver/http.d.ts"], + "selenium-webdriver/remote": ["lib/selenium-webdriver/remote.d.ts"], + "selenium-webdriver/lib/command": ["lib/selenium-webdriver/lib/command.d.ts"] + } }, "exclude": [ "built", @@ -17,6 +26,6 @@ "scripts", "exampleTypescript", "spec/**/*", - "typings" + "lib/selenium-webdriver]" ] } diff --git a/typings/chrome.d.ts b/typings/chrome.d.ts deleted file mode 100644 index a5dbd2fd1..000000000 --- a/typings/chrome.d.ts +++ /dev/null @@ -1,362 +0,0 @@ -import * as webdriver from './index'; -import * as remote from './remote'; -import * as http from './http'; - -/** - * Creates a new WebDriver client for Chrome. - * - * @extends {webdriver.WebDriver} - */ -export class Driver extends webdriver.WebDriver { - /** - * Creates a new session with the ChromeDriver. - * - * @param {(Capabilities|Options)=} opt_config The configuration options. - * @param {(remote.DriverService|http.Executor)=} opt_serviceExecutor Either - * a DriverService to use for the remote end, or a preconfigured executor - * for an externally managed endpoint. If neither is provided, the - * {@linkplain ##getDefaultService default service} will be used by - * default. - * @param {promise.ControlFlow=} opt_flow The control flow to use, or `null` - * to use the currently active flow. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: Options | webdriver.CreateSessionCapabilities, opt_service?: remote.DriverService | http.Executor, opt_flow?: webdriver.promise.ControlFlow): Driver; -} - -export interface IOptionsValues { - args: string[]; - binary?: string; - detach: boolean; - extensions: string[]; - localState?: any; - logFile?: string; - prefs?: any; -} - -export interface IPerfLoggingPrefs { - enableNetwork: boolean; - enablePage: boolean; - enableTimeline: boolean; - tracingCategories: string; - bufferUsageReportingInterval: number; -} - -/** - * Class for managing ChromeDriver specific options. - */ -export class Options { - /** - * @constructor - */ - constructor(); - - /** - * Extracts the ChromeDriver specific options from the given capabilities - * object. - * @param {!webdriver.Capabilities} capabilities The capabilities object. - * @return {!Options} The ChromeDriver options. - */ - static fromCapabilities(capabilities: webdriver.Capabilities): Options; - - /** - * Add additional command line arguments to use when launching the Chrome - * browser. Each argument may be specified with or without the '--' prefix - * (e.g. '--foo' and 'foo'). Arguments with an associated value should be - * delimited by an '=': 'foo=bar'. - * @param {...(string|!Array.)} var_args The arguments to add. - * @return {!Options} A self reference. - */ - addArguments(...var_args: string[]): Options; - - /** - * Configures the chromedriver to start Chrome in headless mode. - * - * > __NOTE:__ Resizing the browser window in headless mode is only supported - * > in Chrome 60. Users are encouraged to set an initial window size with - * > the {@link #windowSize windowSize({width, height})} option. - * - * @return {!Options} A self reference. - */ - headless(): Options; - - /** - * List of Chrome command line switches to exclude that ChromeDriver by default - * passes when starting Chrome. Do not prefix switches with '--'. - * - * @param {...(string|!Array)} var_args The switches to exclude. - * @return {!Options} A self reference. - */ - excludeSwitches(...var_args: string[]): Options; - - /** - * Add additional extensions to install when launching Chrome. Each extension - * should be specified as the path to the packed CRX file, or a Buffer for an - * extension. - * @param {...(string|!Buffer|!Array.<(string|!Buffer)>)} var_args The - * extensions to add. - * @return {!Options} A self reference. - */ - addExtensions(...var_args: any[]): Options; - - /** - * Sets the path to the Chrome binary to use. On Mac OS X, this path should - * reference the actual Chrome executable, not just the application binary - * (e.g. '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'). - * - * The binary path be absolute or relative to the chromedriver server - * executable, but it must exist on the machine that will launch Chrome. - * - * @param {string} path The path to the Chrome binary to use. - * @return {!Options} A self reference. - */ - setChromeBinaryPath(path: string): Options; - - /** - * Sets whether to leave the started Chrome browser running if the controlling - * ChromeDriver service is killed before {@link webdriver.WebDriver#quit()} is - * called. - * @param {boolean} detach Whether to leave the browser running if the - * chromedriver service is killed before the session. - * @return {!Options} A self reference. - */ - detachDriver(detach: boolean): Options; - - /** - * Sets the user preferences for Chrome's user profile. See the 'Preferences' - * file in Chrome's user data directory for examples. - * @param {!Object} prefs Dictionary of user preferences to use. - * @return {!Options} A self reference. - */ - setUserPreferences(prefs: any): Options; - - /** - * Sets the logging preferences for the new session. - * @param {!webdriver.logging.Preferences} prefs The logging preferences. - * @return {!Options} A self reference. - */ - setLoggingPrefs(prefs: webdriver.logging.Preferences): Options; - - /** - * Sets the performance logging preferences. Options include: - * - * - `enableNetwork`: Whether or not to collect events from Network domain. - * - `enablePage`: Whether or not to collect events from Page domain. - * - `enableTimeline`: Whether or not to collect events from Timeline domain. - * Note: when tracing is enabled, Timeline domain is implicitly disabled, - * unless `enableTimeline` is explicitly set to true. - * - `tracingCategories`: A comma-separated string of Chrome tracing categories - * for which trace events should be collected. An unspecified or empty - * string disables tracing. - * - `bufferUsageReportingInterval`: The requested number of milliseconds - * between DevTools trace buffer usage events. For example, if 1000, then - * once per second, DevTools will report how full the trace buffer is. If a - * report indicates the buffer usage is 100%, a warning will be issued. - * - * @param {{enableNetwork: boolean, - * enablePage: boolean, - * enableTimeline: boolean, - * tracingCategories: string, - * bufferUsageReportingInterval: number}} prefs The performance - * logging preferences. - * @return {!Options} A self reference. - */ - setPerfLoggingPrefs(prefs: IPerfLoggingPrefs): Options; - - /** - * Sets preferences for the 'Local State' file in Chrome's user data - * directory. - * @param {!Object} state Dictionary of local state preferences. - * @return {!Options} A self reference. - */ - setLocalState(state: any): Options; - - /** - * Sets the name of the activity hosting a Chrome-based Android WebView. This - * option must be set to connect to an [Android WebView]( - * https://sites.google.com/a/chromium.org/chromedriver/getting-started/getting-started---android) - * - * @param {string} name The activity name. - * @return {!Options} A self reference. - */ - androidActivity(name: string): Options; - - /** - * Sets the device serial number to connect to via ADB. If not specified, the - * ChromeDriver will select an unused device at random. An error will be - * returned if all devices already have active sessions. - * - * @param {string} serial The device serial number to connect to. - * @return {!Options} A self reference. - */ - androidDeviceSerial(serial: string): Options; - - /** - * Configures the ChromeDriver to launch Chrome on Android via adb. This - * function is shorthand for - * {@link #androidPackage options.androidPackage('com.android.chrome')}. - * @return {!Options} A self reference. - */ - androidChrome(): Options; - - /** - * Sets the package name of the Chrome or WebView app. - * - * @param {?string} pkg The package to connect to, or `null` to disable Android - * and switch back to using desktop Chrome. - * @return {!Options} A self reference. - */ - androidPackage(pkg: string): Options; - - /** - * Sets the process name of the Activity hosting the WebView (as given by `ps`). - * If not specified, the process name is assumed to be the same as - * {@link #androidPackage}. - * - * @param {string} processName The main activity name. - * @return {!Options} A self reference. - */ - androidProcess(processName: string): Options; - - /** - * Sets whether to connect to an already-running instead of the specified - * {@linkplain #androidProcess app} instead of launching the app with a clean - * data directory. - * - * @param {boolean} useRunning Whether to connect to a running instance. - * @return {!Options} A self reference. - */ - androidUseRunningApp(useRunning: boolean): Options; - - /** - * Sets the path to Chrome's log file. This path should exist on the machine - * that will launch Chrome. - * @param {string} path Path to the log file to use. - * @return {!Options} A self reference. - */ - setChromeLogFile(path: string): Options; - - /** - * Sets the directory to store Chrome minidumps in. This option is only - * supported when ChromeDriver is running on Linux. - * @param {string} path The directory path. - * @return {!Options} A self reference. - */ - setChromeMinidumpPath(path: string): Options; - - /** - * Configures Chrome to emulate a mobile device. For more information, refer - * to the ChromeDriver project page on [mobile emulation][em]. Configuration - * options include: - * - * - `deviceName`: The name of a pre-configured [emulated device][devem] - * - `width`: screen width, in pixels - * - `height`: screen height, in pixels - * - `pixelRatio`: screen pixel ratio - * - * __Example 1: Using a Pre-configured Device__ - * - * let options = new chrome.Options().setMobileEmulation( - * {deviceName: 'Google Nexus 5'}); - * - * let driver = new chrome.Driver(options); - * - * __Example 2: Using Custom Screen Configuration__ - * - * let options = new chrome.Options().setMobileEmulation({ - * width: 360, - * height: 640, - * pixelRatio: 3.0 - * }); - * - * let driver = new chrome.Driver(options); - * - * - * [em]: https://sites.google.com/a/chromium.org/chromedriver/mobile-emulation - * [devem]: https://developer.chrome.com/devtools/docs/device-mode - * - * @param {?({deviceName: string}| - * {width: number, height: number, pixelRatio: number})} config The - * mobile emulation configuration, or `null` to disable emulation. - * @return {!Options} A self reference. - */ - setMobileEmulation(config: any): Options; - - /** - * Sets the proxy settings for the new session. - * @param {webdriver.ProxyConfig} proxy The proxy configuration to use. - * @return {!Options} A self reference. - */ - setProxy(proxy: webdriver.ProxyConfig): Options; - - /** - * Converts this options instance to a {@link webdriver.Capabilities} object. - * @param {webdriver.Capabilities=} opt_capabilities The capabilities to merge - * these options into, if any. - * @return {!webdriver.Capabilities} The capabilities. - */ - toCapabilities(opt_capabilities?: webdriver.Capabilities): webdriver.Capabilities; -} - -/** - * Creates {@link remote.DriverService} instances that manage a ChromeDriver - * server. - */ -export class ServiceBuilder extends remote.DriverService.Builder { - /** - * @param {string=} opt_exe Path to the server executable to use. If omitted, - * the builder will attempt to locate the chromedriver on the current - * PATH. - * @throws {Error} If provided executable does not exist, or the chromedriver - * cannot be found on the PATH. - * @constructor - */ - constructor(opt_exe?: string); - - /** - * Sets which port adb is listening to. _The ChromeDriver will connect to adb - * if an {@linkplain Options#androidPackage Android session} is requested, but - * adb **must** be started beforehand._ - * - * @param {number} port Which port adb is running on. - * @return {!ServiceBuilder} A self reference. - */ - setAdbPort(port: number): this; - - /** - * Sets the path of the log file the driver should log to. If a log file is - * not specified, the driver will log to stderr. - * @param {string} path Path of the log file to use. - * @return {!ServiceBuilder} A self reference. - */ - loggingTo(path: string): this; - - /** - * Enables verbose logging. - * @return {!ServiceBuilder} A self reference. - */ - enableVerboseLogging(): this; - - /** - * Sets the number of threads the driver should use to manage HTTP requests. - * By default, the driver will use 4 threads. - * @param {number} n The number of threads to use. - * @return {!ServiceBuilder} A self reference. - */ - setNumHttpThreads(n: number): this; -} - -/** - * Returns the default ChromeDriver service. If such a service has not been - * configured, one will be constructed using the default configuration for - * a ChromeDriver executable found on the system PATH. - * @return {!remote.DriverService} The default ChromeDriver service. - */ -export function getDefaultService(): remote.DriverService; - -/** - * Sets the default service to use for new ChromeDriver instances. - * @param {!remote.DriverService} service The service to use. - * @throws {Error} If the default service is currently running. - */ -export function setDefaultService(service: remote.DriverService): void; diff --git a/typings/edge.d.ts b/typings/edge.d.ts deleted file mode 100644 index 90b45fc92..000000000 --- a/typings/edge.d.ts +++ /dev/null @@ -1,92 +0,0 @@ -import * as webdriver from './index'; -import * as remote from './remote'; - -export class Driver extends webdriver.WebDriver { - /** - * Creates a new browser session for Microsoft's Edge browser. - * - * @param {(capabilities.Capabilities|Options)=} opt_config The configuration - * options. - * @param {remote.DriverService=} opt_service The session to use; will use - * the {@linkplain #getDefaultService default service} by default. - * @param {promise.ControlFlow=} opt_flow The control flow to use, or - * {@code null} to use the currently active flow. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: webdriver.CreateSessionCapabilities, opt_service?: remote.DriverService, opt_flow?: webdriver.promise.ControlFlow): Driver; - - /** - * This function is a no-op as file detectors are not supported by this - * implementation. - * @override - */ - setFileDetector(): void; -} - -/** - * Class for managing MicrosoftEdgeDriver specific options. - */ -export class Options { - /** - * Extracts the MicrosoftEdgeDriver specific options from the given - * capabilities object. - * @param {!capabilities.Capabilities} caps The capabilities object. - * @return {!Options} The MicrosoftEdgeDriver options. - */ - static fromCapabilities(cap: webdriver.Capabilities): Options; - - /** - * Sets the proxy settings for the new session. - * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. - * @return {!Options} A self reference. - */ - setProxy(proxy: webdriver.ProxyConfig): Options; - - /** - * Sets the page load strategy for Edge. - * Supported values are 'normal', 'eager', and 'none'; - * - * @param {string} pageLoadStrategy The page load strategy to use. - * @return {!Options} A self reference. - */ - setPageLoadStrategy(pageLoadStrategy: string): Options; - - /** - * Converts this options instance to a {@link capabilities.Capabilities} - * object. - * @param {capabilities.Capabilities=} opt_capabilities The capabilities to - * merge these options into, if any. - * @return {!capabilities.Capabilities} The capabilities. - */ - toCapabilities(opt_capabilities?: webdriver.Capabilities): webdriver.Capabilities; -} - -/** - * Creates {@link remote.DriverService} instances that manage a - * MicrosoftEdgeDriver server in a child process. - */ -export class ServiceBuilder extends remote.DriverService.Builder { - /** - * @param {string=} opt_exe Path to the server executable to use. If omitted, - * the builder will attempt to locate the MicrosoftEdgeDriver on the current - * PATH. - * @throws {Error} If provided executable does not exist, or the - * MicrosoftEdgeDriver cannot be found on the PATH. - */ - constructor(opt_exe?: string); -} - -/** - * Returns the default MicrosoftEdgeDriver service. If such a service has - * not been configured, one will be constructed using the default configuration - * for an MicrosoftEdgeDriver executable found on the system PATH. - * @return {!remote.DriverService} The default MicrosoftEdgeDriver service. - */ -export function getDefaultService(): remote.DriverService; - -/** - * Sets the default service to use for new MicrosoftEdgeDriver instances. - * @param {!remote.DriverService} service The service to use. - * @throws {Error} If the default service is currently running. - */ -export function setDefaultService(service: remote.DriverService): void; diff --git a/typings/firefox.d.ts b/typings/firefox.d.ts deleted file mode 100644 index 0c2ecdbe9..000000000 --- a/typings/firefox.d.ts +++ /dev/null @@ -1,292 +0,0 @@ -import * as webdriver from './index'; -import * as remote from './remote'; -import * as http from './http'; - -/** - * Manages a Firefox subprocess configured for use with WebDriver. - */ -export class Binary { - /** - * @param {string=} opt_exe Path to the Firefox binary to use. If not - * specified, will attempt to locate Firefox on the current system. - * @constructor - */ - constructor(opt_exe?: string); - - /** - * Add arguments to the command line used to start Firefox. - * @param {...(string|!Array.)} var_args Either the arguments to add as - * varargs, or the arguments as an array. - */ - addArguments(...var_args: string[]): void; - - /** - * Launches Firefox and eturns a promise that will be fulfilled when the process - * terminates. - * @param {string} profile Path to the profile directory to use. - * @return {!promise.Promise.} A promise for the process result. - * @throws {Error} If this instance has already been started. - */ - launch(profile: string): webdriver.promise.Promise; - - /** - * Kills the managed Firefox process. - * @return {!promise.Promise} A promise for when the process has terminated. - */ - kill(): webdriver.promise.Promise; -} - -/** - * Models a Firefox proifle directory for use with the FirefoxDriver. The - * {@code Proifle} directory uses an in-memory model until {@link #writeToDisk} - * is called. - */ -export class Profile { - /** - * @param {string=} opt_dir Path to an existing Firefox profile directory to - * use a template for this profile. If not specified, a blank profile will - * be used. - * @constructor - */ - constructor(opt_dir?: string); - - /** - * Registers an extension to be included with this profile. - * @param {string} extension Path to the extension to include, as either an - * unpacked extension directory or the path to a xpi file. - */ - addExtension(extension: string): void; - - /** - * Sets a desired preference for this profile. - * @param {string} key The preference key. - * @param {(string|number|boolean)} value The preference value. - * @throws {Error} If attempting to set a frozen preference. - */ - setPreference(key: string, value: string): void; - setPreference(key: string, value: number): void; - setPreference(key: string, value: boolean): void; - - /** - * Returns the currently configured value of a profile preference. This does - * not include any defaults defined in the profile's template directory user.js - * file (if a template were specified on construction). - * @param {string} key The desired preference. - * @return {(string|number|boolean|undefined)} The current value of the - * requested preference. - */ - getPreference(key: string): any; - - /** - * @return {number} The port this profile is currently configured to use, or - * 0 if the port will be selected at random when the profile is written - * to disk. - */ - getPort(): number; - - /** - * Sets the port to use for the WebDriver extension loaded by this profile. - * @param {number} port The desired port, or 0 to use any free port. - */ - setPort(port: number): void; - - /** - * @return {boolean} Whether the FirefoxDriver is configured to automatically - * accept untrusted SSL certificates. - */ - acceptUntrustedCerts(): boolean; - - /** - * Sets whether the FirefoxDriver should automatically accept untrusted SSL - * certificates. - * @param {boolean} value . - */ - setAcceptUntrustedCerts(value: boolean): void; - - /** - * Sets whether to assume untrusted certificates come from untrusted issuers. - * @param {boolean} value . - */ - setAssumeUntrustedCertIssuer(value: boolean): void; - - /** - * @return {boolean} Whether to assume untrusted certs come from untrusted - * issuers. - */ - assumeUntrustedCertIssuer(): boolean; - - /** - * Sets whether to use native events with this profile. - * @param {boolean} enabled . - */ - setNativeEventsEnabled(enabled: boolean): void; - - /** - * Returns whether native events are enabled in this profile. - * @return {boolean} . - */ - nativeEventsEnabled(): boolean; - - /** - * Writes this profile to disk. - * @param {boolean=} opt_excludeWebDriverExt Whether to exclude the WebDriver - * extension from the generated profile. Used to reduce the size of an - * {@link #encode() encoded profile} since the server will always install - * the extension itself. - * @return {!promise.Promise.} A promise for the path to the new - * profile directory. - */ - writeToDisk(opt_excludeWebDriverExt?: boolean): webdriver.promise.Promise; - - /** - * Encodes this profile as a zipped, base64 encoded directory. - * @return {!promise.Promise.} A promise for the encoded profile. - */ - encode(): webdriver.promise.Promise; -} - -/** - * Configuration options for the FirefoxDriver. - */ -export class Options { - /** - * Sets the profile to use. The profile may be specified as a - * {@link Profile} object or as the path to an existing Firefox profile to use - * as a template. - * - * @param {(string|!Profile)} profile The profile to use. - * @return {!Options} A self reference. - */ - setProfile(profile: string | any): Options; - - /** - * Sets the binary to use. The binary may be specified as the path to a Firefox - * executable, or as a {@link Binary} object. - * - * @param {(string|!Binary)} binary The binary to use. - * @return {!Options} A self reference. - */ - setBinary(binary: string | any): Options; - - /** - * Sets the logging preferences for the new session. - * @param {logging.Preferences} prefs The logging preferences. - * @return {!Options} A self reference. - */ - setLoggingPreferences(prefs: webdriver.logging.Preferences): Options; - - /** - * Sets the proxy to use. - * - * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. - * @return {!Options} A self reference. - */ - setProxy(proxy: webdriver.ProxyConfig): Options; - - /** - * Sets whether to use Mozilla's geckodriver to drive the browser. This option - * is enabled by default and required for Firefox 47+. - * - * @param {boolean} enable Whether to enable the geckodriver. - * @see https://github.com/mozilla/geckodriver - */ - useGeckoDriver(enable: boolean): Options; - - /** - * Converts these options to a {@link capabilities.Capabilities} instance. - * - * @return {!capabilities.Capabilities} A new capabilities object. - */ - toCapabilities(): webdriver.Capabilities; -} - -/** - * @return {string} . - * @throws {Error} - */ -export function findWires(): string; - -/** - * @param {(string|!Binary)} binary . - * @return {!remote.DriverService} . - */ -export function createWiresService(binary: string | any): remote.DriverService; - -/** - * @param {(Profile|string)} profile The profile to prepare. - * @param {number} port The port the FirefoxDriver should listen on. - * @return {!Promise} a promise for the path to the profile directory. - */ -export function prepareProfile(profile: string | any, port: number): any; - -/** - * A WebDriver client for Firefox. - */ -export class Driver extends webdriver.WebDriver { - /** - * Creates a new Firefox session. - * - * @param {(Options|capabilities.Capabilities|Object)=} opt_config The - * configuration options for this driver, specified as either an - * {@link Options} or {@link capabilities.Capabilities}, or as a raw hash - * object. - * @param {(http.Executor|remote.DriverService)=} opt_executor Either a - * pre-configured command executor to use for communicating with an - * externally managed remote end (which is assumed to already be running), - * or the `DriverService` to use to start the geckodriver in a child - * process. - * - * If an executor is provided, care should e taken not to use reuse it with - * other clients as its internal command mappings will be updated to support - * Firefox-specific commands. - * - * _This parameter may only be used with Mozilla's GeckoDriver._ - * - * @param {promise.ControlFlow=} opt_flow The flow to - * schedule commands through. Defaults to the active flow object. - * @throws {Error} If a custom command executor is provided and the driver is - * configured to use the legacy FirefoxDriver from the Selenium project. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: Options | webdriver.Capabilities, opt_executor?: http.Executor | remote.DriverService, opt_flow?: webdriver.promise.ControlFlow): Driver; - - /** - * This function is a no-op as file detectors are not supported by this - * implementation. - * @override - */ - setFileDetector(): void; -} - -/** - * Creates {@link selenium-webdriver/remote.DriverService} instances that manage - * a [geckodriver](https://github.com/mozilla/geckodriver) server in a child - * process. - */ -export class ServiceBuilder extends remote.DriverService.Builder { - /** - * @param {string=} opt_exe Path to the server executable to use. If omitted, - * the builder will attempt to locate the geckodriver on the system PATH. - */ - constructor(opt_exe?: string); - - /** - * Enables verbose logging. - * - * @param {boolean=} opt_trace Whether to enable trace-level logging. By - * default, only debug logging is enabled. - * @return {!ServiceBuilder} A self reference. - */ - enableVerboseLogging(opt_trace?: boolean): this; - - /** - * Sets the path to the executable Firefox binary that the geckodriver should - * use. If this method is not called, this builder will attempt to locate - * Firefox in the default installation location for the current platform. - * - * @param {(string|!Binary)} binary Path to the executable Firefox binary to use. - * @return {!ServiceBuilder} A self reference. - * @see Binary#locate() - */ - setFirefoxBinary(binary: string | Binary): this; -} diff --git a/typings/ie.d.ts b/typings/ie.d.ts deleted file mode 100644 index bf3932450..000000000 --- a/typings/ie.d.ts +++ /dev/null @@ -1,208 +0,0 @@ -import * as webdriver from './index'; - -/** - * A WebDriver client for Microsoft's Internet Explorer. - */ -export class Driver extends webdriver.WebDriver { - /** - * Creates a new session for Microsoft's Internet Explorer. - * - * @param {(capabilities.Capabilities|Options)=} opt_config The configuration - * options. - * @param {promise.ControlFlow=} opt_flow The control flow to use, - * or {@code null} to use the currently active flow. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: webdriver.Capabilities | Options, opt_flow?: webdriver.promise.ControlFlow): Driver; - - /** - * This function is a no-op as file detectors are not supported by this - * implementation. - * @override - */ - setFileDetector(): void; -} - -/** - * Class for managing IEDriver specific options. - */ -export class Options { - constructor(); - - /** - * Extracts the IEDriver specific options from the given capabilities - * object. - * @param {!capabilities.Capabilities} caps The capabilities object. - * @return {!Options} The IEDriver options. - */ - static fromCapabilities(caps: webdriver.Capabilities): Options; - - /** - * Whether to disable the protected mode settings check when the session is - * created. Disbling this setting may lead to significant instability as the - * browser may become unresponsive/hang. Only 'best effort' support is provided - * when using this capability. - * - * For more information, refer to the IEDriver's - * [required system configuration](http://goo.gl/eH0Yi3). - * - * @param {boolean} ignoreSettings Whether to ignore protected mode settings. - * @return {!Options} A self reference. - */ - introduceFlakinessByIgnoringProtectedModeSettings(ignoreSettings: boolean): Options; - - /** - * Indicates whether to skip the check that the browser's zoom level is set to - * 100%. - * - * @param {boolean} ignore Whether to ignore the browser's zoom level settings. - * @return {!Options} A self reference. - */ - ignoreZoomSetting(ignore: boolean): Options; - - /** - * Sets the initial URL loaded when IE starts. This is intended to be used with - * {@link #ignoreProtectedModeSettings} to allow the user to initialize IE in - * the proper Protected Mode zone. Setting this option may cause browser - * instability or flaky and unresponsive code. Only 'best effort' support is - * provided when using this option. - * - * @param {string} url The initial browser URL. - * @return {!Options} A self reference. - */ - initialBrowserUrl(url: string): Options; - - /** - * Configures whether to enable persistent mouse hovering (true by default). - * Persistent hovering is achieved by continuously firing mouse over events at - * the last location the mouse cursor has been moved to. - * - * @param {boolean} enable Whether to enable persistent hovering. - * @return {!Options} A self reference. - */ - enablePersistentHover(enable: boolean): Options; - - /** - * Configures whether the driver should attempt to remove obsolete - * {@linkplain webdriver.WebElement WebElements} from its internal cache on - * page navigation (true by default). Disabling this option will cause the - * driver to run with a larger memory footprint. - * - * @param {boolean} enable Whether to enable element reference cleanup. - * @return {!Options} A self reference. - */ - enableElementCacheCleanup(enable: boolean): Options; - - /** - * Configures whether to require the IE window to have input focus before - * performing any user interactions (i.e. mouse or keyboard events). This - * option is disabled by default, but delivers much more accurate interaction - * events when enabled. - * - * @param {boolean} require Whether to require window focus. - * @return {!Options} A self reference. - */ - requireWindowFocus(require: boolean): Options; - - /** - * Configures the timeout, in milliseconds, that the driver will attempt to - * located and attach to a newly opened instance of Internet Explorer. The - * default is zero, which indicates waiting indefinitely. - * - * @param {number} timeout How long to wait for IE. - * @return {!Options} A self reference. - */ - browserAttachTimeout(timeout: number): Options; - - /** - * Configures whether to launch Internet Explorer using the CreateProcess API. - * If this option is not specified, IE is launched using IELaunchURL, if - * available. For IE 8 and above, this option requires the TabProcGrowth - * registry value to be set to 0. - * - * @param {boolean} force Whether to use the CreateProcess API. - * @return {!Options} A self reference. - */ - forceCreateProcessApi(force: boolean): Options; - - /** - * Specifies command-line switches to use when launching Internet Explorer. - * This is only valid when used with {@link #forceCreateProcessApi}. - * - * @param {...(string|!Array.)} var_args The arguments to add. - * @return {!Options} A self reference. - */ - addArguments(...var_args: string[]): Options; - - /** - * Configures whether proxies should be configured on a per-process basis. If - * not set, setting a {@linkplain #setProxy proxy} will configure the system - * proxy. The default behavior is to use the system proxy. - * - * @param {boolean} enable Whether to enable per-process proxy settings. - * @return {!Options} A self reference. - */ - usePerProcessProxy(enable: boolean): Options; - - /** - * Configures whether to clear the cache, cookies, history, and saved form data - * before starting the browser. _Using this capability will clear session data - * for all running instances of Internet Explorer, including those started - * manually._ - * - * @param {boolean} cleanSession Whether to clear all session data on startup. - * @return {!Options} A self reference. - */ - ensureCleanSession(cleanSession: boolean): Options; - - /** - * Sets the path to the log file the driver should log to. - * @param {string} file The log file path. - * @return {!Options} A self reference. - */ - setLogFile(file: string): Options; - - /** - * Sets the IEDriverServer's logging {@linkplain Level level}. - * @param {Level} level The logging level. - * @return {!Options} A self reference. - */ - setLogLevel(level: webdriver.logging.Level): Options; - - /** - * Sets the IP address of the driver's host adapter. - * @param {string} host The IP address to use. - * @return {!Options} A self reference. - */ - setHost(host: string): Options; - - /** - * Sets the path of the temporary data directory to use. - * @param {string} path The log file path. - * @return {!Options} A self reference. - */ - setExtractPath(path: string): Options; - - /** - * Sets whether the driver should start in silent mode. - * @param {boolean} silent Whether to run in silent mode. - * @return {!Options} A self reference. - */ - silent(silent: boolean): Options; - - /** - * Sets the proxy settings for the new session. - * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. - * @return {!Options} A self reference. - */ - setProxy(proxy: webdriver.ProxyConfig): Options; - - /** - * Converts this options instance to a {@link capabilities.Capabilities} - * object. - * @param {capabilities.Capabilities=} opt_capabilities The capabilities to - * merge these options into, if any. - * @return {!capabilities.Capabilities} The capabilities. - */ - toCapabilities(opt_capabilities?: webdriver.Capabilities): webdriver.Capabilities; -} diff --git a/typings/opera.d.ts b/typings/opera.d.ts deleted file mode 100644 index b4d118f6a..000000000 --- a/typings/opera.d.ts +++ /dev/null @@ -1,176 +0,0 @@ -import * as webdriver from './index'; -import * as remote from './remote'; - -/** - * Creates {@link remote.DriverService} instances that manages an - * [OperaDriver](https://github.com/operasoftware/operachromiumdriver) - * server in a child process. - */ -export class ServiceBuilder { - /** - * @param {string=} opt_exe Path to the server executable to use. If omitted, - * the builder will attempt to locate the operadriver on the current - * PATH. - * @throws {Error} If provided executable does not exist, or the operadriver - * cannot be found on the PATH. - */ - constructor(opt_exe?: string); - - /** - * Sets the port to start the OperaDriver on. - * @param {number} port The port to use, or 0 for any free port. - * @return {!ServiceBuilder} A self reference. - * @throws {Error} If the port is invalid. - */ - usingPort(port: number): ServiceBuilder; - - /** - * Sets the path of the log file the driver should log to. If a log file is - * not specified, the driver will log to stderr. - * @param {string} path Path of the log file to use. - * @return {!ServiceBuilder} A self reference. - */ - loggingTo(path: string): ServiceBuilder; - - /** - * Enables verbose logging. - * @return {!ServiceBuilder} A self reference. - */ - enableVerboseLogging(): ServiceBuilder; - - /** - * Silence sthe drivers output. - * @return {!ServiceBuilder} A self reference. - */ - silent(): ServiceBuilder; - - /** - * Defines the stdio configuration for the driver service. See - * {@code child_process.spawn} for more information. - * @param {(string|!Array)} - * config The configuration to use. - * @return {!ServiceBuilder} A self reference. - */ - setStdio(config: string | Array): ServiceBuilder; - - /** - * Defines the environment to start the server under. This settings will be - * inherited by every browser session started by the server. - * @param {!Object.} env The environment to use. - * @return {!ServiceBuilder} A self reference. - */ - withEnvironment(env: Object): ServiceBuilder; - - /** - * Creates a new DriverService using this instance's current configuration. - * @return {!remote.DriverService} A new driver service using this instance's - * current configuration. - * @throws {Error} If the driver exectuable was not specified and a default - * could not be found on the current PATH. - */ - build(): remote.DriverService; -} - -/** - * Sets the default service to use for new OperaDriver instances. - * @param {!remote.DriverService} service The service to use. - * @throws {Error} If the default service is currently running. - */ -export function setDefaultService(service: remote.DriverService): any; - -/** - * Returns the default OperaDriver service. If such a service has not been - * configured, one will be constructed using the default configuration for - * a OperaDriver executable found on the system PATH. - * @return {!remote.DriverService} The default OperaDriver service. - */ -export function getDefaultService(): remote.DriverService; - -/** - * Class for managing {@linkplain Driver OperaDriver} specific options. - */ -export class Options { - /** - * Extracts the OperaDriver specific options from the given capabilities - * object. - * @param {!capabilities.Capabilities} caps The capabilities object. - * @return {!Options} The OperaDriver options. - */ - static fromCapabilities(caps: webdriver.Capabilities): Options; - - /** - * Add additional command line arguments to use when launching the Opera - * browser. Each argument may be specified with or without the '--' prefix - * (e.g. '--foo' and 'foo'). Arguments with an associated value should be - * delimited by an '=': 'foo=bar'. - * @param {...(string|!Array.)} var_args The arguments to add. - * @return {!Options} A self reference. - */ - addArguments(...var_args: string[]): Options; - - /** - * Add additional extensions to install when launching Opera. Each extension - * should be specified as the path to the packed CRX file, or a Buffer for an - * extension. - * @param {...(string|!Buffer|!Array.<(string|!Buffer)>)} var_args The - * extensions to add. - * @return {!Options} A self reference. - */ - addExtensions(...var_args: any[]): Options; - - /** - * Sets the path to the Opera binary to use. On Mac OS X, this path should - * reference the actual Opera executable, not just the application binary. The - * binary path be absolute or relative to the operadriver server executable, but - * it must exist on the machine that will launch Opera. - * - * @param {string} path The path to the Opera binary to use. - * @return {!Options} A self reference. - */ - setOperaBinaryPath(path: string): Options; - - /** - * Sets the logging preferences for the new session. - * @param {!./lib/logging.Preferences} prefs The logging preferences. - * @return {!Options} A self reference. - */ - setLoggingPrefs(prefs: webdriver.logging.Preferences): Options; - - /** - * Sets the proxy settings for the new session. - * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. - * @return {!Options} A self reference. - */ - setProxy(proxy: webdriver.ProxyConfig): Options; - - /** - * Converts this options instance to a {@link capabilities.Capabilities} - * object. - * @param {capabilities.Capabilities=} opt_capabilities The capabilities to - * merge these options into, if any. - * @return {!capabilities.Capabilities} The capabilities. - */ - toCapabilities(opt_capabilities?: webdriver.Capabilities): webdriver.Capabilities; -} - -export class Driver extends webdriver.WebDriver { - /** - * Creates a new session for Opera. - * - * @param {(capabilities.Capabilities|Options)=} opt_config The configuration - * options. - * @param {remote.DriverService=} opt_service The session to use; will use - * the {@link getDefaultService default service} by default. - * @param {promise.ControlFlow=} opt_flow The control flow to use, - * or {@code null} to use the currently active flow. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: webdriver.Capabilities | Options, opt_service?: remote.DriverService, opt_flow?: webdriver.promise.ControlFlow): Driver; - - /** - * This function is a no-op as file detectors are not supported by this - * implementation. - * @override - */ - setFileDetector(): void; -} diff --git a/typings/remote.d.ts b/typings/remote.d.ts deleted file mode 100644 index 3ef73c953..000000000 --- a/typings/remote.d.ts +++ /dev/null @@ -1,242 +0,0 @@ -import * as webdriver from './index'; - -/** - * A record object that defines the configuration options for a DriverService - * instance. - * - * @record - */ -export interface ServiceOptions { } - -/** - * Manages the life and death of a native executable WebDriver server. - * - * It is expected that the driver server implements the - * https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol. - * Furthermore, the managed server should support multiple concurrent sessions, - * so that this class may be reused for multiple clients. - */ -export class DriverService { - /** - * @param {string} executable Path to the executable to run. - * @param {!ServiceOptions} options Configuration options for the service. - */ - constructor(executable: string, options: ServiceOptions); - - /** - * @return {!promise.Promise} A promise that resolves to - * the server's address. - * @throws {Error} If the server has not been started. - */ - address(): webdriver.promise.Promise; - - /** - * Returns whether the underlying process is still running. This does not take - * into account whether the process is in the process of shutting down. - * @return {boolean} Whether the underlying service process is running. - */ - isRunning(): boolean; - - /** - * Starts the server if it is not already running. - * @param {number=} opt_timeoutMs How long to wait, in milliseconds, for the - * server to start accepting requests. Defaults to 30 seconds. - * @return {!promise.Promise} A promise that will resolve - * to the server's base URL when it has started accepting requests. If the - * timeout expires before the server has started, the promise will be - * rejected. - */ - start(opt_timeoutMs?: number): webdriver.promise.Promise; - - /** - * Stops the service if it is not currently running. This function will kill - * the server immediately. To synchronize with the active control flow, use - * {@link #stop()}. - * @return {!promise.Promise} A promise that will be resolved when - * the server has been stopped. - */ - kill(): webdriver.promise.Promise; - - /** - * Schedules a task in the current control flow to stop the server if it is - * currently running. - * @return {!promise.Promise} A promise that will be resolved when - * the server has been stopped. - */ - stop(): webdriver.promise.Promise; -} - -export namespace DriverService { - /** - * Creates {@link DriverService} objects that manage a WebDriver server in a - * child process. - */ - class Builder { - /** - * @param {string} exe Path to the executable to use. This executable must - * accept the `--port` flag for defining the port to start the server on. - * @throws {Error} If the provided executable path does not exist. - */ - constructor(exe: string); - - /** - * Define additional command line arguments to use when starting the server. - * - * @param {...CommandLineFlag} var_args The arguments to include. - * @return {!THIS} A self reference. - * @this {THIS} - * @template THIS - */ - addArguments(...var_args: string[]): this; - - /** - * Sets the host name to access the server on. If specified, the - * {@linkplain #setLoopback() loopback} setting will be ignored. - * - * @param {string} hostname - * @return {!DriverService.Builder} A self reference. - */ - setHostname(hostname: string): this; - - /** - * Sets whether the service should be accessed at this host's loopback - * address. - * - * @param {boolean} loopback - * @return {!DriverService.Builder} A self reference. - */ - setLoopback(loopback: boolean): this; - - /** - * Sets the base path for WebDriver REST commands (e.g. "/wd/hub"). - * By default, the driver will accept commands relative to "/". - * - * @param {?string} basePath The base path to use, or `null` to use the - * default. - * @return {!DriverService.Builder} A self reference. - */ - setPath(basePath: string | null): this; - - /** - * Sets the port to start the server on. - * - * @param {number} port The port to use, or 0 for any free port. - * @return {!DriverService.Builder} A self reference. - * @throws {Error} If an invalid port is specified. - */ - setPort(port: number): this; - - /** - * Defines the environment to start the server under. This setting will be - * inherited by every browser session started by the server. By default, the - * server will inherit the enviroment of the current process. - * - * @param {(Map|Object|null)} env The desired - * environment to use, or `null` if the server should inherit the - * current environment. - * @return {!DriverService.Builder} A self reference. - */ - setEnvironment(env: Map | {[name: string]: string} | null): this; - - /** - * IO configuration for the spawned server process. For more information, - * refer to the documentation of `child_process.spawn`. - * - * @param {StdIoOptions} config The desired IO configuration. - * @return {!DriverService.Builder} A self reference. - * @see https://nodejs.org/dist/latest-v4.x/docs/api/child_process.html#child_process_options_stdio - */ - setStdio(config: any): this; - - /** - * Creates a new DriverService using this instance's current configuration. - * - * @return {!DriverService} A new driver service. - */ - build(): DriverService; - } -} - -/** - * Manages the life and death of the - * - * standalone Selenium server. - */ -export class SeleniumServer extends DriverService { - /** - * @param {string} jar Path to the Selenium server jar. - * @param {SeleniumServer.Options=} opt_options Configuration options for the - * server. - * @throws {Error} If the path to the Selenium jar is not specified or if an - * invalid port is specified. - **/ - constructor(jar: string, opt_options?: SeleniumServer.Options); -} - -export namespace SeleniumServer { - /** - * Options for the Selenium server - */ - interface Options { - /** Whether the server should only be accessed on this host's loopback address.*/ - loopback?: boolean; - - /** The port to start the server on (must be > 0). If the port is provided - as a promise, the service will wait for the promise to resolve before starting. */ - port?: number|webdriver.promise.IThenable; - - /** The arguments to pass to the service. If a promise is provided, the - service will wait for it to resolve before starting. */ - args?: string[]|webdriver.promise.IThenable; - - /** The arguments to pass to the JVM. If a promise is provided, the service - will wait for it to resolve before starting. */ - jvmArgs?: string[]|webdriver.promise.IThenable; - - /** The environment variables that should be visible to the server process. - Defaults to inheriting the current process's environment.*/ - env?: {[key: string]: string}; - - /** IO configuration for the spawned server process. For more information, - refer to the documentation of `child_process.spawn`*/ - stdio?: string|Array; - } -} - -/** - * A {@link webdriver.FileDetector} that may be used when running - * against a remote - * [Selenium server](http://selenium-release.storage.googleapis.com/index.html). - * - * When a file path on the local machine running this script is entered with - * {@link webdriver.WebElement#sendKeys WebElement#sendKeys}, this file detector - * will transfer the specified file to the Selenium server's host; the sendKeys - * command will be updated to use the transfered file's path. - * - * __Note:__ This class depends on a non-standard command supported on the - * Java Selenium server. The file detector will fail if used with a server that - * only supports standard WebDriver commands (such as the ChromeDriver). - * - * @final - */ -export class FileDetector extends webdriver.FileDetector { - /** - * @constructor - **/ - constructor(); - - /** - * Prepares a `file` for use with the remote browser. If the provided path - * does not reference a normal file (i.e. it does not exist or is a - * directory), then the promise returned by this method will be resolved with - * the original file path. Otherwise, this method will upload the file to the - * remote server, which will return the file's path on the remote system so - * it may be referenced in subsequent commands. - * - * @param {!webdriver.WebDriver} driver The driver for the current browser. - * @param {string} file The path of the file to process. - * @return {!webdriver.promise.Promise} A promise for the processed - * file path. - */ - handleFile(driver: webdriver.WebDriver, file: string): webdriver.promise.Promise; -} diff --git a/typings/safari.d.ts b/typings/safari.d.ts deleted file mode 100644 index bbeb88741..000000000 --- a/typings/safari.d.ts +++ /dev/null @@ -1,91 +0,0 @@ -import * as webdriver from './index'; - -export class Server { } - -/** - * @return {!Promise} A promise that will resolve with the path - * to Safari on the current system. - */ -export function findSafariExecutable(): any; - -/** - * @param {string} serverUrl The URL to connect to. - * @return {!Promise} A promise for the path to a file that Safari can - * open on start-up to trigger a new connection to the WebSocket server. - */ -export function createConnectFile(serverUrl: string): any; - -/** - * Deletes all session data files if so desired. - * @param {!Object} desiredCapabilities . - * @return {!Array} A list of promises for the deleted files. - */ -export function cleanSession(desiredCapabilities: webdriver.Capabilities): any[]; - -/** @return {string} . */ -export function getRandomString(): string; - -/** - * @implements {command.Executor} - */ -export class CommandExecutor { -} - -/** - * Configuration options specific to the {@link Driver SafariDriver}. - */ -export class Options { - /** - * Extracts the SafariDriver specific options from the given capabilities - * object. - * @param {!Capabilities} capabilities The capabilities object. - * @return {!Options} The ChromeDriver options. - */ - static fromCapabilities(capabilities: webdriver.Capabilities): Options; - - /** - * Sets whether to force Safari to start with a clean session. Enabling this - * option will cause all global browser data to be deleted. - * @param {boolean} clean Whether to make sure the session has no cookies, - * cache entries, local storage, or databases. - * @return {!Options} A self reference. - */ - setCleanSession(clean: boolean): Options; - - /** - * Sets the logging preferences for the new session. - * @param {!./lib/logging.Preferences} prefs The logging preferences. - * @return {!Options} A self reference. - */ - setLoggingPrefs(prefs: webdriver.logging.Preferences): Options; - - /** - * Converts this options instance to a {@link Capabilities} object. - * @param {Capabilities=} opt_capabilities The capabilities to - * merge these options into, if any. - * @return {!Capabilities} The capabilities. - */ - toCapabilities(opt_capabilities?: webdriver.Capabilities): webdriver.Capabilities; -} - -/** - * A WebDriver client for Safari. This class should never be instantiated - * directly; instead, use the {@linkplain ./builder.Builder Builder}: - * - * var driver = new Builder() - * .forBrowser('safari') - * .build(); - * - */ -export class Driver extends webdriver.WebDriver { - /** - * Creates a new Safari session. - * - * @param {(Options|Capabilities)=} opt_config The configuration - * options for the new session. - * @param {promise.ControlFlow=} opt_flow The control flow to create - * the driver under. - * @return {!Driver} A new driver instance. - */ - static createSession(opt_config?: Options | webdriver.Capabilities, opt_flow?: webdriver.promise.ControlFlow): Driver; -} diff --git a/typings/testing.d.ts b/typings/testing.d.ts deleted file mode 100644 index 85bf087df..000000000 --- a/typings/testing.d.ts +++ /dev/null @@ -1,106 +0,0 @@ -import { promise } from './index'; -import * as Testing from './testing'; - -export const describe: { - /** - * Registers a new test suite. - * @param name The suite name. - * @param fn The suite function, or {@code undefined} to define a pending test suite. - */ - (name: string, fn: Function): void; - - /** - * An alias for {@link #describe()} that marks the suite as exclusive, - * suppressing all other test suites. - * @param {string} name The suite name. - * @param {function()=} opt_fn The suite function, or `undefined` to define - * a pending test suite. - */ - only(name: string, fn: Function): void; - - /** - * Defines a suppressed test suite. - * @param name The suite name. - * @param fn The suite function, or {@code undefined} to define a pending test suite. - */ - skip(name: string, fn: Function): void; -}; - -/** - * Defines a suppressed test suite. - * @param name The suite name. - * @param fn The suite function, or {@code undefined} to define a pending test suite. - */ -export function xdescribe(name: string, fn: Function): void; - -/** - * Register a function to call after the current suite finishes. - * @param fn - */ -export function after(fn: Function): void; - -/** - * Register a function to call after each test in a suite. - * @param fn - */ -export function afterEach(fn: Function): void; - -/** - * Register a function to call before the current suite starts. - * @param fn - */ -export function before(fn: Function): void; - -/** - * Register a function to call before each test in a suite. - * @param fn - */ -export function beforeEach(fn: Function): void; - -export const it: { - /** - * Add a test to the current suite. - * @param name The test name. - * @param fn The test function, or {@code undefined} to define a pending test case. - */ - (name: string, fn: Function): void; - - /** - * An alias for {@link #it()} that flags the test as the only one that should - * be run within the current suite. - * @param {string} name The test name. - * @param {function()=} opt_fn The test function, or `undefined` to define - * a pending test case. - */ - only(name: string, fn: Function): void; - - /** - * Adds a test to the current suite while suppressing it so it is not run. - * @param name The test name. - * @param fn The test function, or {@code undefined} to define a pending test case. - */ - skip(name: string, fn: Function): void; -} - -/** - * Adds a test to the current suite while suppressing it so it is not run. - * @param name The test name. - * @param fn The test function, or {@code undefined} to define a pending test case. - */ -export function xit(name: string, fn: Function): void; - -/** - * @return {!promise.ControlFlow} the control flow instance used by this module - * to coordinate test actions. - */ -export function controlFlow(): promise.ControlFlow; - -/** - * Ignores the test chained to this function if the provided predicate returns - * true. - * @param {function(): boolean} predicateFn A predicate to call to determine - * if the test should be suppressed. This function MUST be synchronous. - * @return {!Object} An object with wrapped versions of {@link #it()} and - * {@link #describe()} that ignore tests as indicated by the predicate. - */ -export function ignore(predicateFn: () => boolean): typeof Testing;