From b272bb7fbf10f01b80775e187976c13bd6f5e968 Mon Sep 17 00:00:00 2001 From: Craig Nishina Date: Thu, 28 Mar 2019 18:04:39 -0700 Subject: [PATCH] chore(selenium): update to selenium-webdriver 4 typings - Update typings and tests - control flow and promise.Promise deprecated - API changes with regard to W3C - Moved previous typings to selenium-webdriver v3 - Set protractor-helpers to use selenium-webdriver v3 --- types/axe-webdriverjs/index.d.ts | 2 +- types/protractor-browser-logs/tsconfig.json | 8 + types/protractor-helpers/tsconfig.json | 8 + types/selenium-webdriver/chrome.d.ts | 578 +- types/selenium-webdriver/edge.d.ts | 98 +- types/selenium-webdriver/firefox.d.ts | 381 +- types/selenium-webdriver/http.d.ts | 126 +- types/selenium-webdriver/ie.d.ts | 339 +- types/selenium-webdriver/index.d.ts | 2600 ++------- types/selenium-webdriver/lib/by.d.ts | 140 + types/selenium-webdriver/lib/command.d.ts | 201 + types/selenium-webdriver/lib/input.d.ts | 355 ++ types/selenium-webdriver/lib/promise.d.ts | 120 + types/selenium-webdriver/lib/until.d.ts | 207 + types/selenium-webdriver/remote.d.ts | 332 +- types/selenium-webdriver/safari.d.ts | 64 +- types/selenium-webdriver/test/chrome.ts | 7 - types/selenium-webdriver/test/firefox.ts | 43 - types/selenium-webdriver/test/index.ts | 423 +- types/selenium-webdriver/tsconfig.json | 7 +- types/selenium-webdriver/v3/chrome.d.ts | 362 ++ types/selenium-webdriver/v3/edge.d.ts | 92 + types/selenium-webdriver/v3/firefox.d.ts | 335 ++ types/selenium-webdriver/v3/http.d.ts | 161 + types/selenium-webdriver/v3/ie.d.ts | 208 + types/selenium-webdriver/v3/index.d.ts | 4825 +++++++++++++++++ types/selenium-webdriver/{ => v3}/opera.d.ts | 0 types/selenium-webdriver/v3/remote.d.ts | 242 + types/selenium-webdriver/v3/safari.d.ts | 91 + types/selenium-webdriver/v3/test/chrome.ts | 62 + types/selenium-webdriver/v3/test/firefox.ts | 79 + types/selenium-webdriver/v3/test/index.ts | 991 ++++ types/selenium-webdriver/v3/test/remote.ts | 29 + .../{ => v3}/test/testing.ts | 0 .../selenium-webdriver/{ => v3}/testing.d.ts | 0 types/selenium-webdriver/v3/tsconfig.json | 45 + types/selenium-webdriver/v3/tslint.json | 22 + 37 files changed, 9951 insertions(+), 3632 deletions(-) create mode 100644 types/selenium-webdriver/lib/by.d.ts create mode 100644 types/selenium-webdriver/lib/command.d.ts create mode 100644 types/selenium-webdriver/lib/input.d.ts create mode 100644 types/selenium-webdriver/lib/promise.d.ts create mode 100644 types/selenium-webdriver/lib/until.d.ts create mode 100644 types/selenium-webdriver/v3/chrome.d.ts create mode 100644 types/selenium-webdriver/v3/edge.d.ts create mode 100644 types/selenium-webdriver/v3/firefox.d.ts create mode 100644 types/selenium-webdriver/v3/http.d.ts create mode 100644 types/selenium-webdriver/v3/ie.d.ts create mode 100644 types/selenium-webdriver/v3/index.d.ts rename types/selenium-webdriver/{ => v3}/opera.d.ts (100%) create mode 100644 types/selenium-webdriver/v3/remote.d.ts create mode 100644 types/selenium-webdriver/v3/safari.d.ts create mode 100644 types/selenium-webdriver/v3/test/chrome.ts create mode 100644 types/selenium-webdriver/v3/test/firefox.ts create mode 100644 types/selenium-webdriver/v3/test/index.ts create mode 100644 types/selenium-webdriver/v3/test/remote.ts rename types/selenium-webdriver/{ => v3}/test/testing.ts (100%) rename types/selenium-webdriver/{ => v3}/testing.d.ts (100%) create mode 100644 types/selenium-webdriver/v3/tsconfig.json create mode 100644 types/selenium-webdriver/v3/tslint.json diff --git a/types/axe-webdriverjs/index.d.ts b/types/axe-webdriverjs/index.d.ts index c3bf23f788..9c52819887 100644 --- a/types/axe-webdriverjs/index.d.ts +++ b/types/axe-webdriverjs/index.d.ts @@ -2,7 +2,7 @@ // Project: https://github.com/dequelabs/axe-webdriverjs#readme // Definitions by: Joshua Goldberg // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.3 +// TypeScript Version: 2.4 import { Result, RunOptions, Spec } from "axe-core"; import { WebDriver } from "selenium-webdriver"; diff --git a/types/protractor-browser-logs/tsconfig.json b/types/protractor-browser-logs/tsconfig.json index f0cfe8c279..c870c9a66d 100644 --- a/types/protractor-browser-logs/tsconfig.json +++ b/types/protractor-browser-logs/tsconfig.json @@ -13,6 +13,14 @@ "typeRoots": [ "../" ], + "paths": { + "selenium-webdriver": [ + "selenium-webdriver/v3" + ], + "selenium-webdriver/*": [ + "selenium-webdriver/v3/*" + ] + }, "types": [], "noEmit": true, "forceConsistentCasingInFileNames": true diff --git a/types/protractor-helpers/tsconfig.json b/types/protractor-helpers/tsconfig.json index 6a0cde55eb..f8057b3cb1 100644 --- a/types/protractor-helpers/tsconfig.json +++ b/types/protractor-helpers/tsconfig.json @@ -12,6 +12,14 @@ "typeRoots": [ "../" ], + "paths": { + "selenium-webdriver": [ + "selenium-webdriver/v3" + ], + "selenium-webdriver/*": [ + "selenium-webdriver/v3/*" + ] + }, "types": [], "noEmit": true, "forceConsistentCasingInFileNames": true diff --git a/types/selenium-webdriver/chrome.d.ts b/types/selenium-webdriver/chrome.d.ts index a5dbd2fd1f..e44191bd0f 100644 --- a/types/selenium-webdriver/chrome.d.ts +++ b/types/selenium-webdriver/chrome.d.ts @@ -1,6 +1,6 @@ +import * as http from './http'; import * as webdriver from './index'; import * as remote from './remote'; -import * as http from './http'; /** * Creates a new WebDriver client for Chrome. @@ -8,294 +8,282 @@ import * as http from './http'; * @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; + /** + * 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; + 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; + enableNetwork: boolean; + enablePage: boolean; + enableTimeline: boolean; + tracingCategories: string; + bufferUsageReportingInterval: number; } /** * Class for managing ChromeDriver specific options. */ -export class Options { - /** - * @constructor - */ - constructor(); +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; + /** + * 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; + /** + * 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; + /** + * 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; + /** + * 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; - /** - * 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; + /** + * 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; - /** - * 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; + /** + * 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 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 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 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 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 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 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 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 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 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; + /** + * 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; + /** + * 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 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 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 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 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; + /** + * 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; + /** + * 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; } /** @@ -303,47 +291,47 @@ export class Options { * 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); + /** + * @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 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; + /** + * 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; + /** + * 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; + /** + * 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; } /** diff --git a/types/selenium-webdriver/edge.d.ts b/types/selenium-webdriver/edge.d.ts index 90b45fc92d..508c997219 100644 --- a/types/selenium-webdriver/edge.d.ts +++ b/types/selenium-webdriver/edge.d.ts @@ -2,63 +2,45 @@ 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; + /** + * 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; + /** + * 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; +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 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; + /** + * 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; } /** @@ -66,14 +48,14 @@ export class Options { * 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); + /** + * @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); } /** diff --git a/types/selenium-webdriver/firefox.d.ts b/types/selenium-webdriver/firefox.d.ts index fcb8e74520..d08d5fcbb4 100644 --- a/types/selenium-webdriver/firefox.d.ts +++ b/types/selenium-webdriver/firefox.d.ts @@ -1,246 +1,46 @@ +import * as http from './http'; 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 { - /** - * Specify additional command line arguments that should be used when starting - * the Firefox browser. - * - * @param {...(string|!Array)} args The arguments to include. - * @return {!Options} A self reference. - */ - addArguments(...args: string[]): Options; +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 browser to be in headless mode. - * - * @return {!Options} A self reference. - */ - headless(): 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 initial window size when running in - * {@linkplain #headless headless} mode. - * - * @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; + /** + * Sets the proxy to use. + * + * @param {capabilities.ProxyConfig} proxy The proxy configuration to use. + * @return {!Options} A self reference. + */ + setProxy(proxy: webdriver.ProxyConfig): Options; - /** - * Add extensions that should be installed when starting Firefox. - * - * @param {...string} paths The paths to the extension XPI files to install. - * @return {!Options} A self reference. - */ - addExtensions(...paths: string[]): Options; - - /** - * @param {string} key the preference key. - * @param {(string|number|boolean)} value the preference value. - * @return {!Options} A self reference. - * @throws {TypeError} if either the key or value has an invalid type. - */ - setPreference(key: string, value: string | number | boolean): 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; + /** + * 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; } /** @@ -253,52 +53,51 @@ export function findWires(): string; * @param {(string|!Binary)} binary . * @return {!remote.DriverService} . */ -export function createWiresService(binary: string | any): 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; +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; + /** + * 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; + /** + * This function is a no-op as file detectors are not supported by this + * implementation. + * @override + */ + setFileDetector(): void; } /** @@ -307,29 +106,29 @@ export class Driver extends webdriver.WebDriver { * 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); + /** + * @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; + /** + * 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; + /** + * 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/types/selenium-webdriver/http.d.ts b/types/selenium-webdriver/http.d.ts index ac24c6f6d4..bbbe9eb371 100644 --- a/types/selenium-webdriver/http.d.ts +++ b/types/selenium-webdriver/http.d.ts @@ -14,20 +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); - headers: Map; - method: string; - path: string; - data: Object; - - /** @override */ - toString(): string; + /** @override */ + toString(): string; } /** @@ -35,20 +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); - status: number; - body: string; - headers: Map; - - /** @override */ - toString(): string; + /** @override */ + toString(): string; } export function post(path: string): any; @@ -60,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; } /** @@ -90,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. @@ -106,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/types/selenium-webdriver/ie.d.ts b/types/selenium-webdriver/ie.d.ts index bf3932450e..97fb2300e5 100644 --- a/types/selenium-webdriver/ie.d.ts +++ b/types/selenium-webdriver/ie.d.ts @@ -4,205 +4,188 @@ 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; + /** + * 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; + /** + * 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(); +export class Options extends webdriver.Capabilities { + 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; - /** - * 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; - /** - * 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; - /** - * 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 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 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 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 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; - /** - * 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; - /** - * 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 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; - /** - * 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 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 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 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 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 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; + /** + * 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/types/selenium-webdriver/index.d.ts b/types/selenium-webdriver/index.d.ts index 57a32a56b9..a6651c08ce 100644 --- a/types/selenium-webdriver/index.d.ts +++ b/types/selenium-webdriver/index.d.ts @@ -1,5 +1,5 @@ -// Type definitions for Selenium WebDriverJS 3.0 -// Project: https://github.com/SeleniumHQ/selenium/tree/master/javascript/node/selenium-webdriver, https://github.com/seleniumhq/selenium +// Type definitions for Selenium WebDriverJS 4.0 +// Project: https://github.com/SeleniumHQ/selenium // Definitions by: Bill Armstrong , // Yuki Kokubun , // Craig Nishina , @@ -7,18 +7,31 @@ // Ben Dixon , // Ziyu // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped -// TypeScript Version: 2.3 +// TypeScript Version: 2.4 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'; +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; } /** @@ -26,33 +39,50 @@ 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); } /** - * An element command could not be completed because the element is not visible - * on the page. + * 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 ElementNotVisibleError extends WebDriverError { - /** @param {string=} opt_error the error message, if any. */ - constructor(opt_error?: string); + + class ElementNotInteractableError extends WebDriverError { + constructor(message?: string); + } + + /** + * Indicates a navigation event caused the browser to generate a certificate + * warning. This is usually caused by an expired or invalid TLS certificate. + */ + 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); } /** @@ -60,67 +90,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); } /** @@ -128,8 +158,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); } /** @@ -137,8 +166,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); } /** @@ -146,24 +174,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); } /** @@ -171,44 +196,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. @@ -220,8 +236,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); } /** @@ -229,17 +244,60 @@ 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. + */ + function encodeError(err: any): {error: string, message: string}; } export namespace logging { @@ -583,694 +641,6 @@ export namespace logging { function removeConsoleHandler(opt_logger?: Logger): void; } -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; - - /** - * 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. */ @@ -1282,13 +652,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; } /** @@ -1302,516 +672,30 @@ 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; -} - +/** + * x,y + */ export interface ILocation { x: number; y: number; } +/** + * width, height + */ export interface ISize { 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} + * x,y,w,h */ -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; - - /** - * 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; - - // endregion +export interface IRectangle { + x: number; + y: number; + width: number; + height: number; } /** @@ -1828,17 +712,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. @@ -1910,7 +794,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; @@ -1926,11 +810,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; @@ -1955,10 +845,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 @@ -1967,34 +857,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 } @@ -2013,7 +903,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 @@ -2021,7 +915,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); } /** @@ -2043,8 +937,14 @@ export interface IBrowser { HTMLUNIT: string; } +/** + * Instace of + */ export const Browser: IBrowser; +/** + * ProxyConfig + */ export interface ProxyConfig { proxyType: string; proxyAutoconfigUrl?: string; @@ -2136,9 +1036,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. @@ -2158,8 +1058,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; @@ -2172,8 +1072,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; @@ -2189,31 +1089,6 @@ export class Builder { */ setChromeOptions(options: chrome.Options): Builder; - /** - * @return {chrome.Options} the Chrome specific options currently configured - * for this builder. - */ - getChromeOptions(): chrome.Options; - - /** - * Sets the service builder to use for managing the chromedriver child process - * when creating new Chrome sessions. - * - * @param {chrome.ServiceBuilder} service the service to use. - * @return {!Builder} A self reference. - */ - setChromeService(service: chrome.ServiceBuilder): 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 @@ -2225,22 +1100,6 @@ export class Builder { */ setEdgeOptions(options: edge.Options): Builder; - /** - * Sets the {@link edge.ServiceBuilder} to use to manage the - * MicrosoftEdgeDriver child process when creating sessions locally. - * - * @param {edge.ServiceBuilder} service the service to use. - * @return {!Builder} a self reference. - */ - setEdgeService(service: edge.ServiceBuilder): 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 @@ -2252,21 +1111,6 @@ export class Builder { */ setFirefoxOptions(options: firefox.Options): Builder; - /** - * @return {firefox.Options} the Firefox specific options currently configured - * for this instance. - */ - getFirefoxOptions(): firefox.Options; - - /** - * Sets the {@link firefox.ServiceBuilder} to use to manage the geckodriver - * child process when creating Firefox sessions locally. - * - * @param {firefox.ServiceBuilder} service the service to use. - * @return {!Builder} a self reference. - */ - setFirefoxService(service: firefox.ServiceBuilder): Builder; - /** * Set Internet Explorer specific {@linkplain ie.Options options} for drivers * created by this builder. Any proxy settings defined on the given options @@ -2284,18 +1128,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 @@ -2314,25 +1147,12 @@ export class Builder { * @param {!safari.Options} options The Safari options to use. * @return {!Builder} A self reference. */ - setSafariOptions(options: safari.Options): Builder; - - /** - * @return {safari.Options} the Safari specific options currently configured - * for this instance. - */ - getSafariOptions(): safari.Options; - - /** - * 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; + setSafari(options: safari.Options): 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. @@ -2340,9 +1160,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. @@ -2369,148 +1190,11 @@ 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; /** @@ -2553,7 +1237,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; @@ -2605,8 +1289,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 @@ -2615,7 +1305,7 @@ export class Capabilities { * capabilities to merge into this instance. * @constructor */ - constructor(opt_other?: Capabilities | Object); + constructor(opt_other?: Capabilities|{}); // endregion @@ -2631,7 +1321,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. @@ -2649,7 +1339,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. @@ -2667,8 +1357,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; @@ -2676,8 +1366,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; @@ -2765,187 +1455,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}. * @interface @@ -2958,10 +1467,10 @@ 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 + execute(command: Command): Promise; } /** @@ -2974,7 +1483,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); } /** @@ -3014,7 +1523,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 @@ -3026,7 +1536,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; @@ -3035,7 +1546,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; @@ -3068,8 +1580,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() * @@ -3084,31 +1596,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 } @@ -3150,28 +1662,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; } /** @@ -3193,51 +1705,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 @@ -3246,10 +1758,14 @@ export class Options { logs(): Logs; /** - * @return {!Timeouts} The interface for managing driver - * timeouts. + * The current timeouts */ - timeouts(): Timeouts; + getTimeouts(): Promise; + + /** + * Set current timeouts + */ + setTimeouts(timeouts: ITimeouts): Promise; /** * @return {!Window} The interface for managing the @@ -3260,25 +1776,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; /** - * Specifies the amount of time the driver should wait when searching for an - * element if it is not immediately present. + * 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 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 @@ -3292,34 +1805,8 @@ 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; } /** @@ -3341,45 +1828,57 @@ 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; + + /** + * Returns the current top-level window's size and position. + */ + getRect(): Promise; + + /** + * Sets the current top-level window's size and position. You may update + * just the size by omitting `x` & `y`, or just the position by omitting + * `width` & `height` options. + */ + setRect({x, y, width, height}: Partial): Promise; /** * 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 } @@ -3410,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 } @@ -3451,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 @@ -3474,10 +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. */ - 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 @@ -3489,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 @@ -3535,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 @@ -3570,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. * @@ -3651,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 @@ -3684,26 +2162,28 @@ export class WebDriver { */ setFileDetector(detector: FileDetector): void; - /** - * @return {!promise.Promise.} A promise for this - * client's session. - */ - getSession(): promise.Promise; + getExecutor(): Executor; /** - * @return {!promise.Promise.} A promise + * @return {!Promise.} A promise for this + * client's session. + */ + getSession(): 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; + quit(): Promise; /** * Creates a new action sequence using this driver. The sequence will not be @@ -3718,21 +2198,7 @@ export class WebDriver { * * @return {!actions.ActionSequence} A new action sequence for this instance. */ - actions(): ActionSequence; - - /** - * 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; + actions(options?: {async: boolean, bridge: boolean}|{async: boolean}|{bridge: boolean}): Actions; /** * Schedules a command to execute JavaScript in the context of the currently @@ -3744,8 +2210,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 @@ -3767,32 +2233,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} @@ -3825,9 +2291,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]; @@ -3845,33 +2311,21 @@ 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; - - /** - * 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; + executeAsyncScript(script: string|Function, ...var_args: any[]): 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. @@ -3880,21 +2334,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'); @@ -3911,17 +2365,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. @@ -3930,27 +2385,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 @@ -3958,73 +2413,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 @@ -4068,10 +2526,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 @@ -4082,10 +2540,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 @@ -4121,14 +2579,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 @@ -4158,10 +2614,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 @@ -4193,8 +2649,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]')); @@ -4216,51 +2672,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: + * 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 + *

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: @@ -4269,81 +2724,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 } @@ -4397,10 +2858,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; } /** @@ -4420,7 +2881,7 @@ export interface Serializable { * * @return {!(T|IThenable.)} This instance's serialized wire format. */ - serialize(): T | promise.IThenable; + serialize(): T|Promise; } /** @@ -4452,14 +2913,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. @@ -4481,10 +2942,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. @@ -4492,10 +2953,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 @@ -4543,28 +3004,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 @@ -4579,8 +3041,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 @@ -4603,44 +3065,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: @@ -4659,76 +3121,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 @@ -4737,13 +3207,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; } /** @@ -4761,22 +3231,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); } /** @@ -4791,7 +3265,7 @@ export class Session { * capabilities. * @constructor */ - constructor(id: string, capabilities: Capabilities | Object); + constructor(id: string, capabilities: Capabilities|{}); // endregion diff --git a/types/selenium-webdriver/lib/by.d.ts b/types/selenium-webdriver/lib/by.d.ts new file mode 100644 index 0000000000..b57014c9ed --- /dev/null +++ b/types/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/types/selenium-webdriver/lib/command.d.ts b/types/selenium-webdriver/lib/command.d.ts new file mode 100644 index 0000000000..bfde48c237 --- /dev/null +++ b/types/selenium-webdriver/lib/command.d.ts @@ -0,0 +1,201 @@ +/** + * 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/types/selenium-webdriver/lib/input.d.ts b/types/selenium-webdriver/lib/input.d.ts new file mode 100644 index 0000000000..1a4a396c71 --- /dev/null +++ b/types/selenium-webdriver/lib/input.d.ts @@ -0,0 +1,355 @@ +import { Executor, ILocation, WebDriver, WebElement } from '../'; + +/** + * 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; + +export 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/types/selenium-webdriver/lib/promise.d.ts b/types/selenium-webdriver/lib/promise.d.ts new file mode 100644 index 0000000000..699ebf020c --- /dev/null +++ b/types/selenium-webdriver/lib/promise.d.ts @@ -0,0 +1,120 @@ +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/types/selenium-webdriver/lib/until.d.ts b/types/selenium-webdriver/lib/until.d.ts new file mode 100644 index 0000000000..6f439e7637 --- /dev/null +++ b/types/selenium-webdriver/lib/until.d.ts @@ -0,0 +1,207 @@ +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/types/selenium-webdriver/remote.d.ts b/types/selenium-webdriver/remote.d.ts index 3ef73c953d..5df3698ce4 100644 --- a/types/selenium-webdriver/remote.d.ts +++ b/types/selenium-webdriver/remote.d.ts @@ -6,7 +6,7 @@ import * as webdriver from './index'; * * @record */ -export interface ServiceOptions { } +export interface ServiceOptions {} /** * Manages the life and death of a native executable WebDriver server. @@ -17,144 +17,136 @@ export interface ServiceOptions { } * 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); + /** + * @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; + /** + * @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; + /** + * 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; + /** + * 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(): 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; + /** + * 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 { /** - * Creates {@link DriverService} objects that manage a WebDriver server in a - * child process. + * @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. */ - 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); + 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; + /** + * 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 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 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 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; + /** + * 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; + /** + * 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; + /** + * 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; - } + /** + * Creates a new DriverService using this instance's current configuration. + * + * @return {!DriverService} A new driver service. + */ + build(): DriverService; + } } /** @@ -163,44 +155,44 @@ export namespace DriverService { * 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); + /** + * @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; + /** + * 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 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[]|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[]|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[]|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[]|Promise; - /** The environment variables that should be visible to the server process. - Defaults to inheriting the current process's environment.*/ - env?: {[key: string]: string}; + /** 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; - } + /** IO configuration for the spawned server process. For more information, + refer to the documentation of `child_process.spawn`*/ + stdio?: string|Array; + } } /** @@ -220,23 +212,23 @@ export namespace SeleniumServer { * @final */ export class FileDetector extends webdriver.FileDetector { - /** - * @constructor - **/ - constructor(); + /** + * @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; + /** + * 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/types/selenium-webdriver/safari.d.ts b/types/selenium-webdriver/safari.d.ts index bbeb887410..eee4e567fb 100644 --- a/types/selenium-webdriver/safari.d.ts +++ b/types/selenium-webdriver/safari.d.ts @@ -1,12 +1,12 @@ import * as webdriver from './index'; -export class Server { } +export class Server {} /** * @return {!Promise} A promise that will resolve with the path * to Safari on the current system. */ -export function findSafariExecutable(): any; +export function findSafariDriver(): any; /** * @param {string} serverUrl The URL to connect to. @@ -28,44 +28,18 @@ export function getRandomString(): string; /** * @implements {command.Executor} */ -export class CommandExecutor { -} +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; +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; } /** @@ -78,14 +52,12 @@ export class Options { * */ 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; + /** + * 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/types/selenium-webdriver/test/chrome.ts b/types/selenium-webdriver/test/chrome.ts index 5301934933..b5f2329325 100644 --- a/types/selenium-webdriver/test/chrome.ts +++ b/types/selenium-webdriver/test/chrome.ts @@ -5,9 +5,6 @@ import * as webdriver from 'selenium-webdriver'; function TestChromeDriver() { let driver: chrome.Driver = chrome.Driver.createSession(); driver = chrome.Driver.createSession(webdriver.Capabilities.chrome()); - driver = chrome.Driver.createSession(webdriver.Capabilities.chrome(), - new remote.DriverService('executable', new chrome.Options()), - new webdriver.promise.ControlFlow()); let baseDriver: webdriver.WebDriver = driver; } @@ -30,14 +27,10 @@ function TestChromeOptions() { options = options.androidPackage('com.android.chrome'); options = options.androidProcess('com.android.chrome'); options = options.androidUseRunningApp(true); - options = options.setLoggingPrefs(new webdriver.logging.Preferences()); options = options.setPerfLoggingPrefs({ enableNetwork: true, enablePage: true, enableTimeline: true, tracingCategories: 'category', bufferUsageReportingInterval: 1000 }); - options = options.setProxy({ proxyType: 'proxyType' }); options = options.setUserPreferences('preferences'); - let capabilities: webdriver.Capabilities = options.toCapabilities(); - capabilities = options.toCapabilities(webdriver.Capabilities.chrome()); } function TestServiceBuilder() { diff --git a/types/selenium-webdriver/test/firefox.ts b/types/selenium-webdriver/test/firefox.ts index ee5b55bbaa..550f5e82cb 100644 --- a/types/selenium-webdriver/test/firefox.ts +++ b/types/selenium-webdriver/test/firefox.ts @@ -3,21 +3,11 @@ import * as remote from 'selenium-webdriver/remote'; import * as webdriver from 'selenium-webdriver'; import * as http from 'selenium-webdriver/http'; -function TestBinary() { - let binary: firefox.Binary = new firefox.Binary(); - binary = new firefox.Binary('exe'); - - binary.addArguments('A', 'B', 'C'); - let promise: webdriver.promise.Promise = binary.kill(); - binary.launch('profile').then((result: any) => {}); -} - function TestFirefoxDriver() { let driver: firefox.Driver = firefox.Driver.createSession(); driver = firefox.Driver.createSession(webdriver.Capabilities.firefox()); driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new http.Executor(new http.HttpClient('http://someurl'))); driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new remote.DriverService('/dev/null', {})); - driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new remote.DriverService('/dev/null', {}), new webdriver.promise.ControlFlow()); let baseDriver: webdriver.WebDriver = driver; } @@ -25,41 +15,9 @@ function TestFirefoxDriver() { function TestFirefoxOptions() { let options: firefox.Options = new firefox.Options(); - options = options.addArguments('foo', 'bar'); - options = options.windowSize({ width: 320, height: 480 }); - options = options.addExtensions('foo', 'bar'); - options = options.setPreference('a', 1); - options = options.setPreference('a', true); - options = options.setPreference('a', '1'); options = options.setBinary('binary'); - options = options.setBinary(new firefox.Binary()); - options = options.setLoggingPreferences(new webdriver.logging.Preferences()); options = options.setProfile('profile'); - options = options.setProfile(new firefox.Profile()); options = options.setProxy({ proxyType: 'proxy' }); - let capabilities: webdriver.Capabilities = options.toCapabilities(); -} - -function TestFirefoxProfile() { - let profile: firefox.Profile = new firefox.Profile(); - profile = new firefox.Profile('dir'); - - let bool: boolean = profile.acceptUntrustedCerts(); - profile.addExtension('ext'); - bool = profile.assumeUntrustedCertIssuer(); - profile.encode().then((prof: string) => {}); - let num: number = profile.getPort(); - let anything: any = profile.getPreference('key'); - bool = profile.nativeEventsEnabled(); - profile.setAcceptUntrustedCerts(true); - profile.setAssumeUntrustedCertIssuer(true); - profile.setNativeEventsEnabled(true); - profile.setPort(8080); - profile.setPreference('key', 'value'); - profile.setPreference('key', 5); - profile.setPreference('key', true); - let stringPromise: webdriver.promise.Promise = profile.writeToDisk(); - stringPromise = profile.writeToDisk(true); } function TestServiceBuilder() { @@ -71,7 +29,6 @@ function TestServiceBuilder() { builder = builder.enableVerboseLogging(); builder = builder.enableVerboseLogging(true); builder = builder.setFirefoxBinary('exe'); - builder = builder.setFirefoxBinary(new firefox.Binary()); builder = builder.setPath('path'); builder = builder.setStdio('config'); builder = builder.setStdio(['A', 'B']); diff --git a/types/selenium-webdriver/test/index.ts b/types/selenium-webdriver/test/index.ts index 84ffc6a8c2..7031208fa1 100644 --- a/types/selenium-webdriver/test/index.ts +++ b/types/selenium-webdriver/test/index.ts @@ -3,9 +3,6 @@ import * as chrome from 'selenium-webdriver/chrome'; import * as edge from 'selenium-webdriver/edge'; import * as firefox from 'selenium-webdriver/firefox'; import * as http from 'selenium-webdriver/http'; -import * as remote from 'selenium-webdriver/remote'; -import * as safari from 'selenium-webdriver/safari'; -import * as testing from 'selenium-webdriver/testing'; function TestBuilder() { let builder: webdriver.Builder = new webdriver.Builder(); @@ -20,82 +17,14 @@ function TestBuilder() { builder = builder.setAlertBehavior('behavior'); builder = builder.setChromeOptions(new chrome.Options()); - builder = builder.setChromeService(new chrome.ServiceBuilder()); - builder = builder.setControlFlow(new webdriver.promise.ControlFlow()); builder = builder.setEdgeOptions(new edge.Options()); - builder = builder.setEdgeService(new edge.ServiceBuilder()); - builder = builder.setEnableNativeEvents(true); builder = builder.setFirefoxOptions(new firefox.Options()); - builder = builder.setFirefoxService(new firefox.ServiceBuilder()); builder = builder.setLoggingPrefs(new webdriver.logging.Preferences()); builder = builder.setLoggingPrefs({ key: 'value' }); builder = builder.setProxy({ proxyType: 'type' }); - builder = builder.setSafariOptions(new safari.Options()); - builder = builder.setScrollBehavior(1); builder = builder.usingServer('http://someserver'); builder = builder.withCapabilities(new webdriver.Capabilities()); builder = builder.withCapabilities({ something: true }); - - const chromeOptions: chrome.Options = builder.getChromeOptions(); - const firefoxOptions: firefox.Options = builder.getFirefoxOptions(); - const safariOptions: safari.Options = builder.getSafariOptions(); -} - -declare const promise: webdriver.promise.Promise; - -function TestActionSequence() { - let driver: webdriver.WebDriver = new webdriver.Builder(). - withCapabilities(webdriver.Capabilities.chrome()). - build(); - - let sequence: webdriver.ActionSequence = new webdriver.ActionSequence(driver); - let element: webdriver.WebElement = new webdriver.WebElement(driver, 'elementId'); - element = new webdriver.WebElement(driver, promise); - - // Click - sequence = sequence.click(); - sequence = sequence.click(webdriver.Button.LEFT); - sequence = sequence.click(element); - sequence = sequence.click(element, webdriver.Button.LEFT); - - // DoubleClick - sequence = sequence.doubleClick(); - sequence = sequence.doubleClick(webdriver.Button.LEFT); - sequence = sequence.doubleClick(element); - sequence = sequence.doubleClick(element, webdriver.Button.LEFT); - - // DragAndDrop - sequence = sequence.dragAndDrop(element, element); - sequence = sequence.dragAndDrop(element, { x: 1, y: 2 }); - - // KeyDown - sequence = sequence.keyDown(webdriver.Key.ADD); - - // KeyUp - sequence = sequence.keyUp(webdriver.Key.ADD); - - // MouseDown - sequence = sequence.mouseDown(); - sequence = sequence.mouseDown(webdriver.Button.LEFT); - sequence = sequence.mouseDown(element); - sequence = sequence.mouseDown(element, webdriver.Button.LEFT); - - // MouseMove - sequence = sequence.mouseMove(element); - sequence = sequence.mouseMove({ x: 1, y: 1 }); - sequence = sequence.mouseMove(element, { x: 1, y: 2 }); - - // MouseUp - sequence = sequence.mouseUp(); - sequence = sequence.mouseUp(webdriver.Button.LEFT); - sequence = sequence.mouseUp(element); - sequence = sequence.mouseUp(element, webdriver.Button.LEFT); - - // SendKeys - sequence = sequence.sendKeys('A', 'B', 'C'); - sequence = sequence.sendKeys('A', webdriver.Key.NULL); - - sequence.perform().then(() => {}); } function TestTouchSequence() { @@ -148,14 +77,6 @@ function TestBrowser() { browser = webdriver.Browser.SAFARI; } -function TestButton() { - let button: string; - - button = webdriver.Button.LEFT; - button = webdriver.Button.MIDDLE; - button = webdriver.Button.RIGHT; -} - function TestCapabilities() { let capabilities: webdriver.Capabilities = new webdriver.Capabilities(); capabilities = new webdriver.Capabilities(webdriver.Capabilities.chrome()); @@ -213,119 +134,6 @@ function TestCapability() { capability = webdriver.Capability.VERSION; } -function TestCommand() { - let command: webdriver.Command = new webdriver.Command(webdriver.CommandName.ADD_COOKIE); - - let name: string = command.getName(); - let param: any = command.getParameter('param'); - - let params: any = command.getParameters(); - - command = command.setParameter('param', 123); - command = command.setParameters({ param: 123 }); -} - -function TestCommandName() { - let command: string; - - command = webdriver.CommandName.ACCEPT_ALERT; - command = webdriver.CommandName.ADD_COOKIE; - command = webdriver.CommandName.CLEAR_APP_CACHE; - command = webdriver.CommandName.CLEAR_ELEMENT; - command = webdriver.CommandName.CLEAR_LOCAL_STORAGE; - command = webdriver.CommandName.CLEAR_SESSION_STORAGE; - command = webdriver.CommandName.CLICK; - command = webdriver.CommandName.CLICK_ELEMENT; - command = webdriver.CommandName.CLOSE; - command = webdriver.CommandName.DELETE_ALL_COOKIES; - command = webdriver.CommandName.DELETE_COOKIE; - command = webdriver.CommandName.DESCRIBE_SESSION; - command = webdriver.CommandName.DISMISS_ALERT; - command = webdriver.CommandName.DOUBLE_CLICK; - command = webdriver.CommandName.ELEMENT_EQUALS; - command = webdriver.CommandName.EXECUTE_ASYNC_SCRIPT; - command = webdriver.CommandName.EXECUTE_SCRIPT; - command = webdriver.CommandName.EXECUTE_SQL; - command = webdriver.CommandName.FIND_CHILD_ELEMENT; - command = webdriver.CommandName.FIND_CHILD_ELEMENTS; - command = webdriver.CommandName.FIND_ELEMENT; - command = webdriver.CommandName.FIND_ELEMENTS; - command = webdriver.CommandName.GET; - command = webdriver.CommandName.GET_ACTIVE_ELEMENT; - command = webdriver.CommandName.GET_ALERT_TEXT; - command = webdriver.CommandName.GET_ALL_COOKIES; - command = webdriver.CommandName.GET_APP_CACHE; - command = webdriver.CommandName.GET_APP_CACHE_STATUS; - command = webdriver.CommandName.GET_AVAILABLE_LOG_TYPES; - command = webdriver.CommandName.GET_COOKIE; - command = webdriver.CommandName.GET_CURRENT_URL; - command = webdriver.CommandName.GET_CURRENT_WINDOW_HANDLE; - command = webdriver.CommandName.GET_ELEMENT_ATTRIBUTE; - command = webdriver.CommandName.GET_ELEMENT_LOCATION; - command = webdriver.CommandName.GET_ELEMENT_LOCATION_IN_VIEW; - command = webdriver.CommandName.GET_ELEMENT_SIZE; - command = webdriver.CommandName.GET_ELEMENT_TAG_NAME; - command = webdriver.CommandName.GET_ELEMENT_TEXT; - command = webdriver.CommandName.GET_ELEMENT_VALUE_OF_CSS_PROPERTY; - command = webdriver.CommandName.GET_LOCAL_STORAGE_ITEM; - command = webdriver.CommandName.GET_LOCAL_STORAGE_KEYS; - command = webdriver.CommandName.GET_LOCAL_STORAGE_SIZE; - command = webdriver.CommandName.GET_LOCATION; - command = webdriver.CommandName.GET_LOG; - command = webdriver.CommandName.GET_PAGE_SOURCE; - command = webdriver.CommandName.GET_SCREEN_ORIENTATION; - command = webdriver.CommandName.GET_SERVER_STATUS; - command = webdriver.CommandName.GET_SESSION_LOGS; - command = webdriver.CommandName.GET_SESSION_STORAGE_ITEM; - command = webdriver.CommandName.GET_SESSION_STORAGE_KEYS; - command = webdriver.CommandName.GET_SESSION_STORAGE_SIZE; - command = webdriver.CommandName.GET_SESSIONS; - command = webdriver.CommandName.GET_TITLE; - command = webdriver.CommandName.GET_WINDOW_HANDLES; - command = webdriver.CommandName.GET_WINDOW_POSITION; - command = webdriver.CommandName.GET_WINDOW_SIZE; - command = webdriver.CommandName.GO_BACK; - command = webdriver.CommandName.GO_FORWARD; - command = webdriver.CommandName.IMPLICITLY_WAIT; - command = webdriver.CommandName.IS_BROWSER_ONLINE; - command = webdriver.CommandName.IS_ELEMENT_DISPLAYED; - command = webdriver.CommandName.IS_ELEMENT_ENABLED; - command = webdriver.CommandName.IS_ELEMENT_SELECTED; - command = webdriver.CommandName.MAXIMIZE_WINDOW; - command = webdriver.CommandName.MOUSE_DOWN; - command = webdriver.CommandName.MOUSE_UP; - command = webdriver.CommandName.MOVE_TO; - command = webdriver.CommandName.NEW_SESSION; - command = webdriver.CommandName.QUIT; - command = webdriver.CommandName.REFRESH; - command = webdriver.CommandName.REMOVE_LOCAL_STORAGE_ITEM; - command = webdriver.CommandName.REMOVE_SESSION_STORAGE_ITEM; - command = webdriver.CommandName.SCREENSHOT; - command = webdriver.CommandName.SEND_KEYS_TO_ACTIVE_ELEMENT; - command = webdriver.CommandName.SEND_KEYS_TO_ELEMENT; - command = webdriver.CommandName.SET_ALERT_TEXT; - command = webdriver.CommandName.SET_BROWSER_ONLINE; - command = webdriver.CommandName.SET_LOCAL_STORAGE_ITEM; - command = webdriver.CommandName.SET_LOCATION; - command = webdriver.CommandName.SET_SCREEN_ORIENTATION; - command = webdriver.CommandName.SET_SCRIPT_TIMEOUT; - command = webdriver.CommandName.SET_SESSION_STORAGE_ITEM; - command = webdriver.CommandName.SET_TIMEOUT; - command = webdriver.CommandName.SET_WINDOW_POSITION; - command = webdriver.CommandName.SET_WINDOW_SIZE; - command = webdriver.CommandName.SUBMIT_ELEMENT; - command = webdriver.CommandName.SWITCH_TO_FRAME; - command = webdriver.CommandName.SWITCH_TO_WINDOW; - command = webdriver.CommandName.TOUCH_DOUBLE_TAP; - command = webdriver.CommandName.TOUCH_DOWN; - command = webdriver.CommandName.TOUCH_FLICK; - command = webdriver.CommandName.TOUCH_LONG_PRESS; - command = webdriver.CommandName.TOUCH_MOVE; - command = webdriver.CommandName.TOUCH_SCROLL; - command = webdriver.CommandName.TOUCH_SINGLE_TAP; - command = webdriver.CommandName.TOUCH_UP; -} - function TestEventEmitter() { let emitter: webdriver.EventEmitter = new webdriver.EventEmitter(); @@ -510,7 +318,7 @@ function TestWebDriverOptions() { build(); let options: webdriver.Options = new webdriver.Options(driver); - let promise: webdriver.promise.Promise; + let promise: Promise; let name: string = 'name'; let value: string = 'value'; @@ -536,7 +344,6 @@ function TestWebDriverOptions() { options.getCookies().then((cookies: webdriver.IWebDriverCookie[]) => { }); let logs: webdriver.Logs = options.logs(); - let timeouts: webdriver.Timeouts = options.timeouts(); let window: webdriver.Window = options.window(); } @@ -546,7 +353,7 @@ function TestWebDriverTargetLocator() { build(); let locator: webdriver.TargetLocator = new webdriver.TargetLocator(driver); - let promise: webdriver.promise.Promise; + let promise: Promise; let element: webdriver.WebElement = locator.activeElement(); let alert: webdriver.Alert = locator.alert(); @@ -555,28 +362,15 @@ function TestWebDriverTargetLocator() { promise = locator.window('nameOrHandle'); } -function TestWebDriverTimeouts() { - let driver: webdriver.WebDriver = new webdriver.Builder(). - withCapabilities(webdriver.Capabilities.chrome()). - build(); - - let timeouts: webdriver.Timeouts = new webdriver.Timeouts(driver); - let promise: webdriver.promise.Promise; - - promise = timeouts.implicitlyWait(123); - promise = timeouts.pageLoadTimeout(123); - promise = timeouts.setScriptTimeout(123); -} - function TestWebDriverWindow() { let driver: webdriver.WebDriver = new webdriver.Builder(). withCapabilities(webdriver.Capabilities.chrome()). build(); let window: webdriver.Window = new webdriver.Window(driver); - let locationPromise: webdriver.promise.Promise; - let sizePromise: webdriver.promise.Promise; - let voidPromise: webdriver.promise.Promise; + let locationPromise: Promise; + let sizePromise: Promise; + let voidPromise: Promise; locationPromise = window.getPosition(); sizePromise = window.getSize(); @@ -585,8 +379,8 @@ function TestWebDriverWindow() { voidPromise = window.setSize(12, 34); } -declare const sessionPromise: webdriver.promise.Promise; -declare let booleanPromise: webdriver.promise.Promise; +declare const sessionPromise: Promise; +declare let booleanPromise: Promise; declare const booleanCondition: webdriver.Condition; declare const webElementCondition: webdriver.WebElementCondition; @@ -594,27 +388,14 @@ function TestWebDriver() { let session: webdriver.Session = new webdriver.Session('ABC', webdriver.Capabilities.android()); let httpClient: http.HttpClient = new http.HttpClient('http://someserver'); let executor: http.Executor = new http.Executor(httpClient); - let flow: webdriver.promise.ControlFlow = new webdriver.promise.ControlFlow(); let driver: webdriver.WebDriver = new webdriver.WebDriver(session, executor); - driver = new webdriver.WebDriver(session, executor, flow); driver = new webdriver.WebDriver(sessionPromise, executor); - driver = new webdriver.WebDriver(sessionPromise, executor, flow); - let voidPromise: webdriver.promise.Promise; - let stringPromise: webdriver.promise.Promise; + let voidPromise: Promise; + let stringPromise: Promise; let webElementPromise: webdriver.WebElementPromise; - let actions: webdriver.ActionSequence = driver.actions(); - let touchActions: webdriver.TouchSequence = driver.touchActions(); - - // call - stringPromise = driver.call(() => 'value'); - stringPromise = driver.call(() => stringPromise); - stringPromise = driver.call(() => 'value', driver); - stringPromise = driver.call((a: number) => 'value', driver, 1); - voidPromise = driver.close(); - flow = driver.controlFlow(); // executeAsyncScript stringPromise = driver.executeAsyncScript('function(){}'); @@ -654,7 +435,6 @@ function TestWebDriver() { driver.setFileDetector(fileDetector); voidPromise = driver.quit(); - voidPromise = driver.schedule(new webdriver.Command(webdriver.CommandName.CLICK), 'ABC'); voidPromise = driver.sleep(123); stringPromise = driver.takeScreenshot(); @@ -662,20 +442,19 @@ function TestWebDriver() { booleanPromise = driver.wait(booleanCondition); booleanPromise = driver.wait((driver: webdriver.WebDriver) => true); booleanPromise = driver.wait((driver: webdriver.WebDriver) => Promise.resolve(true)); - booleanPromise = driver.wait((driver: webdriver.WebDriver) => webdriver.promise.Promise.resolve(true)); + booleanPromise = driver.wait((driver: webdriver.WebDriver) => Promise.resolve(true)); booleanPromise = driver.wait(booleanPromise, 123); booleanPromise = driver.wait(booleanPromise, 123, 'Message'); webElementPromise = driver.wait(webElementCondition); voidPromise = driver.wait(webElementCondition).click(); - driver = webdriver.WebDriver.attachToSession(executor, 'ABC'); driver = webdriver.WebDriver.createSession(executor, webdriver.Capabilities.android()); } declare const serializable: webdriver.Serializable; function TestSerializable() { - let serial: string | webdriver.promise.IThenable = serializable.serialize(); + let serial: string | Promise = serializable.serialize(); } function TestWebElement() { @@ -686,11 +465,10 @@ function TestWebElement() { let element: webdriver.WebElement; element = new webdriver.WebElement(driver, 'elementId'); - element = new webdriver.WebElement(driver, promise); - let voidPromise: webdriver.promise.Promise; - let stringPromise: webdriver.promise.Promise; - let booleanPromise: webdriver.promise.Promise; + let voidPromise: Promise; + let stringPromise: Promise; + let booleanPromise: Promise; voidPromise = element.clear(); voidPromise = element.click(); @@ -783,89 +561,7 @@ function TestLoggingEntry() { let type: string = entry.type; } -declare let stringPromise: webdriver.promise.Promise; - -function TestPromiseModule() { - let cancellationError: webdriver.promise.CancellationError = new webdriver.promise.CancellationError(); - cancellationError = new webdriver.promise.CancellationError('message'); - let str: string = cancellationError.message; - str = cancellationError.name; - - let numberPromise: webdriver.promise.Promise; - let booleanPromise: webdriver.promise.Promise; - let voidPromise: webdriver.promise.Promise; - - webdriver.promise.all([stringPromise]).then((values: string[]) => {}); - - webdriver.promise.asap('abc', (value: any) => true); - webdriver.promise.asap('abc', (value: any) => {}, (err: any) => 'ABC'); - - stringPromise = webdriver.promise.checkedNodeCall((err: any, value: any) => 'abc'); - - webdriver.promise.consume(() => { - return 5; - }).then((value: number) => {}); - webdriver.promise.consume(() => { - return 5; - }, this).then((value: number) => {}); - webdriver.promise.consume((a: number, b: number, c: number) => 5, this, 1, 2, 3) - .then((value: number) => {}); - - let numbersPromise: webdriver.promise.Promise = webdriver.promise.filter([1, 2, 3], (element: number, type: any, index: number, arr: number[]) => { - return true; - }); - numbersPromise = webdriver.promise.filter([1, 2, 3], (element: number, type: any, index: number, arr: number[]) => { - return true; - }, this); - numbersPromise = webdriver.promise.filter(numbersPromise, (element: number, type: any, index: number, arr: number[]) => { - return true; - }); - numbersPromise = webdriver.promise.filter(numbersPromise, (element: number, type: any, index: number, arr: number[]) => { - return true; - }, this); - - numbersPromise = webdriver.promise.map([1, 2, 3], (el: number, type: any, index: number, arr: number[]) => { - return true; - }); - numbersPromise = webdriver.promise.map([1, 2, 3], (el: number, type: any, index: number, arr: number[]) => { - return true; - }, this); - numbersPromise = webdriver.promise.map(numbersPromise, (el: number, type: any, index: number, arr: number[]) => { - return true; - }); - numbersPromise = webdriver.promise.map(numbersPromise, (el: number, type: any, index: number, arr: number[]) => { - return true; - }, this); - - let flow: webdriver.promise.ControlFlow = webdriver.promise.controlFlow(); - - stringPromise = webdriver.promise.createFlow((newFlow: webdriver.promise.ControlFlow) => 'ABC'); - - let deferred: webdriver.promise.Deferred; - deferred = webdriver.promise.defer(); - deferred = webdriver.promise.defer(); - - stringPromise = deferred.promise; - - deferred.fulfill('ABC'); - deferred.reject('error'); - - voidPromise = webdriver.promise.delayed(123); - - voidPromise = webdriver.promise.fulfilled(); - stringPromise = webdriver.promise.fulfilled('abc'); - - stringPromise = webdriver.promise.fullyResolved('abc'); - - let bool: boolean = webdriver.promise.isGenerator(() => {}); - let isPromise: boolean = webdriver.promise.isPromise('ABC'); - - stringPromise = webdriver.promise.rejected('{a: 123}'); - - webdriver.promise.setDefaultFlow(new webdriver.promise.ControlFlow()); - - numberPromise = webdriver.promise.when('abc', (value: any) => 123, (err: Error) => 123); -} +declare let stringPromise: Promise; function TestUntilModule() { let driver: webdriver.WebDriver = new webdriver.Builder(). @@ -900,92 +596,3 @@ function TestUntilModule() { conditionWebElement = webdriver.until.elementTextMatches(el, /text/); conditionWebElements = webdriver.until.elementsLocated(webdriver.By.className('class')); } - -function TestControlFlow() { - let flow: webdriver.promise.ControlFlow; - flow = new webdriver.promise.ControlFlow(); - - let emitter: webdriver.EventEmitter = flow; - - let eventType: string; - - eventType = webdriver.promise.ControlFlow.EventType.IDLE; - eventType = webdriver.promise.ControlFlow.EventType.RESET; - eventType = webdriver.promise.ControlFlow.EventType.SCHEDULE_TASK; - eventType = webdriver.promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION; - - let stringPromise: webdriver.promise.Promise; - stringPromise = flow.execute(() => 'value'); - stringPromise = flow.execute(() => stringPromise); - stringPromise = flow.execute(() => stringPromise, 'Description'); - - let schedule: string; - schedule = flow.toString(); - schedule = flow.getSchedule(); - schedule = flow.getSchedule(true); - - flow.reset(); - - let voidPromise: webdriver.promise.Promise = flow.timeout(123); - voidPromise = flow.timeout(123, 'Description'); - - stringPromise = flow.wait(stringPromise); - - voidPromise = flow.wait(() => true); - voidPromise = flow.wait(() => true, 123); - voidPromise = flow.wait(() => stringPromise, 123, 'Timeout Message'); -} - -function TestDeferred() { - let deferred: webdriver.promise.Deferred; - - deferred = new webdriver.promise.Deferred(); - deferred = new webdriver.promise.Deferred(new webdriver.promise.ControlFlow()); - - let promise: webdriver.promise.Promise = deferred.promise; - - deferred.errback(new Error('Error')); - deferred.errback('Error'); - deferred.fulfill('abc'); - deferred.reject(new Error('Error')); - deferred.reject('Error'); - deferred.removeAll(); -} - -declare const controlFlow: webdriver.promise.ControlFlow; - -function TestPromiseClass() { - let promise: webdriver.promise.Promise; - promise = new webdriver.promise.Promise((resolve, reject) => { - resolve(""); - resolve(Promise.resolve("")); - reject(new Error()); - }, controlFlow); - - promise = promise.then(); - promise = promise.then((a: string) => 'cde'); - // tslint:disable-next-line void-return (need `--strictNullChecks` to change `void` to `undefined`) - const promiseOrVoid: webdriver.promise.Promise = promise.then((a: string) => 'cde', (e: any) => {}); - const promiseOrNumber: webdriver.promise.Promise = promise.then((a: string) => 'cde', (e: any) => 123); -} - -function TestThenableClass() { - // TODO: this doesn't test the Thenable class, it uses a Promise! - let thenable: webdriver.promise.Promise = new webdriver.promise.Promise((resolve, reject) => { - resolve('a'); - }); - - thenable = thenable.then((a: string) => 'cde'); - // tslint:disable-next-line void-return (need `--strictNullChecks` to change `void` to `undefined`) - const thenableOrVoid: webdriver.promise.Promise = thenable.then((a: string) => 'cde', (e: any) => {}); - const thenableOrNumber: webdriver.promise.Promise = thenable.then((a: string) => 'cde', (e: any) => 123); -} - -async function TestAsyncAwaitable() { - let thenable: webdriver.promise.Promise = new webdriver.promise.Promise((resolve, reject) => resolve('foo')); - let str: string = await thenable; -} - -function TestPromiseManagerFlag() { - webdriver.promise.USE_PROMISE_MANAGER = false; -} diff --git a/types/selenium-webdriver/tsconfig.json b/types/selenium-webdriver/tsconfig.json index 0b343058de..5c7bb8c4a9 100644 --- a/types/selenium-webdriver/tsconfig.json +++ b/types/selenium-webdriver/tsconfig.json @@ -24,14 +24,11 @@ "firefox.d.ts", "http.d.ts", "ie.d.ts", - "opera.d.ts", "remote.d.ts", "safari.d.ts", - "testing.d.ts", "test/index.ts", "test/chrome.ts", "test/firefox.ts", - "test/remote.ts", - "test/testing.ts" + "test/remote.ts" ] -} \ No newline at end of file +} diff --git a/types/selenium-webdriver/v3/chrome.d.ts b/types/selenium-webdriver/v3/chrome.d.ts new file mode 100644 index 0000000000..a5dbd2fd1f --- /dev/null +++ b/types/selenium-webdriver/v3/chrome.d.ts @@ -0,0 +1,362 @@ +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/types/selenium-webdriver/v3/edge.d.ts b/types/selenium-webdriver/v3/edge.d.ts new file mode 100644 index 0000000000..90b45fc92d --- /dev/null +++ b/types/selenium-webdriver/v3/edge.d.ts @@ -0,0 +1,92 @@ +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/types/selenium-webdriver/v3/firefox.d.ts b/types/selenium-webdriver/v3/firefox.d.ts new file mode 100644 index 0000000000..fcb8e74520 --- /dev/null +++ b/types/selenium-webdriver/v3/firefox.d.ts @@ -0,0 +1,335 @@ +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 { + /** + * Specify additional command line arguments that should be used when starting + * the Firefox browser. + * + * @param {...(string|!Array)} args The arguments to include. + * @return {!Options} A self reference. + */ + addArguments(...args: string[]): Options; + + /** + * Sets the browser to be in headless mode. + * + * @return {!Options} A self reference. + */ + headless(): Options; + + /** + * Sets the initial window size when running in + * {@linkplain #headless headless} mode. + * + * @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; + + /** + * Add extensions that should be installed when starting Firefox. + * + * @param {...string} paths The paths to the extension XPI files to install. + * @return {!Options} A self reference. + */ + addExtensions(...paths: string[]): Options; + + /** + * @param {string} key the preference key. + * @param {(string|number|boolean)} value the preference value. + * @return {!Options} A self reference. + * @throws {TypeError} if either the key or value has an invalid type. + */ + setPreference(key: string, value: string | number | boolean): 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/types/selenium-webdriver/v3/http.d.ts b/types/selenium-webdriver/v3/http.d.ts new file mode 100644 index 0000000000..ac24c6f6d4 --- /dev/null +++ b/types/selenium-webdriver/v3/http.d.ts @@ -0,0 +1,161 @@ +import * as webdriver from './index'; + +/** + * Converts a headers map to a HTTP header block string. + * @param {!Map} headers The map to convert. + * @return {string} The headers as a string. + */ +export function headersToString(headers: any): string; + +/** + * Represents a HTTP request message. This class is a 'partial' request and only + * defines the path on the server to send a request to. It is each client's + * responsibility to build the full URL for the final request. + * @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); + + headers: Map; + method: string; + path: string; + data: Object; + + /** @override */ + toString(): string; +} + +/** + * Represents a HTTP response message. + * @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); + + status: number; + body: string; + headers: Map; + + /** @override */ + toString(): string; +} + +export function post(path: string): any; +export function del(path: string): any; +export function get(path: string): any; +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); + + /** + * 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 single HTTP request. + * @param {!Object} options The request options. + * @param {function(!HttpResponse)} onOk The function to call if the + * request succeeds. + * @param {function(!Error)} onError The function to call if the request fails. + * @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; + +/** + * A command executor that communicates with the server using HTTP + JSON. + * + * By default, each instance of this class will use the legacy wire protocol + * from [Selenium project][json]. The executor will automatically switch to the + * [W3C wire protocol][w3c] if the remote end returns a compliant response to + * a new session command. + * + * [json]: https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol + * [w3c]: https://w3c.github.io/webdriver/webdriver-spec.html + * + * @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); + + /** + * 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; +} + +/** + * @param {string} str . + * @return {?} . + */ +export function tryParse(str: string): any; + +/** + * Callback used to parse {@link HttpResponse} objects from a + * {@link HttpClient}. + * @param {!HttpResponse} httpResponse The HTTP response to parse. + * @param {boolean} w3c Whether the response should be processed using the + * W3C wire protocol. + * @return {{value: ?}} The parsed response. + * @throws {WebDriverError} If the HTTP response is an error. + */ +export function parseHttpResponse(httpResponse: Response, w3c: boolean): any; + +/** + * Builds a fully qualified path using the given set of command parameters. Each + * path segment prefixed with ':' will be replaced by the value of the + * corresponding parameter. All parameters spliced into the path will be + * removed from the parameter map. + * @param {string} path The original resource path. + * @param {!Object<*>} parameters The parameters object to splice into the path. + * @return {string} The modified path. + */ +export function buildPath(path: string, parameters: Object): string; diff --git a/types/selenium-webdriver/v3/ie.d.ts b/types/selenium-webdriver/v3/ie.d.ts new file mode 100644 index 0000000000..bf3932450e --- /dev/null +++ b/types/selenium-webdriver/v3/ie.d.ts @@ -0,0 +1,208 @@ +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/types/selenium-webdriver/v3/index.d.ts b/types/selenium-webdriver/v3/index.d.ts new file mode 100644 index 0000000000..57a32a56b9 --- /dev/null +++ b/types/selenium-webdriver/v3/index.d.ts @@ -0,0 +1,4825 @@ +// Type definitions for Selenium WebDriverJS 3.0 +// Project: https://github.com/SeleniumHQ/selenium/tree/master/javascript/node/selenium-webdriver, https://github.com/seleniumhq/selenium +// Definitions by: Bill Armstrong , +// Yuki Kokubun , +// Craig Nishina , +// Simon Gellis , +// Ben Dixon , +// Ziyu +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.3 + +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 * as safari from './safari'; + +export namespace error { + class IError extends Error { + constructor(opt_error?: string); + } + + /** + * The base WebDriver error type. This error type is only used directly when a + * 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); + } + + /** + * 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); + } + + /** + * An element command could not be completed because the element is not visible + * on the page. + */ + class ElementNotVisibleError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + } + + /** + * An illegal attempt was made to set a cookie under a different domain than + * the current page. + */ + class InvalidCookieDomainError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + } + + /** + * 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. + */ + class InvalidElementStateError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } + + /** + * Argument was an invalid selector. + */ + class InvalidSelectorError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + } + + /** + * 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); + } + + /** + * 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); + } + + /** + * 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); + } + + /** + * An element could not be located on the page using the given search + * parameters. + */ + class NoSuchElementError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } + + /** + * A request to switch to a frame could not be satisfied because the frame + * could not be found. + */ + class NoSuchFrameError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } + + /** + * A request to switch to a window could not be satisfied because the window + * could not be found. + */ + class NoSuchWindowError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + } + + /** + * A new session could not be created. + */ + class SessionNotCreatedError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } + + /** + * An element command failed because the referenced element is no longer + * attached to the DOM. + */ + class StaleElementReferenceError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + } + + /** + * 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); + } + + /** + * A screen capture operation was not possible. + */ + class UnableToCaptureScreenError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: 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); + + /** + * @return {(string|undefined)} The text displayed with the unhandled alert, + * if available. + */ + getAlertText(): string; + } + + /** + * 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); + } + + /** + * The requested command matched a known URL but did not match an method for + * that URL. + */ + class UnknownMethodError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } + + /** + * Reports an unsupport operation. + */ + class UnsupportedOperationError extends WebDriverError { + /** @param {string=} opt_error the error message, if any. */ + constructor(opt_error?: string); + } +} + +export namespace logging { + /** + * A hash describing log preferences. + * @typedef {Object.} + */ + class Preferences { + setLevel(type: string, level: Level | string | number): void; + toJSON(): { [key: string]: string }; + } + + interface IType { + /** Logs originating from the browser. */ + BROWSER: string; + /** Logs from a WebDriver client. */ + CLIENT: string; + /** Logs from a WebDriver implementation. */ + DRIVER: string; + /** Logs related to performance. */ + PERFORMANCE: string; + /** Logs from the remote server. */ + SERVER: string; + } + + /** + * Common log types. + * @enum {string} + */ + const Type: IType; + + /** + * Defines a message level that may be used to control logging output. + * + * @final + */ + class Level { + name_: string; + value_: number; + /** + * @param {string} name the level's name. + * @param {number} level the level's numeric value. + */ + constructor(name: string, level: number); + + /** @override */ + toString(): string; + + /** This logger's name. */ + name: string; + + /** The numeric log level. */ + value: number; + + /** + * Indicates no log messages should be recorded. + * @const + */ + static OFF: Level; + /** + * Log messages with a level of `1000` or higher. + * @const + */ + static SEVERE: Level; + /** + * Log messages with a level of `900` or higher. + * @const + */ + static WARNING: Level; + /** + * Log messages with a level of `800` or higher. + * @const + */ + static INFO: Level; + /** + * Log messages with a level of `700` or higher. + * @const + */ + static DEBUG: Level; + /** + * Log messages with a level of `500` or higher. + * @const + */ + static FINE: Level; + /** + * Log messages with a level of `400` or higher. + * @const + */ + static FINER: Level; + /** + * Log messages with a level of `300` or higher. + * @const + */ + static FINEST: Level; + /** + * Indicates all log messages should be recorded. + * @const + */ + static ALL: Level; + } + + /** + * Converts a level name or value to a {@link logging.Level} value. + * If the name/value is not recognized, {@link logging.Level.ALL} + * will be returned. + * @param {(number|string)} nameOrValue The log level name, or value, to + * convert . + * @return {!logging.Level} The converted level. + */ + function getLevel(nameOrValue: string | number): Level; + + interface IEntryJSON { + level: string; + message: string; + timestamp: number; + type: string; + } + + /** + * A single log entry. + */ + class Entry { + /** + * @param {(!logging.Level|string)} level The entry level. + * @param {string} message The log message. + * @param {number=} opt_timestamp The time this entry was generated, in + * milliseconds since 0:00:00, January 1, 1970 UTC. If omitted, the + * current time will be used. + * @param {string=} opt_type The log type, if known. + * @constructor + */ + constructor(level: Level | string | number, message: string, opt_timestamp?: number, opt_type?: string | IType); + + /** @type {!logging.Level} */ + level: Level; + + /** @type {string} */ + message: string; + + /** @type {number} */ + timestamp: number; + + /** @type {string} */ + type: string; + + /** + * @return {{level: string, message: string, timestamp: number, + * type: string}} The JSON representation of this entry. + */ + toJSON(): IEntryJSON; + } + + /** + * 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'. + * + * Each logger may be assigned a {@linkplain #setLevel log level}, which + * controls which level of messages will be reported to the + * {@linkplain #addHandler handlers} attached to this instance. If a log level + * is not explicitly set on a logger, it will inherit its parent. + * + * This class should never be directly instantiated. Instead, users should + * obtain logger references using the {@linkplain ./logging.getLogger() + * getLogger()} function. + * + * @final + */ + class Logger { + /** + * @param {string} name the name of this logger. + * @param {Level=} opt_level the initial level for this logger. + */ + constructor(name: string, opt_level?: Level); + + /** @private {string} */ + name_: string; + /** @private {Level} */ + level_: Level; + /** @private {Logger} */ + parent_: Logger; + /** @private {Set} */ + handlers_: any; + + /** @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. + */ + setLevel(level: Level): void; + + /** @return {Level} the log level for this logger. */ + getLevel(): Level; + + /** + * @return {!Level} the effective level for this logger. + */ + getEffectiveLevel(): Level; + + /** + * @param {!Level} level the level to check. + * @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. + * + * @param {function(!Entry)} handler the handler to add. + */ + addHandler(handler: any): void; + + /** + * Removes a handler from this logger. + * + * @param {function(!Entry)} handler the handler to remove. + * @return {boolean} whether a handler was successfully removed. + */ + removeHandler(handler: any): void; + + /** + * Logs a message at the given level. The message may be defined as a string + * or as a function that will return the message. If a function is provided, + * it will only be invoked if this logger's + * {@linkplain #getEffectiveLevel() effective log level} includes the given + * `level`. + * + * @param {!Level} level the level at which to log the message. + * @param {(string|function(): string)} loggable the message to log, or a + * function that will return the message. + */ + 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + } + + /** + * Maintains a collection of loggers. + * + * @final + */ + class LogManager { + /** + * Retrieves a named logger, creating it in the process. This function will + * implicitly create the requested logger, and any of its parents, if they + * do not yet exist. + * + * @param {string} name the logger's name. + * @return {!Logger} the requested logger. + */ + getLogger(name?: string): Logger; + + /** + * Creates a new logger. + * + * @param {string} name the logger's name. + * @param {!Logger} parent the logger's parent. + * @return {!Logger} the new logger. + * @private + */ + createLogger_(name: string, parent: Logger): Logger; + } + + /** + * Retrieves a named logger, creating it in the process. This function will + * implicitly create the requested logger, and any of its parents, if they + * do not yet exist. + * + * @param {string} name the logger's name. + * @return {!Logger} the requested logger. + */ + function getLogger(name?: string): Logger; + + /** + * Adds the console handler to the given logger. The console handler will log + * all messages using the JavaScript Console API. + * + * @param {Logger=} opt_logger The logger to add the handler to; defaults + * to the root logger. + */ + function addConsoleHandler(opt_logger?: Logger): void; + + /** + * Removes the console log handler from the given logger. + * + * @param {Logger=} opt_logger The logger to remove the handler from; defaults + * to the root logger. + * @see exports.addConsoleHandler + */ + function removeConsoleHandler(opt_logger?: Logger): void; +} + +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; + + /** + * 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. + */ +export class Condition { + /** + * @param {string} message A descriptive error message. Should complete the + * sentence 'Waiting [...]' + * @param {function(!WebDriver): OUT} fn The condition function to + * evaluate on each iteration of the wait loop. + * @constructor + */ + constructor(message: string, fn: (webdriver: WebDriver) => any); + + /** @return {string} A description of this condition. */ + description(): string; + + /** @type {function(!WebDriver): OUT} */ + fn(webdriver: WebDriver): any; +} + +/** + * Defines a condition that will result in a {@link WebElement}. + * + * @extends {Condition)>} + */ +export class WebElementCondition extends Condition { + // add an unused private member so the compiler treats this + // class distinct from other Conditions + 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 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; + + /** + * 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; + + // endregion +} + +/** + * Class for defining sequences of user touch interactions. Each sequence + * will not be executed until {@link #perform} is called. + * + * Example: + * + * new TouchSequence(driver). + * tapAndHold({x: 0, y: 0}). + * move({x: 3, y: 4}). + * release({x: 10, y: 10}). + * perform(); + */ +export class TouchSequence { + /* + * @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 + * this sequence has completed. + */ + perform(): promise.Promise; + + /** + * Taps an element. + * + * @param {!WebElement} elem The element to tap. + * @return {!TouchSequence} A self reference. + */ + tap(elem: WebElement): TouchSequence; + + /** + * Double taps an element. + * + * @param {!WebElement} elem The element to double tap. + * @return {!TouchSequence} A self reference. + */ + doubleTap(elem: WebElement): TouchSequence; + + /** + * Long press on an element. + * + * @param {!WebElement} elem The element to long press. + * @return {!TouchSequence} A self reference. + */ + longPress(elem: WebElement): TouchSequence; + + /** + * Touch down at the given location. + * + * @param {{ x: number, y: number }} location The location to touch down at. + * @return {!TouchSequence} A self reference. + */ + tapAndHold(location: ILocation): TouchSequence; + + /** + * Move a held {@linkplain #tapAndHold touch} to the specified location. + * + * @param {{x: number, y: number}} location The location to move to. + * @return {!TouchSequence} A self reference. + */ + move(location: ILocation): TouchSequence; + + /** + * Release a held {@linkplain #tapAndHold touch} at the specified location. + * + * @param {{x: number, y: number}} location The location to release at. + * @return {!TouchSequence} A self reference. + */ + release(location: ILocation): TouchSequence; + + /** + * Scrolls the touch screen by the given offset. + * + * @param {{x: number, y: number}} offset The offset to scroll to. + * @return {!TouchSequence} A self reference. + */ + scroll(offset: IOffset): TouchSequence; + + /** + * Scrolls the touch screen, starting on `elem` and moving by the specified + * offset. + * + * @param {!WebElement} elem The element where scroll starts. + * @param {{x: number, y: number}} offset The offset to scroll to. + * @return {!TouchSequence} A self reference. + */ + scrollFromElement(elem: WebElement, offset: IOffset): 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. + * @return {!TouchSequence} A self reference. + */ + flick(speed: ISpeed): TouchSequence; + + /** + * Flick starting at elem and moving by x and y at specified speed. + * + * @param {!WebElement} elem The element where flick starts. + * @param {{x: number, y: number}} offset The offset to flick to. + * @param {number} speed The speed to flick at in pixels per second. + * @return {!TouchSequence} A self reference. + */ + flickElement(elem: WebElement, offset: IOffset, speed: number): TouchSequence; +} + +export interface IOffset { + x: number; + y: number; +} + +export interface ISpeed { + xspeed: number; + yspeed: number; +} + +/** + * Represents a modal dialog such as {@code alert}, {@code confirm}, or + * {@code prompt}. Provides functions to retrieve the message displayed with + * the alert, accept or dismiss the alert, and set the response text (in the + * case of {@code prompt}). + */ +export class Alert { + /** + * @param {!WebDriver} driver The driver controlling the browser this alert + * is attached to. + * @param {string} text The message text displayed with this alert. + */ + constructor(driver: WebDriver, text: string); + + // region Methods + + /** + * 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 + * text displayed with this alert. + */ + getText(): promise.Promise; + + /** + * Sets the username and password in an alert prompting for credentials (such + * as a Basic HTTP Auth prompt). This method will implicitly + * {@linkplain #accept() submit} the dialog. + * + * @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 + * command has completed. + */ + authenticateAs(username: string, password: string): promise.Promise; + + /** + * Accepts this alert. + * @return {!promise.Promise} A promise that will be resolved when + * this command has completed. + */ + accept(): promise.Promise; + + /** + * Dismisses this alert. + * @return {!promise.Promise} A promise that will be resolved when + * this command has completed. + */ + dismiss(): promise.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 + * this command has completed. + */ + sendKeys(text: string): promise.Promise; + + // endregion +} + +/** + * AlertPromise is a promise that will be fulfilled with an Alert. This promise + * serves as a forward proxy on an Alert, allowing calls to be scheduled + * directly on this instance before the underlying Alert has been fulfilled. In + * other words, the following two statements are equivalent: + * + * driver.switchTo().alert().dismiss(); + * driver.switchTo().alert().then(function(alert) { + * return alert.dismiss(); + * }); + * + * @implements {promise.Thenable.} + * @final + */ +export interface AlertPromise extends promise.IThenable {} +export class AlertPromise extends Alert { + /** + * @param {!WebDriver} driver The driver controlling the browser this + * alert is attached to. + * @param {!promise.Thenable} alert A thenable + * that will be fulfilled with the promised alert. + */ + constructor(driver: WebDriver, alert: promise.Promise); +} + +/** + * Recognized browser names. + * @enum {string} + */ +export interface IBrowser { + ANDROID: string; + CHROME: string; + EDGE: string; + FIREFOX: string; + IE: string; + INTERNET_EXPLORER: string; + IPAD: string; + IPHONE: string; + OPERA: string; + PHANTOM_JS: string; + SAFARI: string; + HTMLUNIT: string; +} + +export const Browser: IBrowser; + +export interface ProxyConfig { + proxyType: string; + proxyAutoconfigUrl?: string; + ftpProxy?: string; + httpProxy?: string; + sslProxy?: string; + noProxy?: string; + socksProxy?: string; + socksUsername?: string; + socksPassword?: string; +} + +/** + * Creates new {@link WebDriver WebDriver} instances. The environment + * variables listed below may be used to override a builder's configuration, + * allowing quick runtime changes. + * + * - {@code SELENIUM_BROWSER}: defines the target browser in the form + * {@code browser[:version][:platform]}. + * + * - {@code SELENIUM_REMOTE_URL}: defines the remote URL for all builder + * instances. This environment variable should be set to a fully qualified + * URL for a WebDriver server (e.g. http://localhost:4444/wd/hub). This + * option always takes precedence over {@code SELENIUM_SERVER_JAR}. + * + * - {@code SELENIUM_SERVER_JAR}: defines the path to the + * + * standalone Selenium server jar to use. The server will be started the + * first time a WebDriver instance and be killed when the process exits. + * + * Suppose you had mytest.js that created WebDriver with + * + * var driver = new Builder() + * .forBrowser('chrome') + * .build(); + * + * This test could be made to use Firefox on the local machine by running with + * `SELENIUM_BROWSER=firefox node mytest.js`. Rather than change the code to + * target Google Chrome on a remote machine, you can simply set the + * `SELENIUM_BROWSER` and `SELENIUM_REMOTE_URL` environment variables: + * + * SELENIUM_BROWSER=chrome:36:LINUX \ + * SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub \ + * node mytest.js + * + * You could also use a local copy of the standalone Selenium server: + * + * SELENIUM_BROWSER=chrome:36:LINUX \ + * SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar \ + * node mytest.js + */ +export class Builder { + // region Constructors + + /** + * @constructor + */ + constructor(); + + // endregion + + // region Methods + + /** + * Configures this builder to ignore any environment variable overrides and to + * only use the configuration specified through this instance's API. + * + * @return {!Builder} A self reference. + */ + disableEnvironmentOverrides(): Builder; + + /** + * Creates a new WebDriver client based on this builder's current + * configuration. + * + * This method will return a {@linkplain ThenableWebDriver} instance, allowing + * users to issue commands directly without calling `then()`. The returned + * thenable wraps a promise that will resolve to a concrete + * {@linkplain webdriver.WebDriver WebDriver} instance. The promise will be + * rejected if the remote end fails to create a new session. + * + * @return {!ThenableWebDriver} A new WebDriver instance. + * @throws {Error} If the current configuration is invalid. + */ + build(): ThenableWebDriver; + + /** + * Configures the target browser for clients created by this instance. + * 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]]}. + * + * @param {(string|Browser)} name The name of the target browser; + * common defaults are available on the {@link Browser} enum. + * @param {string=} opt_version A desired version; may be omitted if any + * version should be used. + * @param {string=} opt_platform The desired platform; may be omitted if any + * version may be used. + * @return {!Builder} A self reference. + */ + forBrowser(name: string, opt_version?: string, opt_platform?: string): Builder; + + /** + * Returns the base set of capabilities this instance is currently configured + * to use. + * @return {!Capabilities} The current capabilities for this builder. + */ + getCapabilities(): Capabilities; + + /** + * @return {string} The URL of the WebDriver server this instance is configured + * to use. + */ + getServerUrl(): string; + + /** + * @return {?string} The URL of the proxy server to use for the WebDriver's + * HTTP connections, or `null` if not set. + */ + getWebDriverProxy(): string; + + /** + * 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'. + * @return {!Builder} A self reference. + */ + setAlertBehavior(behavior: string): Builder; + + /** + * Sets Chrome-specific 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 {!chrome.Options} options The ChromeDriver options to use. + * @return {!Builder} A self reference. + */ + setChromeOptions(options: chrome.Options): Builder; + + /** + * @return {chrome.Options} the Chrome specific options currently configured + * for this builder. + */ + getChromeOptions(): chrome.Options; + + /** + * Sets the service builder to use for managing the chromedriver child process + * when creating new Chrome sessions. + * + * @param {chrome.ServiceBuilder} service the service to use. + * @return {!Builder} A self reference. + */ + setChromeService(service: chrome.ServiceBuilder): 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 + * given options will take precedence over those set through + * {@link #setProxy}. + * + * @param {!edge.Options} options The MicrosoftEdgeDriver options to use. + * @return {!Builder} A self reference. + */ + setEdgeOptions(options: edge.Options): Builder; + + /** + * Sets the {@link edge.ServiceBuilder} to use to manage the + * MicrosoftEdgeDriver child process when creating sessions locally. + * + * @param {edge.ServiceBuilder} service the service to use. + * @return {!Builder} a self reference. + */ + setEdgeService(service: edge.ServiceBuilder): 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 + * over those set through {@link #setLoggingPrefs} and {@link #setProxy}, + * respectively. + * + * @param {!firefox.Options} options The FirefoxDriver options to use. + * @return {!Builder} A self reference. + */ + setFirefoxOptions(options: firefox.Options): Builder; + + /** + * @return {firefox.Options} the Firefox specific options currently configured + * for this instance. + */ + getFirefoxOptions(): firefox.Options; + + /** + * Sets the {@link firefox.ServiceBuilder} to use to manage the geckodriver + * child process when creating Firefox sessions locally. + * + * @param {firefox.ServiceBuilder} service the service to use. + * @return {!Builder} a self reference. + */ + setFirefoxService(service: firefox.ServiceBuilder): Builder; + + /** + * Set Internet Explorer specific {@linkplain ie.Options options} for drivers + * created by this builder. Any proxy settings defined on the given options + * will take precedence over those set through {@link #setProxy}. + * + * @param {!ie.Options} options The IEDriver options to use. + * @return {!Builder} A self reference. + */ + setIeOptions(options: ie.Options): Builder; + + /** + * Sets the logging preferences for the created session. Preferences may be + * changed by repeated calls, or by calling {@link #withCapabilities}. + * @param {!(logging.Preferences|Object.)} prefs The + * 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; + + /** + * Sets the proxy configuration to use for WebDriver clients created by this + * builder. Any calls to {@link #withCapabilities} after this function will + * overwrite these settings. + * @param {!capabilities.ProxyConfig} config The configuration to use. + * @return {!Builder} A self reference. + */ + setProxy(config: ProxyConfig): Builder; + + /** + * Sets Safari specific {@linkplain safari.Options options} for drivers + * created by this builder. Any logging settings defined on the given options + * will take precedence over those set through {@link #setLoggingPrefs}. + * + * @param {!safari.Options} options The Safari options to use. + * @return {!Builder} A self reference. + */ + setSafariOptions(options: safari.Options): Builder; + + /** + * @return {safari.Options} the Safari specific options currently configured + * for this instance. + */ + getSafariOptions(): safari.Options; + + /** + * 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. + * + * @param {http.Agent} agent The agent to use for each request. + * @return {!Builder} A self reference. + */ + 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. + * + *

    As an alternative to this method, you may also set the + * {@code SELENIUM_REMOTE_URL} environment variable. + * + * @param {string} url The URL of a remote server to use. + * @return {!Builder} A self reference. + */ + usingServer(url: string): Builder; + + /** + * Sets the URL of the proxy to use for the WebDriver's HTTP connections. + * If this method is never called, the Builder will create a connection + * without a proxy. + * + * @param {string} proxy The URL of a proxy to use. + * @return {!Builder} A self reference. + */ + usingWebDriverProxy(proxy: string): Builder; + + /** + * Sets the desired capabilities when requesting a new session. This will + * overwrite any previously set capabilities. + * @param {!(Object|Capabilities)} capabilities The desired + * capabilities for a new session. + * @return {!Builder} A self reference. + */ + withCapabilities(capabilities: Object | 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} + */ +export interface ICapability { + /** + * Indicates whether a driver should accept all SSL certs by default. This + * capability only applies when requesting a new session. To query whether + * a driver can handle insecure SSL certs, see + * {@link Capability.SECURE_SSL}. + */ + ACCEPT_SSL_CERTS: string; + + /** + * The browser name. Common browser names are defined in the + * {@link Browser} enum. + */ + BROWSER_NAME: string; + + /** + * Defines how elements should be scrolled into the viewport for interaction. + * This capability will be set to zero (0) if elements are aligned with the + * top of the viewport, or one (1) if aligned with the bottom. The default + * behavior is to align with the top of the viewport. + */ + ELEMENT_SCROLL_BEHAVIOR: string; + + /** + * Whether the driver is capable of handling modal alerts (e.g. alert, + * confirm, prompt). To define how a driver should handle alerts, + * use {@link Capability.UNEXPECTED_ALERT_BEHAVIOR}. + */ + HANDLES_ALERTS: string; + + /** + * Key for the logging driver logging preferences. + */ + LOGGING_PREFS: string; + + /** + * Whether this session generates native events when simulating user input. + */ + NATIVE_EVENTS: string; + + /** + * Describes the platform the browser is running on. Will be one of + * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When requesting a + * session, ANY may be used to indicate no platform preference (this is + * semantically equivalent to omitting the platform capability). + */ + PLATFORM: string; + + /** + * Describes the proxy configuration to use for a new WebDriver session. + */ + PROXY: string; + + /** Whether the driver supports changing the brower's orientation. */ + ROTATABLE: string; + + /** + * Whether a driver is only capable of handling secure SSL certs. To request + * that a driver accept insecure SSL certs by default, use + * {@link Capability.ACCEPT_SSL_CERTS}. + */ + SECURE_SSL: string; + + /** Whether the driver supports manipulating the app cache. */ + SUPPORTS_APPLICATION_CACHE: string; + + /** Whether the driver supports locating elements with CSS selectors. */ + SUPPORTS_CSS_SELECTORS: string; + + /** Whether the browser supports JavaScript. */ + SUPPORTS_JAVASCRIPT: string; + + /** Whether the driver supports controlling the browser's location info. */ + SUPPORTS_LOCATION_CONTEXT: string; + + /** Whether the driver supports taking screenshots. */ + TAKES_SCREENSHOT: string; + + /** + * Defines how the driver should handle unexpected alerts. The value should + * be one of 'accept', 'dismiss', or 'ignore. + */ + UNEXPECTED_ALERT_BEHAVIOR: string; + + /** Defines the browser version. */ + VERSION: string; +} + +export const Capability: ICapability; + +export class Capabilities { + // region Constructors + + /** + * @param {(Capabilities|Object)=} opt_other Another set of + * capabilities to merge into this instance. + * @constructor + */ + constructor(opt_other?: Capabilities | Object); + + // endregion + + // region Methods + + /** @return {!Object} The JSON representation of this instance. */ + toJSON(): any; + + /** + * Merges another set of capabilities into this instance. Any duplicates in + * the provided set will override those already set on this instance. + * @param {!(Capabilities|Object)} other The capabilities to + * merge into this instance. + * @return {!Capabilities} A self reference. + */ + merge(other: Capabilities | Object): Capabilities; + + /** + * @param {string} key The capability to set. + * @param {*} value The capability value. Capability values must be JSON + * serializable. Pass {@code null} to unset the capability. + * @return {!Capabilities} A self reference. + */ + set(key: string, value: any): Capabilities; + + /** + * Sets the logging preferences. Preferences may be specified as a + * {@link logging.Preferences} instance, or a as a map of log-type to + * log-level. + * @param {!(logging.Preferences|Object.)} prefs The + * logging preferences. + * @return {!Capabilities} A self reference. + */ + setLoggingPrefs(prefs: logging.Preferences | Object): Capabilities; + + /** + * Sets the proxy configuration for this instance. + * @param {ProxyConfig} proxy The desired proxy configuration. + * @return {!Capabilities} A self reference. + */ + setProxy(proxy: ProxyConfig): Capabilities; + + /** + * Sets whether native events should be used. + * @param {boolean} enabled Whether to enable native events. + * @return {!Capabilities} A self reference. + */ + setEnableNativeEvents(enabled: boolean): 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. + * @return {!Capabilities} A self reference. + */ + setScrollBehavior(behavior: number): 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'. + * @return {!Capabilities} A self reference. + */ + setAlertBehavior(behavior: string): Capabilities; + + /** + * @param {string} key The capability to return. + * @return {*} The capability with the given key, or {@code null} if it has + * not been set. + */ + get(key: string): any; + + /** + * @param {string} key The capability to check. + * @return {boolean} Whether the specified capability is set. + */ + has(key: string): boolean; + + // endregion + + // region Static Methods + + /** + * @return {!Capabilities} A basic set of capabilities for Android. + */ + static android(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for Chrome. + */ + static chrome(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for Microsoft Edge. + */ + static edge(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for Firefox. + */ + static firefox(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for + * Internet Explorer. + */ + static ie(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for iPad. + */ + static ipad(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for iPhone. + */ + static iphone(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for Opera. + */ + static opera(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for + * PhantomJS. + */ + static phantomjs(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for Safari. + */ + static safari(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for HTMLUnit. + */ + static htmlunit(): Capabilities; + + /** + * @return {!Capabilities} A basic set of capabilities for HTMLUnit + * with enabled Javascript. + */ + static htmlunitwithjs(): 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}. + * @interface + */ +export class Executor { + /** + * Executes the given {@code command}. If there is an error executing the + * command, the provided callback will be invoked with the offending error. + * Otherwise, the callback will be invoked with a null Error and non-null + * response object. + * + * @param {!Command} command The command to execute. + * @return {!promise.Promise} A promise that will be fulfilled with + * the command result. + */ + execute(command: Command): promise.Promise +} + +/** + * Describes an event listener registered on an {@linkplain EventEmitter}. + */ +export class Listener { + /** + * @param {!Function} fn The acutal listener function. + * @param {(Object|undefined)} scope The object in whose scope to invoke the + * listener. + * @param {boolean} oneshot Whether this listener should only be used once. + */ + constructor(fn: Function, scope: Object, oneshot: boolean); +} + +/** + * Object that can emit events for others to listen for. This is used instead + * of Closure's event system because it is much more light weight. The API is + * based on Node's EventEmitters. + */ +export class EventEmitter { + // region Constructors + + /** + * @constructor + */ + constructor(); + + // endregion + + // region Methods + + /** + * Fires an event and calls all listeners. + * @param {string} type The type of event to emit. + * @param {...*} var_args Any arguments to pass to each listener. + */ + emit(type: string, ...var_args: any[]): void; + + /** + * Returns a mutable list of listeners for a specific type of event. + * @param {string} type The type of event to retrieve the listeners for. + * @return {!Set} The registered listeners for the given event + * type. + */ + listeners(type: string): any; + + /** + * Registers a listener. + * @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 + * the first event is fired. + * @return {!EventEmitter} A self reference. + * @private + */ + addListener(type: string, fn: Function, opt_scope?: any, opt_oneshot?: boolean): EventEmitter; + + /** + * Registers a one-time listener which will be called only the first time an + * 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. + * @return {!EventEmitter} A self reference. + */ + once(type: string, fn: any, opt_scope?: any): 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. + * @return {!EventEmitter} A self reference. + */ + on(type: string, fn: Function, opt_scope?: any): EventEmitter; + + /** + * Removes a previously registered event listener. + * @param {string} type The type of event to unregister. + * @param {!Function} listenerFn The handler function to remove. + * @return {!EventEmitter} A self reference. + */ + removeListener(type: string, listenerFn: Function): EventEmitter; + + /** + * Removes all listeners for a specific type of event. If no event is + * specified, all listeners across all types will be removed. + * @param {string=} opt_type The type of event to remove listeners from. + * @return {!EventEmitter} A self reference. + */ + removeAllListeners(opt_type?: string): EventEmitter; + + // endregion +} + +/** + * Interface for navigating back and forth in the browser history. + */ +export class Navigation { + // region Constructors + + /** + * Interface for navigating back and forth in the browser history. + * + * This class should never be instantiated directly. Insead, obtain an instance + * with + * + * navigate() + * + * @see WebDriver#navigate() + */ + constructor(driver: WebDriver); + + // endregion + + // region Methods + + /** + * 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 + * when the URL has been loaded. + */ + to(url: string): promise.Promise; + + /** + * Schedules a command to move backwards in the browser history. + * @return {!promise.Promise.} A promise that will be resolved + * when the navigation event has completed. + */ + back(): promise.Promise; + + /** + * Schedules a command to move forwards in the browser history. + * @return {!promise.Promise.} A promise that will be resolved + * when the navigation event has completed. + */ + forward(): promise.Promise; + + /** + * Schedules a command to refresh the current page. + * @return {!promise.Promise.} A promise that will be resolved + * when the navigation event has completed. + */ + refresh(): promise.Promise; + + // endregion +} + +export interface IWebDriverOptionsCookie { + /** + * The name of the cookie. + */ + name: string; + + /** + * The cookie value. + */ + value: string; + + /** + * The cookie path. Defaults to "/" when adding a cookie. + */ + path?: string; + + /** + * The domain the cookie is visible to. Defaults to the current browsing + * context's document's URL when adding a cookie. + */ + domain?: string; + + /** + * Whether the cookie is a secure cookie. Defaults to false when adding a new + * cookie. + */ + secure?: boolean; + + /** + * Whether the cookie is an HTTP only cookie. Defaults to false when adding a + * new cookie. + */ + httpOnly?: boolean; + + /** + * 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. + * + * 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; +} + +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; +} + +/** + * Provides methods for managing browser and driver state. + */ +export class Options { + // region Constructors + + /** + * @param {!WebDriver} driver The parent driver. + * @constructor + */ + constructor(driver: WebDriver); + + // endregion + + // region Methods + + /** + * Schedules a command to add a cookie. + * @param {IWebDriverOptionsCookie} spec Defines the cookie to add. + * @return {!promise.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; + + /** + * Schedules a command to delete all cookies visible to the current page. + * @return {!promise.Promise} A promise that will be resolved when all + * cookies have been deleted. + */ + deleteAllCookies(): promise.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 + * page. + * @param {string} name The name of the cookie to delete. + * @return {!promise.Promise} A promise that will be resolved when the + * cookie has been deleted. + */ + deleteCookie(name: string): promise.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 + * cookies visible to the current page. + * @see http://code.google.com/p/selenium/wiki/JsonWireProtocol#Cookie_JSON_Object + */ + getCookies(): promise.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. + * @param {string} name The name of the cookie to retrieve. + * @return {!promise.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; + + /** + * @return {!Logs} The interface for managing driver + * logs. + */ + logs(): Logs; + + /** + * @return {!Timeouts} The interface for managing driver + * timeouts. + */ + timeouts(): Timeouts; + + /** + * @return {!Window} The interface for managing the + * current window. + */ + window(): Window; + + // endregion +} + +/** + * An interface for managing timeout behavior for WebDriver instances. + */ +export class Timeouts { + // region Constructors + + /** + * @param {!WebDriver} driver The parent driver. + * @constructor + */ + constructor(driver: WebDriver); + + // endregion + + // region Methods + + /** + * Specifies the amount of time 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 + * with a {@code bot.ErrorCode.NO_SUCH_ELEMENT} error. When searching + * for multiple elements, the driver should poll the page until at least one + * element has been found or this timeout has expired. + *

    + * Setting the wait timeout to 0 (its default value), disables implicit + * waiting. + *

    + * 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 +} + +/** + * An interface for managing the current window. + */ +export class Window { + // region Constructors + + /** + * @param {!WebDriver} driver The parent driver. + * @constructor + */ + constructor(driver: WebDriver); + + // endregion + + // region Methods + + /** + * 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 + * window's position in the form of a {x:number, y:number} object literal. + */ + getPosition(): promise.Promise; + + /** + * Repositions the current window. + * @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 + * command has completed. + */ + setPosition(x: number, y: number): promise.Promise; + + /** + * Retrieves the window's current size. + * @return {!promise.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; + + /** + * 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 + * command has completed. + */ + setSize(width: number, height: number): promise.Promise; + + /** + * Maximizes the current window. + * @return {!promise.Promise} A promise that will be resolved when the + * command has completed. + */ + maximize(): promise.Promise; + + // endregion +} + +/** + * Interface for managing WebDriver log records. + */ +export class Logs { + // region Constructors + + /** + * @param {!WebDriver} driver The parent driver. + * @constructor + */ + constructor(driver: WebDriver); + + // endregion + + // region + + /** + * Fetches available log entries for the given type. + * + *

    Note that log buffers are reset after each call, meaning that + * available log entries correspond to those entries not yet returned for a + * given log type. In practice, this means that this call will return the + * available log entries since the last call, or from the start of the + * session. + * + * @param {!logging.Type} type The desired log type. + * @return {!promise.Promise.>} A + * promise that will resolve to a list of log entries for the specified + * type. + */ + get(type: string): promise.Promise; + + /** + * Retrieves the log types available to this driver. + * @return {!promise.Promise.>} A + * promise that will resolve to a list of available log types. + */ + getAvailableLogTypes(): promise.Promise; + + // endregion +} + +/** + * An interface for changing the focus of the driver to another frame or window. + */ +export class TargetLocator { + // region Constructors + + /** + * @param {!WebDriver} driver The parent driver. + * @constructor + */ + constructor(driver: WebDriver); + + // endregion + + // region Methods + + /** + * Schedules a command retrieve the {@code document.activeElement} element on + * the current document, or {@code document.body} if activeElement is not + * available. + * @return {!WebElement} The active element. + */ + 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 + * driver has changed focus to the default content. + */ + defaultContent(): promise.Promise; + + /** + * Schedules a command to switch the focus of all future commands to another + * frame on the page. The target frame may be specified as one of the + * following: + * + * - A number that specifies a (zero-based) index into [window.frames]( + * https://developer.mozilla.org/en-US/docs/Web/API/Window.frames). + * - A {@link WebElement} reference, which correspond to a `frame` or `iframe` + * DOM element. + * - The `null` value, to select the topmost frame on the page. Passing `null` + * is the same as calling {@link #defaultContent defaultContent()}. + * + * If the specified frame can not be found, the returned promise will be + * rejected with a {@linkplain error.NoSuchFrameError}. + * + * @param {(number|WebElement|null)} id The frame locator. + * @return {!promise.Promise} A promise that will be resolved + * when the driver has changed focus to the specified frame. + */ + frame(nameOrIndex: number | WebElement | null): promise.Promise; + + /** + * Schedules a command to switch the focus of all future commands to another + * window. Windows may be specified by their {@code window.name} attribute or + * by its handle (as returned by {@link WebDriver#getWindowHandles}). + * + * If the specified window cannot be found, the returned promise will be + * rejected with a {@linkplain error.NoSuchWindowError}. + * + * @param {string} nameOrHandle The name or window handle of the window to + * switch focus to. + * @return {!promise.Promise} A promise that will be resolved + * when the driver has changed focus to the specified window. + */ + window(nameOrHandle: string): promise.Promise; + + /** + * Schedules a command to change focus to the active modal dialog, such as + * those opened by `window.alert()`, `window.confirm()`, and + * `window.prompt()`. The returned promise will be rejected with a + * {@linkplain error.NoSuchAlertError} if there are no open alerts. + * + * @return {!AlertPromise} The open alert. + */ + alert(): AlertPromise; + + // endregion +} + +/** + * Used with {@link WebElement#sendKeys WebElement#sendKeys} on file + * input elements ({@code }) to detect when the entered key + * sequence defines the path to a file. + * + * By default, {@linkplain WebElement WebElement's} will enter all + * key sequences exactly as entered. You may set a + * {@linkplain WebDriver#setFileDetector file detector} on the parent + * WebDriver instance to define custom behavior for handling file elements. Of + * particular note is the {@link selenium-webdriver/remote.FileDetector}, which + * should be used when running against a remote + * [Selenium Server](http://docs.seleniumhq.org/download/). + */ +export class FileDetector { + /** @constructor */ + constructor(); + + /** + * Handles the file specified by the given path, preparing it for use with + * the current browser. If the path does not refer to a valid file, it will + * be returned unchanged, otherwisee a path suitable for use with the current + * browser will be returned. + * + * This default implementation is a no-op. Subtypes may override this + * function for custom tailored file handling. + * + * @param {!WebDriver} driver The driver for the current browser. + * @param {string} path The path to process. + * @return {!promise.Promise} A promise for the processed + * file path. + * @package + */ + handleFile(driver: WebDriver, path: string): promise.Promise; +} + +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 + * represents the result of that command. Callbacks may be registered on this + * object to manipulate the command result or catch an expected error. Any + * commands scheduled with a callback are considered sub-commands and will + * execute before the next command in the current frame. For example: + * + * var message = []; + * driver.call(message.push, message, 'a').then(function() { + * driver.call(message.push, message, 'b'); + * }); + * driver.call(message.push, message, 'c'); + * driver.call(function() { + * alert('message is abc? ' + (message.join('') == 'abc')); + * }); + * + */ +export class WebDriver { + // region Constructors + + /** + * @param {!(Session|promise.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); + + // 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. + * + * By default, the requested session `capabilities` are merely "desired" and + * the remote end will still create a new session even if it cannot satisfy + * all of the requested capabilities. You can query which capabilities a + * session actually has using the + * {@linkplain #getCapabilities() getCapabilities()} method on the returned + * WebDriver instance. + * + * To define _required capabilities_, provide the `capabilities` as an object + * literal with `required` and `desired` keys. The `desired` key may be + * omitted if all capabilities are required, and vice versa. If the server + * cannot create a session with all of the required capabilities, it will + * return an {@linkplain error.SessionNotCreatedError}. + * + * let required = new Capabilities().set('browserName', 'firefox'); + * let desired = new Capabilities().set('version', '45'); + * let driver = WebDriver.createSession(executor, {required, desired}); + * + * This function will always return a WebDriver instance. If there is an error + * creating the session, such as the aforementioned SessionNotCreatedError, + * the driver will have a rejected {@linkplain #getSession session} promise. + * It is recommended that this promise is left _unhandled_ so it will + * propagate through the {@linkplain promise.ControlFlow control flow} and + * cause subsequent commands to fail. + * + * let required = Capabilities.firefox(); + * let driver = WebDriver.createSession(executor, {required}); + * + * // If the createSession operation failed, then this command will also + * // also fail, propagating the creation failure. + * driver.get('http://www.google.com').catch(e => console.log(e)); + * + * @param {!command.Executor} executor The executor to create the new session + * with. + * @param {(!Capabilities| + * {desired: (Capabilities|undefined), + * required: (Capabilities|undefined)})} capabilities The desired + * capabilities for the new session. + * @param {promise.ControlFlow=} opt_flow The control flow all driver + * commands should execute under, including the initial session creation. + * Defaults to the {@link promise.controlFlow() currently active} + * control flow. + * @param {(function(new: WebDriver, + * !IThenable, + * !command.Executor, + * promise.ControlFlow=))=} opt_ctor + * A reference to the constructor of the specific type of WebDriver client + * to instantiate. Will create a vanilla {@linkplain WebDriver} instance + * if a constructor is not provided. + * @param {(function(this: void): ?)=} opt_onQuit A callback to invoke when + * the newly created session is terminated. This should be used to clean + * 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. + 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 + * with the command result. + * @template T + */ + schedule(command: Command, description: string): promise.Promise; + + /** + * Sets the {@linkplain input.FileDetector file detector} that should be + * used with this instance. + * @param {input.FileDetector} detector The detector to use or {@code null}. + */ + setFileDetector(detector: FileDetector): void; + + /** + * @return {!promise.Promise.} A promise for this + * client's session. + */ + getSession(): promise.Promise; + + /** + * @return {!promise.Promise.} A promise + * that will resolve with the this instance's capabilities. + */ + getCapabilities(): promise.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 + * 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; + + /** + * 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 + * 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. + * + * The script may refer to any variables accessible from the current window. + * Furthermore, the script will execute in the window's context, thus + * {@code document} may be used to refer to the current document. Any local + * variables will not be available once the script has finished executing, + * though global variables will persist. + * + * If the script has a return value (i.e. if the script contains a return + * statement), then the following steps will be taken for resolving this + * functions return value: + * + * - For a HTML element, the value will resolve to a + * {@link WebElement} + * - Null and undefined return values will resolve to null

    • + * - Booleans, numbers, and strings will resolve as is + * - Functions will resolve to their string representation + * - For arrays and objects, each member item will be converted according to + * the rules above + * + * @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 + * scripts return value. + * @template T + */ + executeScript(script: string | Function, ...var_args: any[]): promise.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. + * + * 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. + * + * 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: + * + * - For a HTML element, the value will resolve to a + * {@link WebElement} + * - Null and undefined return values will resolve to null + * - Booleans, numbers, and strings will resolve as is + * - Functions will resolve to their string representation + * - For arrays and objects, each member item will be converted according to + * the rules above + * + * __Example #1:__ Performing a sleep that is synchronized with the currently + * selected window: + * + * var start = new Date().getTime(); + * driver.executeAsyncScript( + * 'window.setTimeout(arguments[arguments.length - 1], 500);'). + * then(function() { + * console.log( + * 'Elapsed time: ' + (new Date().getTime() - start) + ' ms'); + * }); + * + * __Example #2:__ Synchronizing a test with an AJAX application: + * + * var button = driver.findElement(By.id('compose-button')); + * button.click(); + * driver.executeAsyncScript( + * 'var callback = arguments[arguments.length - 1];' + + * 'mailClient.getComposeWindowWidget().onload(callback);'); + * driver.switchTo().frame('composeWidget'); + * driver.findElement(By.id('to')).sendKeys('dog@example.com'); + * + * __Example #3:__ Injecting a XMLHttpRequest and waiting for the result. In + * this example, the inject script is specified with a function literal. When + * using this format, the function is converted to a string for injection, so it + * should not reference any symbols not defined in the scope of the page under + * test. + * + * driver.executeAsyncScript(function() { + * var callback = arguments[arguments.length - 1]; + * var xhr = new XMLHttpRequest(); + * xhr.open('GET', '/resource/data.json', true); + * xhr.onreadystatechange = function() { + * if (xhr.readyState == 4) { + * callback(xhr.responseText); + * } + * } + * xhr.send(''); + * }).then(function(str) { + * console.log(JSON.parse(str)['food']); + * }); + * + * @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 + * scripts return value. + * @template T + */ + executeAsyncScript(script: string | Function, ...var_args: any[]): promise.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}. + * + * 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 + * 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. + * + * Note, if the provided condition is a {@link WebElementCondition}, then + * 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. + * + * 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. + * + * *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: + * + * var started = startTestServer(); + * driver.wait(started, 5 * 1000, 'Server should start within 5 seconds'); + * driver.get(getServerUrl()); + * + * @param {!WebElementCondition} condition The condition to + * wait on, defined as a promise, condition object, or a function to + * evaluate as a condition. + * @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 {!WebElementPromise} 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: 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}. + * + * 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 + * 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. + * + * Note, if the provided condition is a {@link WebElementCondition}, then + * 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. + * + * 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. + * + * *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: + * + * var started = startTestServer(); + * driver.wait(started, 5 * 1000, 'Server should start within 5 seconds'); + * driver.get(getServerUrl()); + * + * @param {!(promise.Promise| + * Condition| + * function(!WebDriver): T)} condition The condition to + * wait on, defined as a promise, condition object, or a function to + * evaluate as a condition. + * @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 + * 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; + + /** + * 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 + * when the sleep has finished. + */ + sleep(ms: number): promise.Promise; + + /** + * Schedules a command to retrieve they current window handle. + * @return {!promise.Promise.} A promise that will be + * resolved with the current window handle. + */ + getWindowHandle(): promise.Promise; + + /** + * Schedules a command to retrieve the current list of available window handles. + * @return {!promise.Promise.>} A promise that will + * be resolved with an array of window handles. + */ + getAllWindowHandles(): promise.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 + * resolved with the current page source. + */ + getPageSource(): promise.Promise; + + /** + * Schedules a command to close the current window. + * @return {!promise.Promise.} A promise that will be resolved + * when this command has completed. + */ + close(): promise.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 + * when the document has finished loading. + */ + get(url: string): promise.Promise; + + /** + * Schedules a command to retrieve the URL of the current page. + * @return {!promise.Promise.} A promise that will be + * resolved with the current URL. + */ + getCurrentUrl(): promise.Promise; + + /** + * Schedules a command to retrieve the current page's title. + * @return {!promise.Promise.} A promise that will be + * resolved with the current page's title. + */ + getTitle(): promise.Promise; + + /** + * Schedule a command to find an element on the page. If the element cannot be + * found, a {@link bot.ErrorCode.NO_SUCH_ELEMENT} result will be returned + * by the driver. Unlike other commands, this error cannot be suppressed. In + * other words, scheduling a command to find an element doubles as an assert + * that the element is present on the page. To test whether an element is + * present on the page, use {@link #findElements}. + * + * The search criteria for an element may be defined using one of the + * factories in the {@link By} namespace, or as a short-hand + * {@link By.Hash} object. For example, the following two statements + * are equivalent: + * + * var e1 = driver.findElement(By.id('foo')); + * var e2 = driver.findElement({id:'foo'}); + * + * You may also provide a custom locator function, which takes as input this + * instance and returns a {@link WebElement}, or a promise that will resolve + * to a WebElement. If the returned promise resolves to an array of + * WebElements, WebDriver will use the first element. For example, to find the + * first visible link on a page, you could write: + * + * var link = driver.findElement(firstVisibleLink); + * + * function firstVisibleLink(driver) { + * var links = driver.findElements(By.tagName('a')); + * return promise.filter(links, function(link) { + * return link.isDisplayed(); + * }); + * } + * + * @param {!(by.By|Function)} locator The locator to use. + * @return {!WebElementPromise} A WebElement that can be used to issue + * commands against the located element. If the element is not found, the + * element will be invalidated and all scheduled commands aborted. + */ + findElement(locator: Locator): WebElementPromise; + + /** + * Schedule a command to search for multiple elements on the page. + * + * @param {!(by.By|Function)} locator The locator to use. + * @return {!promise.Promise.>} A + * promise that will resolve to an array of WebElements. + */ + findElements(locator: Locator): promise.Promise; + + /** + * Schedule a command to take a screenshot. The driver makes a best effort to + * return a screenshot of the following, in order of preference: + * + * 1. Entire page + * 2. Current window + * 3. Visible portion of the current frame + * 4. The entire display containing the browser + * + * @return {!promise.Promise} A promise that will be + * resolved to the screenshot as a base-64 encoded PNG. + */ + takeScreenshot(): promise.Promise; + + /** + * @return {!Options} The options interface for this + * instance. + */ + manage(): Options; + + /** + * @return {!Navigation} The navigation interface for this + * instance. + */ + navigate(): Navigation; + + /** + * @return {!TargetLocator} The target locator interface for + * this instance. + */ + switchTo(): TargetLocator; + + // endregion +} + +/** + * A thenable wrapper around a {@linkplain webdriver.IWebDriver IWebDriver} + * instance that allows commands to be issued directly instead of having to + * repeatedly call `then`: + * + * let driver = new Builder().build(); + * driver.then(d => d.get(url)); // You can do this... + * driver.get(url); // ...or this + * + * If the driver instance fails to resolve (e.g. the session cannot be created), + * every issued command will fail. + * + * @extends {webdriver.IWebDriver} + * @extends {promise.IThenable} + * @interface + */ +export interface ThenableWebDriver extends WebDriver, promise.IThenable { } + +export interface IWebElementId { + [ELEMENT: string]: string; +} + +/** + * Represents a DOM element. WebElements can be found by searching from the + * document root using a {@code WebDriver} instance, or by searching + * under another {@code WebElement}: + * 
    
+ *   driver.get('http://www.google.com');
+ *   var searchForm = driver.findElement(By.tagName('form'));
+ *   var searchBox = searchForm.findElement(By.name('q'));
+ *   searchBox.sendKeys('webdriver');
+ *
    + * + * The WebElement is implemented as a promise for compatibility with the promise + * API. It will always resolve itself when its internal state has been fully + * resolved and commands may be issued against the element. This can be used to + * catch errors when an element cannot be located on the page: + * 
    
+ *   driver.findElement(By.id('not-there')).then(function(element) {
+ *     alert('Found an element that was not expected to be there!');
+ *   }, function(error) {
+ *     alert('The element was not found, as expected');
+ *   });
+ *
    + */ +export interface IWebElement { + // region Methods + + /** + * Schedules a command to click on this element. + * @return {!promise.Promise} A promise that will be resolved when + * the click command has completed. + */ + click(): promise.Promise; + + /** + * Schedules a command to type a sequence on the DOM element represented by + * this instance. + * + * Modifier keys (SHIFT, CONTROL, ALT, META) are stateful; once a modifier is + * processed in the key sequence, 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). + * - The {@link input.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 + * simulate common keyboard shortcuts: + * + * element.sendKeys('text was', + * Key.CONTROL, 'a', Key.NULL, + * 'now text is'); + * // Alternatively: + * element.sendKeys('text was', + * Key.chord(Key.CONTROL, 'a'), + * 'now text is'); + * + * - The end of the key sequence is encountered. When there are no more keys + * 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 + * 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]')); + * element.sendKeys('/path/to/file.txt'); + * form.submit(); + * + * For uploads to function correctly, the entered path must reference a file + * on the _browser's_ machine, not the local machine running this script. When + * running against a remote Selenium server, a {@link input.FileDetector} + * may be used to transparently copy files to the remote machine before + * attempting to upload them in the browser. + * + * __Note:__ On browsers where native keyboard events are not supported + * (e.g. Firefox on OS X), key events will be synthesized. Special + * punctuation keys will be synthesized according to a standard QWERTY en-us + * keyboard layout. + * + * @param {...(number|string|!IThenable<(number|string)>)} var_args The + * 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 + * keys have been typed. + */ + sendKeys(...var_args: Array>): promise.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 + * element's tag name. + */ + getTagName(): promise.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. + * + * @param {string} cssStyleProperty The name of the CSS style property to look + * up. + * @return {!promise.Promise} A promise that will be resolved with the + * requested CSS value. + */ + getCssValue(cssStyleProperty: string): promise.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 + * + *

    Finally, the following commonly mis-capitalized attribute/property names + * are evaluated as expected: + *

      + *
    • 'class' + *
    • 'readonly' + *
    + * @param {string} attributeName The name of the attribute to query. + * @return {!promise.Promise} A promise that will be resolved with the + * attribute's value. + */ + getAttribute(attributeName: string): promise.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 + * element's visible text. + */ + getText(): promise.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 + * element's size as a {@code {width:number, height:number}} object. + */ + getSize(): promise.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 + * element's location as a {@code {x:number, y:number}} object. + */ + getLocation(): promise.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 + * whether this element is currently enabled. + */ + isEnabled(): promise.Promise; + + /** + * Schedules a command to query whether this element is selected. + * @return {!promise.Promise} A promise that will be resolved with + * whether this element is currently selected. + */ + isSelected(): promise.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 + * the form has been submitted. + */ + submit(): promise.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 + * the element has been cleared. + */ + clear(): promise.Promise; + + /** + * Schedules a command to test whether this element is currently displayed. + * @return {!promise.Promise} A promise that will be resolved with + * whether this element is currently visible on the page. + */ + isDisplayed(): promise.Promise; + + /** + * @return {!promise.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; + + // endregion +} + +export interface IWebElementFinders { + /** + * Schedule a command to find a descendant of this element. If the element + * cannot be found, a {@code bot.ErrorCode.NO_SUCH_ELEMENT} result will + * be returned by the driver. Unlike other commands, this error cannot be + * suppressed. In other words, scheduling a command to find an element doubles + * as an assert that the element is present on the page. To test whether an + * element is present on the page, use {@code #findElements}. + * + *

    The search criteria for an element may be defined using one of the + * factories in the {@link By} namespace, or as a short-hand + * {@link By.Hash} object. For example, the following two statements + * are equivalent: + * 

    +   * var e1 = element.findElement(By.id('foo'));
+   * var e2 = element.findElement({id:'foo'});
+   *
    + * + *

    You may also provide a custom locator function, which takes as input + * this WebDriver instance and returns a {@link WebElement}, or a + * promise that will resolve to a WebElement. For example, to find the first + * visible link on a page, you could write: + * 

    +   * var link = element.findElement(firstVisibleLink);
+   *
+   * function firstVisibleLink(element) {
+   *   var links = element.findElements(By.tagName('a'));
+   *   return promise.filter(links, function(link) {
+   *     return links.isDisplayed();
+   *   }).then(function(visibleLinks) {
+   *     return visibleLinks[0];
+   *   });
+   * }
+   *
    + * + * @param {!(Locator|By.Hash|Function)} locator The + * locator strategy to use when searching for the element. + * @return {!WebElement} A WebElement that can be used to issue + * commands against the located element. If the element is not found, the + * element will be invalidated and all scheduled commands aborted. + */ + findElement(locator: Locator): WebElementPromise; + + /** + * Schedules a command to find all of the descendants of this element that + * match the given search criteria. + * + * @param {!(Locator|By.Hash|Function)} locator The + * locator strategy to use when searching for the elements. + * @return {!promise.Promise.>} A + * promise that will resolve to an array of WebElements. + */ + findElements(locator: Locator): promise.Promise; +} + +/** + * Defines an object that can be asynchronously serialized to its WebDriver + * wire representation. + * + * @constructor + * @template T + */ +export interface Serializable { + /** + * Returns either this instance's serialized represention, if immediately + * available, or a promise for its serialized representation. This function is + * conceptually equivalent to objects that have a {@code toJSON()} property, + * except the serialize() result may be a promise or an object containing a + * promise (which are not directly JSON friendly). + * + * @return {!(T|IThenable.)} This instance's serialized wire format. + */ + serialize(): T | promise.IThenable; +} + +/** + * Represents a DOM element. WebElements can be found by searching from the + * document root using a {@link WebDriver} instance, or by searching + * under another WebElement: + * + * driver.get('http://www.google.com'); + * var searchForm = driver.findElement(By.tagName('form')); + * var searchBox = searchForm.findElement(By.name('q')); + * searchBox.sendKeys('webdriver'); + * + * The WebElement is implemented as a promise for compatibility with the promise + * API. It will always resolve itself when its internal state has been fully + * resolved and commands may be issued against the element. This can be used to + * catch errors when an element cannot be located on the page: + * + * driver.findElement(By.id('not-there')).then(function(element) { + * alert('Found an element that was not expected to be there!'); + * }, function(error) { + * alert('The element was not found, as expected'); + * }); + * + * @extends {Serializable.} + */ +export class WebElement implements Serializable { + /** + * @param {!WebDriver} driver the parent WebDriver instance for this element. + * @param {(!IThenable|string)} id The server-assigned opaque ID for + * the underlying DOM element. + */ + constructor(driver: WebDriver, id: promise.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; + + /** + * Extracts the encoded WebElement ID from the object. + * + * @param {?} obj The object to extract the ID from. + * @return {string} the extracted ID. + * @throws {TypeError} if the object is not a valid encoded ID. + */ + static extractId(obj: IWebElementId): string; + + /** + * @param {?} obj the object to test. + * @return {boolean} whether the object is a valid encoded WebElement ID. + */ + static isId(obj: IWebElementId): boolean; + + /** + * Compares two WebElements for equality. + * + * @param {!WebElement} a A WebElement. + * @param {!WebElement} b A WebElement. + * @return {!promise.Promise} A promise that will be + * resolved to whether the two WebElements are equal. + */ + static equals(a: WebElement, b: WebElement): promise.Promise; + + /** + * @return {!WebDriver} The parent driver for this instance. + */ + getDriver(): WebDriver; + + /** + * @return {!promise.Promise} A promise that resolves to + * the server-assigned opaque ID assigned to this element. + */ + getId(): promise.Promise; + + /** + * Schedule a command to find a descendant of this element. If the element + * cannot be found, a {@link bot.ErrorCode.NO_SUCH_ELEMENT} result will + * be returned by the driver. Unlike other commands, this error cannot be + * suppressed. In other words, scheduling a command to find an element doubles + * as an assert that the element is present on the page. To test whether an + * element is present on the page, use {@link #findElements}. + * + * The search criteria for an element may be defined using one of the + * factories in the {@link By} namespace, or as a short-hand + * {@link By.Hash} object. For example, the following two statements + * are equivalent: + * + * var e1 = element.findElement(By.id('foo')); + * var e2 = element.findElement({id:'foo'}); + * + * You may also provide a custom locator function, which takes as input + * this WebDriver instance and returns a {@link WebElement}, or a + * promise that will resolve to a WebElement. For example, to find the first + * visible link on a page, you could write: + * + * var link = element.findElement(firstVisibleLink); + * + * function firstVisibleLink(element) { + * var links = element.findElements(By.tagName('a')); + * return promise.filter(links, function(link) { + * return links.isDisplayed(); + * }).then(function(visibleLinks) { + * return visibleLinks[0]; + * }); + * } + * + * @param {!(by.By|Function)} locator The locator strategy to use when + * searching for the element. + * @return {!WebElementPromise} A WebElement that can be used to issue + * commands against the located element. If the element is not found, the + * element will be invalidated and all scheduled commands aborted. + */ + findElement(locator: Locator): WebElementPromise; + + /** + * Schedules a command to find all of the descendants of this element that + * match the given search criteria. + * + * @param {!(by.By|Function)} locator The locator strategy to use when + * searching for the element. + * @return {!promise.Promise>} A + * promise that will resolve to an array of WebElements. + */ + findElements(locator: Locator): promise.Promise; + + /** + * Schedules a command to click on this element. + * @return {!promise.Promise.} A promise that will be resolved + * when the click command has completed. + */ + click(): promise.Promise; + + /** + * 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). + * - 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 + * simulate common keyboard shortcuts: + * + * element.sendKeys('text was', + * Key.CONTROL, 'a', Key.NULL, + * 'now text is'); + * // Alternatively: + * element.sendKeys('text was', + * Key.chord(Key.CONTROL, 'a'), + * '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). + * + * 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 analgous 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]')); + * element.sendKeys('/path/to/file.txt'); + * form.submit(); + * + * For uploads to function correctly, the entered path must reference a file + * on the _browser's_ machine, not the local machine running this script. When + * running against a remote Selenium server, a {@link FileDetector} + * may be used to transparently copy files to the remote machine before + * attempting to upload them in the browser. + * + * __Note:__ On browsers where native keyboard events are not supported + * (e.g. Firefox on OS X), key events will be synthesized. Special + * punctionation keys will be synthesized according to a standard QWERTY en-us + * keyboard layout. + * + * @param {...(string|!promise.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 + * when all keys have been typed. + */ + sendKeys(...var_args: Array>): promise.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 element's tag name. + */ + getTagName(): promise.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. + * + * @param {string} cssStyleProperty The name of the CSS style property to look + * up. + * @return {!promise.Promise} A promise that will be + * resolved with the requested CSS value. + */ + getCssValue(cssStyleProperty: string): promise.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 + * 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: + * + * 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: + * + * - 'class' + * - 'readonly' + * + * @param {string} attributeName The name of the attribute to query. + * @return {!promise.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; + + /** + * 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 element's visible text. + */ + getText(): promise.Promise; + + /** + * Schedules a command to compute the size of this element's bounding box, in + * pixels. + * @return {!promise.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; + + /** + * Schedules a command to compute the location of this element in page space. + * @return {!promise.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; + + /** + * 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 whether this element is currently enabled. + */ + isEnabled(): promise.Promise; + + /** + * Schedules a command to query whether this element is selected. + * @return {!promise.Promise.} A promise that will be + * resolved with whether this element is currently selected. + */ + isSelected(): promise.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 the form has been submitted. + */ + submit(): promise.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 + * when the element has been cleared. + */ + clear(): promise.Promise; + + /** + * Schedules a command to test whether this element is currently displayed. + * @return {!promise.Promise.} A promise that will be + * resolved with whether this element is currently visible on the page. + */ + isDisplayed(): promise.Promise; + + /** + * Take a screenshot of the visible region encompassed by this element's + * bounding rectangle. + * + * @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 + * resolved to the screenshot as a base-64 encoded PNG. + */ + takeScreenshot(opt_scroll?: boolean): promise.Promise; + + /** @override */ + serialize(): promise.Promise; +} + +/** + * WebElementPromise is a promise that will be fulfilled with a WebElement. + * This serves as a forward proxy on WebElement, allowing calls to be + * scheduled without directly on this instance before the underlying + * WebElement has been fulfilled. In other words, the following two statements + * are equivalent: + * 
    
+ *     driver.findElement({id: 'my-button'}).click();
+ *     driver.findElement({id: 'my-button'}).then(function(el) {
+ *       return el.click();
+ *     });
+ *
    + * + * @param {!WebDriver} driver The parent WebDriver instance for this + * element. + * @param {!promise.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 class WebElementPromise extends WebElement { + /** + * @param {!WebDriver} driver The parent WebDriver instance for this + * element. + * @param {!promise.Promise} el A promise + * that will resolve to the promised element. + */ + constructor(driver: WebDriver, el: promise.Promise); +} + +/** + * Contains information about a WebDriver session. + */ +export class Session { + // region Constructors + + /** + * @param {string} id The session ID. + * @param {!(Object|Capabilities)} capabilities The session + * capabilities. + * @constructor + */ + constructor(id: string, capabilities: Capabilities | Object); + + // endregion + + // region Methods + + /** + * @return {string} This session's ID. + */ + getId(): string; + + /** + * @return {!Capabilities} This session's capabilities. + */ + getCapabilities(): Capabilities; + + /** + * Retrieves the value of a specific capability. + * @param {string} key The capability to retrieve. + * @return {*} The capability value. + */ + getCapability(key: string): any; + + /** + * Returns the JSON representation of this object, which is just the string + * session ID. + * @return {string} The JSON representation of this Session. + */ + toJSON(): string; + + // endregion +} diff --git a/types/selenium-webdriver/opera.d.ts b/types/selenium-webdriver/v3/opera.d.ts similarity index 100% rename from types/selenium-webdriver/opera.d.ts rename to types/selenium-webdriver/v3/opera.d.ts diff --git a/types/selenium-webdriver/v3/remote.d.ts b/types/selenium-webdriver/v3/remote.d.ts new file mode 100644 index 0000000000..3ef73c953d --- /dev/null +++ b/types/selenium-webdriver/v3/remote.d.ts @@ -0,0 +1,242 @@ +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/types/selenium-webdriver/v3/safari.d.ts b/types/selenium-webdriver/v3/safari.d.ts new file mode 100644 index 0000000000..bbeb887410 --- /dev/null +++ b/types/selenium-webdriver/v3/safari.d.ts @@ -0,0 +1,91 @@ +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/types/selenium-webdriver/v3/test/chrome.ts b/types/selenium-webdriver/v3/test/chrome.ts new file mode 100644 index 0000000000..5301934933 --- /dev/null +++ b/types/selenium-webdriver/v3/test/chrome.ts @@ -0,0 +1,62 @@ +import * as chrome from 'selenium-webdriver/chrome'; +import * as remote from 'selenium-webdriver/remote'; +import * as webdriver from 'selenium-webdriver'; + +function TestChromeDriver() { + let driver: chrome.Driver = chrome.Driver.createSession(); + driver = chrome.Driver.createSession(webdriver.Capabilities.chrome()); + driver = chrome.Driver.createSession(webdriver.Capabilities.chrome(), + new remote.DriverService('executable', new chrome.Options()), + new webdriver.promise.ControlFlow()); + + let baseDriver: webdriver.WebDriver = driver; +} + +function TestChromeOptions() { + let options: chrome.Options = new chrome.Options(); + options = chrome.Options.fromCapabilities(webdriver.Capabilities.chrome()); + + options = options.addArguments('a', 'b', 'c'); + options = options.addExtensions('a', 'b', 'c'); + options = options.excludeSwitches('a', 'b', 'c'); + options = options.detachDriver(true); + options = options.setChromeBinaryPath('path'); + options = options.setChromeLogFile('logfile'); + options = options.setLocalState('state'); + options = options.androidActivity('com.example.Activity'); + options = options.headless(); + options = options.androidDeviceSerial('emulator-5554'); + options = options.androidChrome(); + options = options.androidPackage('com.android.chrome'); + options = options.androidProcess('com.android.chrome'); + options = options.androidUseRunningApp(true); + options = options.setLoggingPrefs(new webdriver.logging.Preferences()); + options = options.setPerfLoggingPrefs({ + enableNetwork: true, enablePage: true, enableTimeline: true, + tracingCategories: 'category', bufferUsageReportingInterval: 1000 }); + options = options.setProxy({ proxyType: 'proxyType' }); + options = options.setUserPreferences('preferences'); + let capabilities: webdriver.Capabilities = options.toCapabilities(); + capabilities = options.toCapabilities(webdriver.Capabilities.chrome()); +} + +function TestServiceBuilder() { + let builder: chrome.ServiceBuilder = new chrome.ServiceBuilder(); + builder = new chrome.ServiceBuilder('exe'); + + let anything: any = builder.build(); + builder = builder.setPort(8080); + builder = builder.setAdbPort(5037); + builder = builder.loggingTo('path'); + builder = builder.enableVerboseLogging(); + builder = builder.setNumHttpThreads(5); + builder = builder.setPath('path'); + builder = builder.setStdio('config'); + builder = builder.setStdio(['A', 'B']); + builder = builder.setEnvironment({ A: 'a', B: 'b' }); +} + +function TestChromeModule() { + let service: any = chrome.getDefaultService(); + chrome.setDefaultService(new remote.DriverService('executable', new chrome.Options())); +} diff --git a/types/selenium-webdriver/v3/test/firefox.ts b/types/selenium-webdriver/v3/test/firefox.ts new file mode 100644 index 0000000000..ee5b55bbaa --- /dev/null +++ b/types/selenium-webdriver/v3/test/firefox.ts @@ -0,0 +1,79 @@ +import * as firefox from 'selenium-webdriver/firefox'; +import * as remote from 'selenium-webdriver/remote'; +import * as webdriver from 'selenium-webdriver'; +import * as http from 'selenium-webdriver/http'; + +function TestBinary() { + let binary: firefox.Binary = new firefox.Binary(); + binary = new firefox.Binary('exe'); + + binary.addArguments('A', 'B', 'C'); + let promise: webdriver.promise.Promise = binary.kill(); + binary.launch('profile').then((result: any) => {}); +} + +function TestFirefoxDriver() { + let driver: firefox.Driver = firefox.Driver.createSession(); + driver = firefox.Driver.createSession(webdriver.Capabilities.firefox()); + driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new http.Executor(new http.HttpClient('http://someurl'))); + driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new remote.DriverService('/dev/null', {})); + driver = firefox.Driver.createSession(webdriver.Capabilities.firefox(), new remote.DriverService('/dev/null', {}), new webdriver.promise.ControlFlow()); + + let baseDriver: webdriver.WebDriver = driver; +} + +function TestFirefoxOptions() { + let options: firefox.Options = new firefox.Options(); + + options = options.addArguments('foo', 'bar'); + options = options.windowSize({ width: 320, height: 480 }); + options = options.addExtensions('foo', 'bar'); + options = options.setPreference('a', 1); + options = options.setPreference('a', true); + options = options.setPreference('a', '1'); + options = options.setBinary('binary'); + options = options.setBinary(new firefox.Binary()); + options = options.setLoggingPreferences(new webdriver.logging.Preferences()); + options = options.setProfile('profile'); + options = options.setProfile(new firefox.Profile()); + options = options.setProxy({ proxyType: 'proxy' }); + let capabilities: webdriver.Capabilities = options.toCapabilities(); +} + +function TestFirefoxProfile() { + let profile: firefox.Profile = new firefox.Profile(); + profile = new firefox.Profile('dir'); + + let bool: boolean = profile.acceptUntrustedCerts(); + profile.addExtension('ext'); + bool = profile.assumeUntrustedCertIssuer(); + profile.encode().then((prof: string) => {}); + let num: number = profile.getPort(); + let anything: any = profile.getPreference('key'); + bool = profile.nativeEventsEnabled(); + profile.setAcceptUntrustedCerts(true); + profile.setAssumeUntrustedCertIssuer(true); + profile.setNativeEventsEnabled(true); + profile.setPort(8080); + profile.setPreference('key', 'value'); + profile.setPreference('key', 5); + profile.setPreference('key', true); + let stringPromise: webdriver.promise.Promise = profile.writeToDisk(); + stringPromise = profile.writeToDisk(true); +} + +function TestServiceBuilder() { + let builder: firefox.ServiceBuilder = new firefox.ServiceBuilder(); + builder = new firefox.ServiceBuilder('exe'); + + let anything: any = builder.build(); + builder = builder.setPort(8080); + builder = builder.enableVerboseLogging(); + builder = builder.enableVerboseLogging(true); + builder = builder.setFirefoxBinary('exe'); + builder = builder.setFirefoxBinary(new firefox.Binary()); + builder = builder.setPath('path'); + builder = builder.setStdio('config'); + builder = builder.setStdio(['A', 'B']); + builder = builder.setEnvironment({ A: 'a', B: 'b' }); +} diff --git a/types/selenium-webdriver/v3/test/index.ts b/types/selenium-webdriver/v3/test/index.ts new file mode 100644 index 0000000000..84ffc6a8c2 --- /dev/null +++ b/types/selenium-webdriver/v3/test/index.ts @@ -0,0 +1,991 @@ +import * as webdriver from 'selenium-webdriver'; +import * as chrome from 'selenium-webdriver/chrome'; +import * as edge from 'selenium-webdriver/edge'; +import * as firefox from 'selenium-webdriver/firefox'; +import * as http from 'selenium-webdriver/http'; +import * as remote from 'selenium-webdriver/remote'; +import * as safari from 'selenium-webdriver/safari'; +import * as testing from 'selenium-webdriver/testing'; + +function TestBuilder() { + let builder: webdriver.Builder = new webdriver.Builder(); + + let driver: webdriver.WebDriver = builder.build(); + builder = builder.forBrowser('name'); + builder = builder.forBrowser('name', 'version'); + builder = builder.forBrowser('name', 'version', 'platform'); + + let cap: webdriver.Capabilities = builder.getCapabilities(); + let str: string = builder.getServerUrl(); + + builder = builder.setAlertBehavior('behavior'); + builder = builder.setChromeOptions(new chrome.Options()); + builder = builder.setChromeService(new chrome.ServiceBuilder()); + builder = builder.setControlFlow(new webdriver.promise.ControlFlow()); + builder = builder.setEdgeOptions(new edge.Options()); + builder = builder.setEdgeService(new edge.ServiceBuilder()); + builder = builder.setEnableNativeEvents(true); + builder = builder.setFirefoxOptions(new firefox.Options()); + builder = builder.setFirefoxService(new firefox.ServiceBuilder()); + builder = builder.setLoggingPrefs(new webdriver.logging.Preferences()); + builder = builder.setLoggingPrefs({ key: 'value' }); + builder = builder.setProxy({ proxyType: 'type' }); + builder = builder.setSafariOptions(new safari.Options()); + builder = builder.setScrollBehavior(1); + builder = builder.usingServer('http://someserver'); + builder = builder.withCapabilities(new webdriver.Capabilities()); + builder = builder.withCapabilities({ something: true }); + + const chromeOptions: chrome.Options = builder.getChromeOptions(); + const firefoxOptions: firefox.Options = builder.getFirefoxOptions(); + const safariOptions: safari.Options = builder.getSafariOptions(); +} + +declare const promise: webdriver.promise.Promise; + +function TestActionSequence() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let sequence: webdriver.ActionSequence = new webdriver.ActionSequence(driver); + let element: webdriver.WebElement = new webdriver.WebElement(driver, 'elementId'); + element = new webdriver.WebElement(driver, promise); + + // Click + sequence = sequence.click(); + sequence = sequence.click(webdriver.Button.LEFT); + sequence = sequence.click(element); + sequence = sequence.click(element, webdriver.Button.LEFT); + + // DoubleClick + sequence = sequence.doubleClick(); + sequence = sequence.doubleClick(webdriver.Button.LEFT); + sequence = sequence.doubleClick(element); + sequence = sequence.doubleClick(element, webdriver.Button.LEFT); + + // DragAndDrop + sequence = sequence.dragAndDrop(element, element); + sequence = sequence.dragAndDrop(element, { x: 1, y: 2 }); + + // KeyDown + sequence = sequence.keyDown(webdriver.Key.ADD); + + // KeyUp + sequence = sequence.keyUp(webdriver.Key.ADD); + + // MouseDown + sequence = sequence.mouseDown(); + sequence = sequence.mouseDown(webdriver.Button.LEFT); + sequence = sequence.mouseDown(element); + sequence = sequence.mouseDown(element, webdriver.Button.LEFT); + + // MouseMove + sequence = sequence.mouseMove(element); + sequence = sequence.mouseMove({ x: 1, y: 1 }); + sequence = sequence.mouseMove(element, { x: 1, y: 2 }); + + // MouseUp + sequence = sequence.mouseUp(); + sequence = sequence.mouseUp(webdriver.Button.LEFT); + sequence = sequence.mouseUp(element); + sequence = sequence.mouseUp(element, webdriver.Button.LEFT); + + // SendKeys + sequence = sequence.sendKeys('A', 'B', 'C'); + sequence = sequence.sendKeys('A', webdriver.Key.NULL); + + sequence.perform().then(() => {}); +} + +function TestTouchSequence() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + let element: webdriver.WebElement = new webdriver.WebElement(driver, 'elementId'); + + let sequence: webdriver.TouchSequence = new webdriver.TouchSequence(driver); + + sequence = sequence.tap(element); + sequence = sequence.doubleTap(element); + sequence = sequence.longPress(element); + sequence = sequence.tapAndHold({ x: 100, y: 100 }); + sequence = sequence.move({ x: 100, y: 100 }); + sequence = sequence.release({ x: 100, y: 100 }); + sequence = sequence.scroll({ x: 100, y: 100 }); + sequence = sequence.scrollFromElement(element, { x: 100, y: 100 }); + sequence = sequence.flick({ xspeed: 100, yspeed: 100 }); + sequence = sequence.flickElement(element, { x: 100, y: 100 }, 100); + + sequence.perform().then(() => {}); +} + +function TestAlert() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let alert: webdriver.Alert = driver.switchTo().alert(); + + alert.accept().then(() => {}); + alert.dismiss().then(() => {}); + alert.getText().then((text: string) => {}); + alert.sendKeys('ABC').then(() => {}); +} + +function TestBrowser() { + let browser: string; + + browser = webdriver.Browser.ANDROID; + browser = webdriver.Browser.CHROME; + browser = webdriver.Browser.FIREFOX; + browser = webdriver.Browser.HTMLUNIT; + browser = webdriver.Browser.INTERNET_EXPLORER; + browser = webdriver.Browser.IPAD; + browser = webdriver.Browser.IPHONE; + browser = webdriver.Browser.OPERA; + browser = webdriver.Browser.PHANTOM_JS; + browser = webdriver.Browser.SAFARI; +} + +function TestButton() { + let button: string; + + button = webdriver.Button.LEFT; + button = webdriver.Button.MIDDLE; + button = webdriver.Button.RIGHT; +} + +function TestCapabilities() { + let capabilities: webdriver.Capabilities = new webdriver.Capabilities(); + capabilities = new webdriver.Capabilities(webdriver.Capabilities.chrome()); + let objCapabilities: any = {}; + objCapabilities[webdriver.Capability.BROWSER_NAME] = webdriver.Browser.PHANTOM_JS; + capabilities = new webdriver.Capabilities(objCapabilities); + + let anything: any = capabilities.get(webdriver.Capability.SECURE_SSL); + let check: boolean = capabilities.has(webdriver.Capability.SECURE_SSL); + capabilities = capabilities.merge(capabilities); + capabilities = capabilities.merge(objCapabilities); + capabilities = capabilities.set(webdriver.Capability.VERSION, { abc: 'def' }); + capabilities = capabilities.set(webdriver.Capability.VERSION, null); + capabilities = capabilities.setLoggingPrefs(new webdriver.logging.Preferences()); + capabilities = capabilities.setLoggingPrefs({ key: 'value' }); + capabilities = capabilities.setProxy({ proxyType: 'Type' }); + capabilities = capabilities.setEnableNativeEvents(true); + capabilities = capabilities.setScrollBehavior(1); + capabilities = capabilities.setAlertBehavior('accept'); + + anything = capabilities.toJSON(); + + capabilities = webdriver.Capabilities.android(); + capabilities = webdriver.Capabilities.chrome(); + capabilities = webdriver.Capabilities.firefox(); + capabilities = webdriver.Capabilities.htmlunit(); + capabilities = webdriver.Capabilities.htmlunitwithjs(); + capabilities = webdriver.Capabilities.ie(); + capabilities = webdriver.Capabilities.ipad(); + capabilities = webdriver.Capabilities.iphone(); + capabilities = webdriver.Capabilities.opera(); + capabilities = webdriver.Capabilities.phantomjs(); + capabilities = webdriver.Capabilities.safari(); +} + +function TestCapability() { + let capability: string; + + capability = webdriver.Capability.ACCEPT_SSL_CERTS; + capability = webdriver.Capability.BROWSER_NAME; + capability = webdriver.Capability.ELEMENT_SCROLL_BEHAVIOR; + capability = webdriver.Capability.HANDLES_ALERTS; + capability = webdriver.Capability.LOGGING_PREFS; + capability = webdriver.Capability.NATIVE_EVENTS; + capability = webdriver.Capability.PLATFORM; + capability = webdriver.Capability.PROXY; + capability = webdriver.Capability.ROTATABLE; + capability = webdriver.Capability.SECURE_SSL; + capability = webdriver.Capability.SUPPORTS_APPLICATION_CACHE; + capability = webdriver.Capability.SUPPORTS_CSS_SELECTORS; + capability = webdriver.Capability.SUPPORTS_JAVASCRIPT; + capability = webdriver.Capability.SUPPORTS_LOCATION_CONTEXT; + capability = webdriver.Capability.TAKES_SCREENSHOT; + capability = webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR; + capability = webdriver.Capability.VERSION; +} + +function TestCommand() { + let command: webdriver.Command = new webdriver.Command(webdriver.CommandName.ADD_COOKIE); + + let name: string = command.getName(); + let param: any = command.getParameter('param'); + + let params: any = command.getParameters(); + + command = command.setParameter('param', 123); + command = command.setParameters({ param: 123 }); +} + +function TestCommandName() { + let command: string; + + command = webdriver.CommandName.ACCEPT_ALERT; + command = webdriver.CommandName.ADD_COOKIE; + command = webdriver.CommandName.CLEAR_APP_CACHE; + command = webdriver.CommandName.CLEAR_ELEMENT; + command = webdriver.CommandName.CLEAR_LOCAL_STORAGE; + command = webdriver.CommandName.CLEAR_SESSION_STORAGE; + command = webdriver.CommandName.CLICK; + command = webdriver.CommandName.CLICK_ELEMENT; + command = webdriver.CommandName.CLOSE; + command = webdriver.CommandName.DELETE_ALL_COOKIES; + command = webdriver.CommandName.DELETE_COOKIE; + command = webdriver.CommandName.DESCRIBE_SESSION; + command = webdriver.CommandName.DISMISS_ALERT; + command = webdriver.CommandName.DOUBLE_CLICK; + command = webdriver.CommandName.ELEMENT_EQUALS; + command = webdriver.CommandName.EXECUTE_ASYNC_SCRIPT; + command = webdriver.CommandName.EXECUTE_SCRIPT; + command = webdriver.CommandName.EXECUTE_SQL; + command = webdriver.CommandName.FIND_CHILD_ELEMENT; + command = webdriver.CommandName.FIND_CHILD_ELEMENTS; + command = webdriver.CommandName.FIND_ELEMENT; + command = webdriver.CommandName.FIND_ELEMENTS; + command = webdriver.CommandName.GET; + command = webdriver.CommandName.GET_ACTIVE_ELEMENT; + command = webdriver.CommandName.GET_ALERT_TEXT; + command = webdriver.CommandName.GET_ALL_COOKIES; + command = webdriver.CommandName.GET_APP_CACHE; + command = webdriver.CommandName.GET_APP_CACHE_STATUS; + command = webdriver.CommandName.GET_AVAILABLE_LOG_TYPES; + command = webdriver.CommandName.GET_COOKIE; + command = webdriver.CommandName.GET_CURRENT_URL; + command = webdriver.CommandName.GET_CURRENT_WINDOW_HANDLE; + command = webdriver.CommandName.GET_ELEMENT_ATTRIBUTE; + command = webdriver.CommandName.GET_ELEMENT_LOCATION; + command = webdriver.CommandName.GET_ELEMENT_LOCATION_IN_VIEW; + command = webdriver.CommandName.GET_ELEMENT_SIZE; + command = webdriver.CommandName.GET_ELEMENT_TAG_NAME; + command = webdriver.CommandName.GET_ELEMENT_TEXT; + command = webdriver.CommandName.GET_ELEMENT_VALUE_OF_CSS_PROPERTY; + command = webdriver.CommandName.GET_LOCAL_STORAGE_ITEM; + command = webdriver.CommandName.GET_LOCAL_STORAGE_KEYS; + command = webdriver.CommandName.GET_LOCAL_STORAGE_SIZE; + command = webdriver.CommandName.GET_LOCATION; + command = webdriver.CommandName.GET_LOG; + command = webdriver.CommandName.GET_PAGE_SOURCE; + command = webdriver.CommandName.GET_SCREEN_ORIENTATION; + command = webdriver.CommandName.GET_SERVER_STATUS; + command = webdriver.CommandName.GET_SESSION_LOGS; + command = webdriver.CommandName.GET_SESSION_STORAGE_ITEM; + command = webdriver.CommandName.GET_SESSION_STORAGE_KEYS; + command = webdriver.CommandName.GET_SESSION_STORAGE_SIZE; + command = webdriver.CommandName.GET_SESSIONS; + command = webdriver.CommandName.GET_TITLE; + command = webdriver.CommandName.GET_WINDOW_HANDLES; + command = webdriver.CommandName.GET_WINDOW_POSITION; + command = webdriver.CommandName.GET_WINDOW_SIZE; + command = webdriver.CommandName.GO_BACK; + command = webdriver.CommandName.GO_FORWARD; + command = webdriver.CommandName.IMPLICITLY_WAIT; + command = webdriver.CommandName.IS_BROWSER_ONLINE; + command = webdriver.CommandName.IS_ELEMENT_DISPLAYED; + command = webdriver.CommandName.IS_ELEMENT_ENABLED; + command = webdriver.CommandName.IS_ELEMENT_SELECTED; + command = webdriver.CommandName.MAXIMIZE_WINDOW; + command = webdriver.CommandName.MOUSE_DOWN; + command = webdriver.CommandName.MOUSE_UP; + command = webdriver.CommandName.MOVE_TO; + command = webdriver.CommandName.NEW_SESSION; + command = webdriver.CommandName.QUIT; + command = webdriver.CommandName.REFRESH; + command = webdriver.CommandName.REMOVE_LOCAL_STORAGE_ITEM; + command = webdriver.CommandName.REMOVE_SESSION_STORAGE_ITEM; + command = webdriver.CommandName.SCREENSHOT; + command = webdriver.CommandName.SEND_KEYS_TO_ACTIVE_ELEMENT; + command = webdriver.CommandName.SEND_KEYS_TO_ELEMENT; + command = webdriver.CommandName.SET_ALERT_TEXT; + command = webdriver.CommandName.SET_BROWSER_ONLINE; + command = webdriver.CommandName.SET_LOCAL_STORAGE_ITEM; + command = webdriver.CommandName.SET_LOCATION; + command = webdriver.CommandName.SET_SCREEN_ORIENTATION; + command = webdriver.CommandName.SET_SCRIPT_TIMEOUT; + command = webdriver.CommandName.SET_SESSION_STORAGE_ITEM; + command = webdriver.CommandName.SET_TIMEOUT; + command = webdriver.CommandName.SET_WINDOW_POSITION; + command = webdriver.CommandName.SET_WINDOW_SIZE; + command = webdriver.CommandName.SUBMIT_ELEMENT; + command = webdriver.CommandName.SWITCH_TO_FRAME; + command = webdriver.CommandName.SWITCH_TO_WINDOW; + command = webdriver.CommandName.TOUCH_DOUBLE_TAP; + command = webdriver.CommandName.TOUCH_DOWN; + command = webdriver.CommandName.TOUCH_FLICK; + command = webdriver.CommandName.TOUCH_LONG_PRESS; + command = webdriver.CommandName.TOUCH_MOVE; + command = webdriver.CommandName.TOUCH_SCROLL; + command = webdriver.CommandName.TOUCH_SINGLE_TAP; + command = webdriver.CommandName.TOUCH_UP; +} + +function TestEventEmitter() { + let emitter: webdriver.EventEmitter = new webdriver.EventEmitter(); + + let callback = (a: number, b: number, c: number) => {}; + + emitter = emitter.addListener('ABC', callback); + emitter = emitter.addListener('ABC', callback, this); + + emitter.emit('ABC', 1, 2, 3); + + let listeners = emitter.listeners('ABC'); + if (listeners[0].oneshot) { + listeners[0].fn.apply(listeners[0].scope); + } + let length: number = listeners.length; + let listenerInfo = listeners[0]; + if (listenerInfo.oneshot) { + listenerInfo.fn.apply(listenerInfo.scope, [1, 2, 3]); + } + + emitter = emitter.on('ABC', callback); + emitter = emitter.on('ABC', callback, this); + + emitter = emitter.once('ABC', callback); + emitter = emitter.once('ABC', callback, this); + + emitter = emitter.removeListener('ABC', callback); + + emitter.removeAllListeners('ABC'); + emitter.removeAllListeners(); +} + +function TestKey() { + let key: string; + + key = webdriver.Key.ADD; + key = webdriver.Key.ALT; + key = webdriver.Key.ARROW_DOWN; + key = webdriver.Key.ARROW_LEFT; + key = webdriver.Key.ARROW_RIGHT; + key = webdriver.Key.ARROW_UP; + key = webdriver.Key.BACK_SPACE; + key = webdriver.Key.CANCEL; + key = webdriver.Key.CLEAR; + key = webdriver.Key.COMMAND; + key = webdriver.Key.CONTROL; + key = webdriver.Key.DECIMAL; + key = webdriver.Key.DELETE; + key = webdriver.Key.DIVIDE; + key = webdriver.Key.DOWN; + key = webdriver.Key.END; + key = webdriver.Key.ENTER; + key = webdriver.Key.EQUALS; + key = webdriver.Key.ESCAPE; + key = webdriver.Key.F1; + key = webdriver.Key.F2; + key = webdriver.Key.F3; + key = webdriver.Key.F4; + key = webdriver.Key.F5; + key = webdriver.Key.F6; + key = webdriver.Key.F7; + key = webdriver.Key.F8; + key = webdriver.Key.F9; + key = webdriver.Key.F10; + key = webdriver.Key.F11; + key = webdriver.Key.F12; + key = webdriver.Key.HELP; + key = webdriver.Key.HOME; + key = webdriver.Key.INSERT; + key = webdriver.Key.LEFT; + key = webdriver.Key.META; + key = webdriver.Key.MULTIPLY; + key = webdriver.Key.NULL; + key = webdriver.Key.NUMPAD0; + key = webdriver.Key.NUMPAD1; + key = webdriver.Key.NUMPAD2; + key = webdriver.Key.NUMPAD3; + key = webdriver.Key.NUMPAD4; + key = webdriver.Key.NUMPAD5; + key = webdriver.Key.NUMPAD6; + key = webdriver.Key.NUMPAD7; + key = webdriver.Key.NUMPAD8; + key = webdriver.Key.NUMPAD9; + key = webdriver.Key.PAGE_DOWN; + key = webdriver.Key.PAGE_UP; + key = webdriver.Key.PAUSE; + key = webdriver.Key.RETURN; + key = webdriver.Key.RIGHT; + key = webdriver.Key.SEMICOLON; + key = webdriver.Key.SEPARATOR; + key = webdriver.Key.SHIFT; + key = webdriver.Key.SPACE; + key = webdriver.Key.SUBTRACT; + key = webdriver.Key.TAB; + key = webdriver.Key.UP; +} + +function TestBy() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let locator: webdriver.By = new webdriver.By('class name', 'class'); + + let str: string = locator.toString(); + + locator = webdriver.By.className('class'); + locator = webdriver.By.css('css'); + locator = webdriver.By.id('id'); + locator = webdriver.By.linkText('link'); + locator = webdriver.By.name('name'); + locator = webdriver.By.partialLinkText('text'); + locator = webdriver.By.tagName('tag'); + locator = webdriver.By.xpath('xpath'); + + // Can import 'By' without import declarations + let By = webdriver.By; + + let locatorHash: webdriver.ByHash; + locatorHash = { className: 'class' }; + locatorHash = { css: 'css' }; + locatorHash = { id: 'id' }; + locatorHash = { linkText: 'link' }; + locatorHash = { name: 'name' }; + locatorHash = { partialLinkText: 'text' }; + locatorHash = { tagName: 'tag' }; + locatorHash = { xpath: 'xpath' }; + + webdriver.By.js('script', 1, 2, 3)(driver).then((abc: number) => {}); +} + +function TestSession() { + let session: webdriver.Session = new webdriver.Session('ABC', webdriver.Capabilities.android()); + let capabilitiesObj: any = {}; + capabilitiesObj[webdriver.Capability.BROWSER_NAME] = webdriver.Browser.ANDROID; + capabilitiesObj[webdriver.Capability.PLATFORM] = 'ANDROID'; + session = new webdriver.Session('ABC', capabilitiesObj); + + let capabilities: webdriver.Capabilities = session.getCapabilities(); + let capability: any = session.getCapability(webdriver.Capability.BROWSER_NAME); + let id: string = session.getId(); + let data: string = session.toJSON(); +} + +function TestWebDriverFileDetector() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let fileDetector: webdriver.FileDetector = new webdriver.FileDetector(); + + fileDetector.handleFile(driver, 'path/to/file').then((path: string) => {}); +} + +function TestWebDriverLogs() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let logs: webdriver.Logs = new webdriver.Logs(driver); + + logs.get(webdriver.logging.Type.BROWSER).then((entries: webdriver.logging.Entry[]) => {}); + logs.getAvailableLogTypes().then((types: string[]) => {}); +} + +function TestWebDriverNavigation() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let navigation: webdriver.Navigation = new webdriver.Navigation(driver); + + navigation.back().then(() => {}); + navigation.forward().then(() => {}); + navigation.refresh().then(() => {}); + navigation.to('http://google.com').then(() => {}); +} + +function TestWebDriverOptions() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let options: webdriver.Options = new webdriver.Options(driver); + let promise: webdriver.promise.Promise; + + let name: string = 'name'; + let value: string = 'value'; + let path: string = 'path'; + let domain: string = 'domain'; + let secure: boolean = true; + let httpOnly: boolean = true; + + // Add Cookie + promise = options.addCookie({ name, value }); + promise = options.addCookie({ name, value, path }); + promise = options.addCookie({ name, value, path, domain }); + promise = options.addCookie({ name, value, path, domain, secure }); + promise = options.addCookie({ name, value, path, domain, secure, httpOnly }); + promise = options.addCookie({ name, value, path, domain, secure, httpOnly, expiry: 123 }); + promise = options.addCookie({ name, value, path, domain, secure, httpOnly, expiry: Date.now() }); + + promise = options.deleteAllCookies(); + promise = options.deleteCookie('name'); + options.getCookie('name').then((cookie: webdriver.IWebDriverCookie) => { + let expiry: number | undefined = cookie.expiry; + }); + options.getCookies().then((cookies: webdriver.IWebDriverCookie[]) => { }); + + let logs: webdriver.Logs = options.logs(); + let timeouts: webdriver.Timeouts = options.timeouts(); + let window: webdriver.Window = options.window(); +} + +function TestWebDriverTargetLocator() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let locator: webdriver.TargetLocator = new webdriver.TargetLocator(driver); + let promise: webdriver.promise.Promise; + + let element: webdriver.WebElement = locator.activeElement(); + let alert: webdriver.Alert = locator.alert(); + promise = locator.defaultContent(); + promise = locator.frame(1); + promise = locator.window('nameOrHandle'); +} + +function TestWebDriverTimeouts() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let timeouts: webdriver.Timeouts = new webdriver.Timeouts(driver); + let promise: webdriver.promise.Promise; + + promise = timeouts.implicitlyWait(123); + promise = timeouts.pageLoadTimeout(123); + promise = timeouts.setScriptTimeout(123); +} + +function TestWebDriverWindow() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let window: webdriver.Window = new webdriver.Window(driver); + let locationPromise: webdriver.promise.Promise; + let sizePromise: webdriver.promise.Promise; + let voidPromise: webdriver.promise.Promise; + + locationPromise = window.getPosition(); + sizePromise = window.getSize(); + voidPromise = window.maximize(); + voidPromise = window.setPosition(12, 34); + voidPromise = window.setSize(12, 34); +} + +declare const sessionPromise: webdriver.promise.Promise; +declare let booleanPromise: webdriver.promise.Promise; +declare const booleanCondition: webdriver.Condition; +declare const webElementCondition: webdriver.WebElementCondition; + +function TestWebDriver() { + let session: webdriver.Session = new webdriver.Session('ABC', webdriver.Capabilities.android()); + let httpClient: http.HttpClient = new http.HttpClient('http://someserver'); + let executor: http.Executor = new http.Executor(httpClient); + let flow: webdriver.promise.ControlFlow = new webdriver.promise.ControlFlow(); + let driver: webdriver.WebDriver = new webdriver.WebDriver(session, executor); + driver = new webdriver.WebDriver(session, executor, flow); + driver = new webdriver.WebDriver(sessionPromise, executor); + driver = new webdriver.WebDriver(sessionPromise, executor, flow); + + let voidPromise: webdriver.promise.Promise; + let stringPromise: webdriver.promise.Promise; + let webElementPromise: webdriver.WebElementPromise; + + let actions: webdriver.ActionSequence = driver.actions(); + let touchActions: webdriver.TouchSequence = driver.touchActions(); + + // call + stringPromise = driver.call(() => 'value'); + stringPromise = driver.call(() => stringPromise); + stringPromise = driver.call(() => 'value', driver); + stringPromise = driver.call((a: number) => 'value', driver, 1); + + voidPromise = driver.close(); + flow = driver.controlFlow(); + + // executeAsyncScript + stringPromise = driver.executeAsyncScript('function(){}'); + stringPromise = driver.executeAsyncScript('function(){}', 1, 2, 3); + stringPromise = driver.executeAsyncScript(() => {}); + stringPromise = driver.executeAsyncScript((a: number) => {}, 1); + + // executeScript + stringPromise = driver.executeScript('function(){}'); + stringPromise = driver.executeScript('function(){}', 1, 2, 3); + stringPromise = driver.executeScript(() => {}); + stringPromise = driver.executeScript((a: number) => {}, 1); + + // findElement + let element: webdriver.WebElement; + element = driver.findElement(webdriver.By.id('ABC')); + element = driver.findElement(webdriver.By.js('function(){}')); + + // findElements + driver.findElements(webdriver.By.className('ABC')).then((elements: webdriver.WebElement[]) => {}); + driver.findElements(webdriver.By.js('function(){}')).then((elements: webdriver.WebElement[]) => {}); + + voidPromise = driver.get('http://www.google.com'); + driver.getAllWindowHandles().then((handles: string[]) => {}); + driver.getCapabilities().then((caps: webdriver.Capabilities) => {}); + stringPromise = driver.getCurrentUrl(); + stringPromise = driver.getPageSource(); + driver.getSession().then((session: webdriver.Session) => {}); + stringPromise = driver.getTitle(); + stringPromise = driver.getWindowHandle(); + + let options: webdriver.Options = driver.manage(); + let navigation: webdriver.Navigation = driver.navigate(); + let locator: webdriver.TargetLocator = driver.switchTo(); + + let fileDetector: webdriver.FileDetector = new webdriver.FileDetector(); + driver.setFileDetector(fileDetector); + + voidPromise = driver.quit(); + voidPromise = driver.schedule(new webdriver.Command(webdriver.CommandName.CLICK), 'ABC'); + voidPromise = driver.sleep(123); + stringPromise = driver.takeScreenshot(); + + booleanPromise = driver.wait(booleanPromise); + booleanPromise = driver.wait(booleanCondition); + booleanPromise = driver.wait((driver: webdriver.WebDriver) => true); + booleanPromise = driver.wait((driver: webdriver.WebDriver) => Promise.resolve(true)); + booleanPromise = driver.wait((driver: webdriver.WebDriver) => webdriver.promise.Promise.resolve(true)); + booleanPromise = driver.wait(booleanPromise, 123); + booleanPromise = driver.wait(booleanPromise, 123, 'Message'); + webElementPromise = driver.wait(webElementCondition); + voidPromise = driver.wait(webElementCondition).click(); + + driver = webdriver.WebDriver.attachToSession(executor, 'ABC'); + driver = webdriver.WebDriver.createSession(executor, webdriver.Capabilities.android()); +} + +declare const serializable: webdriver.Serializable; + +function TestSerializable() { + let serial: string | webdriver.promise.IThenable = serializable.serialize(); +} + +function TestWebElement() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let element: webdriver.WebElement; + + element = new webdriver.WebElement(driver, 'elementId'); + element = new webdriver.WebElement(driver, promise); + + let voidPromise: webdriver.promise.Promise; + let stringPromise: webdriver.promise.Promise; + let booleanPromise: webdriver.promise.Promise; + + voidPromise = element.clear(); + voidPromise = element.click(); + + element = element.findElement(webdriver.By.id('ABC')); + element = element.findElement({id: 'ABC'}); + element.findElements({className: 'ABC'}).then((elements: webdriver.WebElement[]) => { }); + + stringPromise = element.getAttribute('class'); + stringPromise = element.getCssValue('display'); + driver = element.getDriver(); + element.getLocation().then((location: webdriver.ILocation) => {}); + element.getSize().then((size: webdriver.ISize) => {}); + stringPromise = element.getTagName(); + stringPromise = element.getText(); + booleanPromise = element.isDisplayed(); + booleanPromise = element.isEnabled(); + booleanPromise = element.isSelected(); + voidPromise = element.sendKeys('A', 'B', 'C'); + voidPromise = element.sendKeys(1, 2, 3); + voidPromise = element.sendKeys(webdriver.Key.BACK_SPACE); + voidPromise = element.sendKeys(stringPromise, stringPromise, stringPromise); + voidPromise = element.sendKeys('A', 1, webdriver.Key.BACK_SPACE, stringPromise); + voidPromise = element.submit(); + element.getId().then((id: string) => {}); + element.serialize().then((id: webdriver.IWebElementId) => {}); + + booleanPromise = webdriver.WebElement.equals(element, new webdriver.WebElement(driver, 'elementId')); +} + +function TestWebElementPromise() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let elementPromise: webdriver.WebElementPromise = driver.findElement(webdriver.By.id('id')); + + elementPromise.then(); + elementPromise.then((element: webdriver.WebElement) => {}); + elementPromise.then((element: webdriver.WebElement) => {}, (error: any) => {}); + elementPromise.then((element: webdriver.WebElement) => 'foo', (error: any) => {}).then((result: string) => {}); +} + +function TestLogging() { + let preferences: webdriver.logging.Preferences = new webdriver.logging.Preferences(); + preferences.setLevel(webdriver.logging.Type.BROWSER, webdriver.logging.Level.ALL); + let prefs: any = preferences.toJSON(); + + let level: webdriver.logging.Level = webdriver.logging.getLevel('OFF'); + level = webdriver.logging.getLevel(1); + + level = webdriver.logging.Level.ALL; + level = webdriver.logging.Level.DEBUG; + level = webdriver.logging.Level.INFO; + level = webdriver.logging.Level.OFF; + level = webdriver.logging.Level.SEVERE; + level = webdriver.logging.Level.WARNING; + + let name: string = level.name; + let value: number = level.value; + + let type: string; + type = webdriver.logging.Type.BROWSER; + type = webdriver.logging.Type.CLIENT; + type = webdriver.logging.Type.DRIVER; + type = webdriver.logging.Type.PERFORMANCE; + type = webdriver.logging.Type.SERVER; + + let logger: webdriver.logging.Logger = webdriver.logging.getLogger(); + webdriver.logging.addConsoleHandler(); + webdriver.logging.addConsoleHandler(logger); + webdriver.logging.removeConsoleHandler(); + webdriver.logging.removeConsoleHandler(logger); +} + +function TestLoggingEntry() { + let entry: webdriver.logging.Entry; + + entry = new webdriver.logging.Entry(webdriver.logging.Level.ALL, 'ABC'); + entry = new webdriver.logging.Entry('ALL', 'ABC'); + entry = new webdriver.logging.Entry(webdriver.logging.Level.ALL, 'ABC', 123); + entry = new webdriver.logging.Entry('ALL', 'ABC', 123); + entry = new webdriver.logging.Entry(webdriver.logging.Level.ALL, 'ABC', 123, webdriver.logging.Type.BROWSER); + entry = new webdriver.logging.Entry('ALL', 'ABC', 123, webdriver.logging.Type.BROWSER); + + let entryObj: any = entry.toJSON(); + + let message: string = entry.message; + let timestamp: number = entry.timestamp; + let type: string = entry.type; +} + +declare let stringPromise: webdriver.promise.Promise; + +function TestPromiseModule() { + let cancellationError: webdriver.promise.CancellationError = new webdriver.promise.CancellationError(); + cancellationError = new webdriver.promise.CancellationError('message'); + let str: string = cancellationError.message; + str = cancellationError.name; + + let numberPromise: webdriver.promise.Promise; + let booleanPromise: webdriver.promise.Promise; + let voidPromise: webdriver.promise.Promise; + + webdriver.promise.all([stringPromise]).then((values: string[]) => {}); + + webdriver.promise.asap('abc', (value: any) => true); + webdriver.promise.asap('abc', (value: any) => {}, (err: any) => 'ABC'); + + stringPromise = webdriver.promise.checkedNodeCall((err: any, value: any) => 'abc'); + + webdriver.promise.consume(() => { + return 5; + }).then((value: number) => {}); + webdriver.promise.consume(() => { + return 5; + }, this).then((value: number) => {}); + webdriver.promise.consume((a: number, b: number, c: number) => 5, this, 1, 2, 3) + .then((value: number) => {}); + + let numbersPromise: webdriver.promise.Promise = webdriver.promise.filter([1, 2, 3], (element: number, type: any, index: number, arr: number[]) => { + return true; + }); + numbersPromise = webdriver.promise.filter([1, 2, 3], (element: number, type: any, index: number, arr: number[]) => { + return true; + }, this); + numbersPromise = webdriver.promise.filter(numbersPromise, (element: number, type: any, index: number, arr: number[]) => { + return true; + }); + numbersPromise = webdriver.promise.filter(numbersPromise, (element: number, type: any, index: number, arr: number[]) => { + return true; + }, this); + + numbersPromise = webdriver.promise.map([1, 2, 3], (el: number, type: any, index: number, arr: number[]) => { + return true; + }); + numbersPromise = webdriver.promise.map([1, 2, 3], (el: number, type: any, index: number, arr: number[]) => { + return true; + }, this); + numbersPromise = webdriver.promise.map(numbersPromise, (el: number, type: any, index: number, arr: number[]) => { + return true; + }); + numbersPromise = webdriver.promise.map(numbersPromise, (el: number, type: any, index: number, arr: number[]) => { + return true; + }, this); + + let flow: webdriver.promise.ControlFlow = webdriver.promise.controlFlow(); + + stringPromise = webdriver.promise.createFlow((newFlow: webdriver.promise.ControlFlow) => 'ABC'); + + let deferred: webdriver.promise.Deferred; + deferred = webdriver.promise.defer(); + deferred = webdriver.promise.defer(); + + stringPromise = deferred.promise; + + deferred.fulfill('ABC'); + deferred.reject('error'); + + voidPromise = webdriver.promise.delayed(123); + + voidPromise = webdriver.promise.fulfilled(); + stringPromise = webdriver.promise.fulfilled('abc'); + + stringPromise = webdriver.promise.fullyResolved('abc'); + + let bool: boolean = webdriver.promise.isGenerator(() => {}); + let isPromise: boolean = webdriver.promise.isPromise('ABC'); + + stringPromise = webdriver.promise.rejected('{a: 123}'); + + webdriver.promise.setDefaultFlow(new webdriver.promise.ControlFlow()); + + numberPromise = webdriver.promise.when('abc', (value: any) => 123, (err: Error) => 123); +} + +function TestUntilModule() { + let driver: webdriver.WebDriver = new webdriver.Builder(). + withCapabilities(webdriver.Capabilities.chrome()). + build(); + + let conditionB: webdriver.Condition = new webdriver.Condition('message', (driver: webdriver.WebDriver) => true); + let conditionBBase: webdriver.Condition = conditionB; + let conditionWebElement: webdriver.WebElementCondition; + let conditionWebElements: webdriver.Condition; + + conditionB = webdriver.until.ableToSwitchToFrame(5); + let conditionAlert: webdriver.Condition = webdriver.until.alertIsPresent(); + let el: webdriver.WebElement = driver.findElement(webdriver.By.id('id')); + conditionB = webdriver.until.stalenessOf(el); + conditionB = webdriver.until.titleContains('text'); + conditionB = webdriver.until.titleIs('text'); + conditionB = webdriver.until.titleMatches(/text/); + conditionB = webdriver.until.urlContains('text'); + conditionB = webdriver.until.urlIs('text'); + conditionB = webdriver.until.urlMatches(/text/); + + conditionWebElement = webdriver.until.elementIsDisabled(el); + conditionWebElement = webdriver.until.elementIsEnabled(el); + conditionWebElement = webdriver.until.elementIsNotSelected(el); + conditionWebElement = webdriver.until.elementIsNotVisible(el); + conditionWebElement = webdriver.until.elementIsSelected(el); + conditionWebElement = webdriver.until.elementIsVisible(el); + conditionWebElement = webdriver.until.elementLocated(webdriver.By.id('id')); + conditionWebElement = webdriver.until.elementTextContains(el, 'text'); + conditionWebElement = webdriver.until.elementTextIs(el, 'text'); + conditionWebElement = webdriver.until.elementTextMatches(el, /text/); + conditionWebElements = webdriver.until.elementsLocated(webdriver.By.className('class')); +} + +function TestControlFlow() { + let flow: webdriver.promise.ControlFlow; + flow = new webdriver.promise.ControlFlow(); + + let emitter: webdriver.EventEmitter = flow; + + let eventType: string; + + eventType = webdriver.promise.ControlFlow.EventType.IDLE; + eventType = webdriver.promise.ControlFlow.EventType.RESET; + eventType = webdriver.promise.ControlFlow.EventType.SCHEDULE_TASK; + eventType = webdriver.promise.ControlFlow.EventType.UNCAUGHT_EXCEPTION; + + let stringPromise: webdriver.promise.Promise; + stringPromise = flow.execute(() => 'value'); + stringPromise = flow.execute(() => stringPromise); + stringPromise = flow.execute(() => stringPromise, 'Description'); + + let schedule: string; + schedule = flow.toString(); + schedule = flow.getSchedule(); + schedule = flow.getSchedule(true); + + flow.reset(); + + let voidPromise: webdriver.promise.Promise = flow.timeout(123); + voidPromise = flow.timeout(123, 'Description'); + + stringPromise = flow.wait(stringPromise); + + voidPromise = flow.wait(() => true); + voidPromise = flow.wait(() => true, 123); + voidPromise = flow.wait(() => stringPromise, 123, 'Timeout Message'); +} + +function TestDeferred() { + let deferred: webdriver.promise.Deferred; + + deferred = new webdriver.promise.Deferred(); + deferred = new webdriver.promise.Deferred(new webdriver.promise.ControlFlow()); + + let promise: webdriver.promise.Promise = deferred.promise; + + deferred.errback(new Error('Error')); + deferred.errback('Error'); + deferred.fulfill('abc'); + deferred.reject(new Error('Error')); + deferred.reject('Error'); + deferred.removeAll(); +} + +declare const controlFlow: webdriver.promise.ControlFlow; + +function TestPromiseClass() { + let promise: webdriver.promise.Promise; + promise = new webdriver.promise.Promise((resolve, reject) => { + resolve(""); + resolve(Promise.resolve("")); + reject(new Error()); + }, controlFlow); + + promise = promise.then(); + promise = promise.then((a: string) => 'cde'); + // tslint:disable-next-line void-return (need `--strictNullChecks` to change `void` to `undefined`) + const promiseOrVoid: webdriver.promise.Promise = promise.then((a: string) => 'cde', (e: any) => {}); + const promiseOrNumber: webdriver.promise.Promise = promise.then((a: string) => 'cde', (e: any) => 123); +} + +function TestThenableClass() { + // TODO: this doesn't test the Thenable class, it uses a Promise! + let thenable: webdriver.promise.Promise = new webdriver.promise.Promise((resolve, reject) => { + resolve('a'); + }); + + thenable = thenable.then((a: string) => 'cde'); + // tslint:disable-next-line void-return (need `--strictNullChecks` to change `void` to `undefined`) + const thenableOrVoid: webdriver.promise.Promise = thenable.then((a: string) => 'cde', (e: any) => {}); + const thenableOrNumber: webdriver.promise.Promise = thenable.then((a: string) => 'cde', (e: any) => 123); +} + +async function TestAsyncAwaitable() { + let thenable: webdriver.promise.Promise = new webdriver.promise.Promise((resolve, reject) => resolve('foo')); + let str: string = await thenable; +} + +function TestPromiseManagerFlag() { + webdriver.promise.USE_PROMISE_MANAGER = false; +} diff --git a/types/selenium-webdriver/v3/test/remote.ts b/types/selenium-webdriver/v3/test/remote.ts new file mode 100644 index 0000000000..014fd33af4 --- /dev/null +++ b/types/selenium-webdriver/v3/test/remote.ts @@ -0,0 +1,29 @@ +import * as remote from "selenium-webdriver/remote"; +import * as webdriver from "selenium-webdriver"; + +function TestRemoteFileDetector() { + const driver: webdriver.WebDriver = new webdriver.Builder() + .withCapabilities(webdriver.Capabilities.chrome()) + .build(); + + const fileDetector: remote.FileDetector = new remote.FileDetector(); + fileDetector.handleFile(driver, 'path/to/file').then((path: string) => { /* empty */ }); +} + +function TestSeleniumServer() { + const pathToJar = '/path/to/jar'; + const seleniumServer: remote.SeleniumServer = new remote.SeleniumServer(pathToJar); +} + +function TestSeleniumServerOptions() { + const pathToJar = '/path/to/jar'; + const options: remote.SeleniumServer.Options = { + loopback: false, + port: 4444, + args: ['--testArg'], + jvmArgs: ['--testJvmArg'], + env: {test1: 'test1', test2: 'test2'}, + stdio: 'inherit' + } + const seleniumServer: remote.SeleniumServer = new remote.SeleniumServer(pathToJar, options); +} diff --git a/types/selenium-webdriver/test/testing.ts b/types/selenium-webdriver/v3/test/testing.ts similarity index 100% rename from types/selenium-webdriver/test/testing.ts rename to types/selenium-webdriver/v3/test/testing.ts diff --git a/types/selenium-webdriver/testing.d.ts b/types/selenium-webdriver/v3/testing.d.ts similarity index 100% rename from types/selenium-webdriver/testing.d.ts rename to types/selenium-webdriver/v3/testing.d.ts diff --git a/types/selenium-webdriver/v3/tsconfig.json b/types/selenium-webdriver/v3/tsconfig.json new file mode 100644 index 0000000000..da785a6bf5 --- /dev/null +++ b/types/selenium-webdriver/v3/tsconfig.json @@ -0,0 +1,45 @@ +{ + "compilerOptions": { + "module": "commonjs", + "target": "es6", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": false, + "strictNullChecks": false, + "strictFunctionTypes": false, + "baseUrl": "../../", + "typeRoots": [ + "../../" + ], + "paths": { + "selenium-webdriver": [ + "selenium-webdriver/v3" + ], + "selenium-webdriver/*": [ + "selenium-webdriver/v3/*" + ] + }, + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "chrome.d.ts", + "edge.d.ts", + "firefox.d.ts", + "http.d.ts", + "ie.d.ts", + "opera.d.ts", + "remote.d.ts", + "safari.d.ts", + "testing.d.ts", + "test/index.ts", + "test/chrome.ts", + "test/firefox.ts", + "test/remote.ts", + "test/testing.ts" + ] +} \ No newline at end of file diff --git a/types/selenium-webdriver/v3/tslint.json b/types/selenium-webdriver/v3/tslint.json new file mode 100644 index 0000000000..5ae3225834 --- /dev/null +++ b/types/selenium-webdriver/v3/tslint.json @@ -0,0 +1,22 @@ +{ + "extends": "dtslint/dt.json", + "rules": { + // TODOs + "align": false, + "ban-types": false, + "callable-types": false, + "interface-name": [false], + "jsdoc-format": false, + "no-empty-interface": false, + "no-inferrable-types": false, + "no-any-union": false, + "no-redundant-jsdoc": false, + "no-redundant-jsdoc-2": false, + "no-redundant-undefined": false, + "no-unnecessary-class": false, + "no-unnecessary-generics": false, + "prefer-const": false, + "semicolon": false, + "unified-signatures": false + } +}