1 | import * as http from './http';
|
2 | import * as webdriver from './index';
|
3 | import * as remote from './remote';
|
4 |
|
5 | /**
|
6 | * Creates a new WebDriver client for Chrome.
|
7 | *
|
8 | * @extends {webdriver.WebDriver}
|
9 | */
|
10 | export class Driver extends webdriver.WebDriver {
|
11 | /**
|
12 | * Creates a new session with the ChromeDriver.
|
13 | *
|
14 | * @param {(Capabilities|Options)=} opt_config The configuration options.
|
15 | * @param {(remote.DriverService|http.Executor)=} opt_serviceExecutor Either
|
16 | * a DriverService to use for the remote end, or a preconfigured executor
|
17 | * for an externally managed endpoint. If neither is provided, the
|
18 | * {@linkplain ##getDefaultService default service} will be used by
|
19 | * default.
|
20 | * @return {!Driver} A new driver instance.
|
21 | */
|
22 | static createSession(
|
23 | opt_config?: Options|webdriver.CreateSessionCapabilities,
|
24 | opt_service?: remote.DriverService|http.Executor): Driver;
|
25 | }
|
26 |
|
27 | export interface IOptionsValues {
|
28 | args: string[];
|
29 | binary?: string | undefined;
|
30 | detach: boolean;
|
31 | extensions: string[];
|
32 | localState?: any;
|
33 | logFile?: string | undefined;
|
34 | prefs?: any;
|
35 | }
|
36 |
|
37 | export interface IPerfLoggingPrefs {
|
38 | enableNetwork?: boolean | undefined;
|
39 | enablePage?: boolean | undefined;
|
40 | enableTimeline?: boolean | undefined;
|
41 | traceCategories?: string | undefined;
|
42 | bufferUsageReportingInterval?: number | undefined;
|
43 | }
|
44 |
|
45 | /**
|
46 | * Class for managing ChromeDriver specific options.
|
47 | */
|
48 | export class Options extends webdriver.Capabilities {
|
49 | /**
|
50 | * @constructor
|
51 | */
|
52 | constructor();
|
53 |
|
54 | /**
|
55 | * Extracts the ChromeDriver specific options from the given capabilities
|
56 | * object.
|
57 | * @param {!webdriver.Capabilities} capabilities The capabilities object.
|
58 | * {!Options} The ChromeDriver options.
|
59 | */
|
60 | static fromCapabilities(capabilities: webdriver.Capabilities): Options;
|
61 |
|
62 | /**
|
63 | * Add additional command line arguments to use when launching the Chrome
|
64 | * browser. Each argument may be specified with or without the '--' prefix
|
65 | * (e.g. '--foo' and 'foo'). Arguments with an associated value should be
|
66 | * delimited by an '=': 'foo=bar'.
|
67 | * @param {...(string|!Array.<string>)} var_args The arguments to add.
|
68 | * @return {!Options} A self reference.
|
69 | */
|
70 | addArguments(...var_args: string[]): Options;
|
71 |
|
72 | /**
|
73 | * Configures the chromedriver to start Chrome in headless mode.
|
74 | *
|
75 | * > __NOTE:__ Resizing the browser window in headless mode is only supported
|
76 | * > in Chrome 60. Users are encouraged to set an initial window size with
|
77 | * > the {@link #windowSize windowSize({width, height})} option.
|
78 | *
|
79 | * @return {!Options} A self reference.
|
80 | */
|
81 | headless(): Options;
|
82 |
|
83 | /**
|
84 | * Sets the initial window size.
|
85 | *
|
86 | * @param {{width: number, height: number}} size The desired window size.
|
87 | * @return {!Options} A self reference.
|
88 | * @throws {TypeError} if width or height is unspecified, not a number, or
|
89 | * less than or equal to 0.
|
90 | */
|
91 | windowSize(size: {width: number, height: number}): Options;
|
92 |
|
93 | /**
|
94 | * List of Chrome command line switches to exclude that ChromeDriver by
|
95 | * default passes when starting Chrome. Do not prefix switches with '--'.
|
96 | *
|
97 | * @param {...(string|!Array<string>)} var_args The switches to exclude.
|
98 | * @return {!Options} A self reference.
|
99 | */
|
100 | excludeSwitches(...var_args: string[]): Options;
|
101 |
|
102 | /**
|
103 | * Add additional extensions to install when launching Chrome. Each extension
|
104 | * should be specified as the path to the packed CRX file, or a Buffer for an
|
105 | * extension.
|
106 | * @param {...(string|!Buffer|!Array.<(string|!Buffer)>)} var_args The
|
107 | * extensions to add.
|
108 | * @return {!Options} A self reference.
|
109 | */
|
110 | addExtensions(...var_args: any[]): Options;
|
111 |
|
112 | /**
|
113 | * Sets the path to the Chrome binary to use. On Mac OS X, this path should
|
114 | * reference the actual Chrome executable, not just the application binary
|
115 | * (e.g. '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome').
|
116 | *
|
117 | * The binary path be absolute or relative to the chromedriver server
|
118 | * executable, but it must exist on the machine that will launch Chrome.
|
119 | *
|
120 | * @param {string} path The path to the Chrome binary to use.
|
121 | * @return {!Options} A self reference.
|
122 | */
|
123 | setChromeBinaryPath(path: string): Options;
|
124 |
|
125 | /**
|
126 | * Sets whether to leave the started Chrome browser running if the controlling
|
127 | * ChromeDriver service is killed before {@link webdriver.WebDriver#quit()} is
|
128 | * called.
|
129 | * @param {boolean} detach Whether to leave the browser running if the
|
130 | * chromedriver service is killed before the session.
|
131 | * @return {!Options} A self reference.
|
132 | */
|
133 | detachDriver(detach: boolean): Options;
|
134 |
|
135 | /**
|
136 | * Sets the user preferences for Chrome's user profile. See the 'Preferences'
|
137 | * file in Chrome's user data directory for examples.
|
138 | * @param {!Object} prefs Dictionary of user preferences to use.
|
139 | * @return {!Options} A self reference.
|
140 | */
|
141 | setUserPreferences(prefs: any): Options;
|
142 |
|
143 | /**
|
144 | * Sets the performance logging preferences. Options include:
|
145 | *
|
146 | * - `enableNetwork`: Whether or not to collect events from Network domain.
|
147 | * - `enablePage`: Whether or not to collect events from Page domain.
|
148 | * - `enableTimeline`: Whether or not to collect events from Timeline domain.
|
149 | * Note: when tracing is enabled, Timeline domain is implicitly disabled,
|
150 | * unless `enableTimeline` is explicitly set to true.
|
151 | * - `tracingCategories`: A comma-separated string of Chrome tracing
|
152 | * categories for which trace events should be collected. An unspecified or
|
153 | * empty string disables tracing.
|
154 | * - `bufferUsageReportingInterval`: The requested number of milliseconds
|
155 | * between DevTools trace buffer usage events. For example, if 1000, then
|
156 | * once per second, DevTools will report how full the trace buffer is. If
|
157 | * a report indicates the buffer usage is 100%, a warning will be issued.
|
158 | *
|
159 | * @param {{enableNetwork: boolean,
|
160 | * enablePage: boolean,
|
161 | * enableTimeline: boolean,
|
162 | * tracingCategories: string,
|
163 | * bufferUsageReportingInterval: number}} prefs The performance
|
164 | * logging preferences.
|
165 | * @return {!Options} A self reference.
|
166 | */
|
167 | setPerfLoggingPrefs(prefs: IPerfLoggingPrefs): Options;
|
168 |
|
169 | /**
|
170 | * Sets preferences for the 'Local State' file in Chrome's user data
|
171 | * directory.
|
172 | * @param {!Object} state Dictionary of local state preferences.
|
173 | * @return {!Options} A self reference.
|
174 | */
|
175 | setLocalState(state: any): Options;
|
176 |
|
177 | /**
|
178 | * Sets the name of the activity hosting a Chrome-based Android WebView. This
|
179 | * option must be set to connect to an [Android WebView](
|
180 | * https://sites.google.com/a/chromium.org/chromedriver/getting-started/getting-started---android)
|
181 | *
|
182 | * @param {string} name The activity name.
|
183 | * @return {!Options} A self reference.
|
184 | */
|
185 | androidActivity(name: string): Options;
|
186 |
|
187 | /**
|
188 | * Sets the device serial number to connect to via ADB. If not specified, the
|
189 | * ChromeDriver will select an unused device at random. An error will be
|
190 | * returned if all devices already have active sessions.
|
191 | *
|
192 | * @param {string} serial The device serial number to connect to.
|
193 | * @return {!Options} A self reference.
|
194 | */
|
195 | androidDeviceSerial(serial: string): Options;
|
196 |
|
197 | /**
|
198 | * Configures the ChromeDriver to launch Chrome on Android via adb. This
|
199 | * function is shorthand for
|
200 | * {@link #androidPackage options.androidPackage('com.android.chrome')}.
|
201 | * @return {!Options} A self reference.
|
202 | */
|
203 | androidChrome(): Options;
|
204 |
|
205 | /**
|
206 | * Sets the package name of the Chrome or WebView app.
|
207 | *
|
208 | * @param {?string} pkg The package to connect to, or `null` to disable
|
209 | * Android and switch back to using desktop Chrome.
|
210 | * @return {!Options} A self reference.
|
211 | */
|
212 | androidPackage(pkg: string): Options;
|
213 |
|
214 | /**
|
215 | * Sets the process name of the Activity hosting the WebView (as given by
|
216 | * `ps`). If not specified, the process name is assumed to be the same as
|
217 | * {@link #androidPackage}.
|
218 | *
|
219 | * @param {string} processName The main activity name.
|
220 | * @return {!Options} A self reference.
|
221 | */
|
222 | androidProcess(processName: string): Options;
|
223 |
|
224 | /**
|
225 | * Sets whether to connect to an already-running instead of the specified
|
226 | * {@linkplain #androidProcess app} instead of launching the app with a clean
|
227 | * data directory.
|
228 | *
|
229 | * @param {boolean} useRunning Whether to connect to a running instance.
|
230 | * @return {!Options} A self reference.
|
231 | */
|
232 | androidUseRunningApp(useRunning: boolean): Options;
|
233 |
|
234 | /**
|
235 | * Sets the path to Chrome's log file. This path should exist on the machine
|
236 | * that will launch Chrome.
|
237 | * @param {string} path Path to the log file to use.
|
238 | * @return {!Options} A self reference.
|
239 | */
|
240 | setChromeLogFile(path: string): Options;
|
241 |
|
242 | /**
|
243 | * Sets the directory to store Chrome minidumps in. This option is only
|
244 | * supported when ChromeDriver is running on Linux.
|
245 | * @param {string} path The directory path.
|
246 | * @return {!Options} A self reference.
|
247 | */
|
248 | setChromeMinidumpPath(path: string): Options;
|
249 |
|
250 | /**
|
251 | * Configures Chrome to emulate a mobile device. For more information, refer
|
252 | * to the ChromeDriver project page on [mobile emulation][em]. Configuration
|
253 | * options include:
|
254 | *
|
255 | * - `deviceName`: The name of a pre-configured [emulated device][devem]
|
256 | * - `width`: screen width, in pixels
|
257 | * - `height`: screen height, in pixels
|
258 | * - `pixelRatio`: screen pixel ratio
|
259 | *
|
260 | * __Example 1: Using a Pre-configured Device__
|
261 | *
|
262 | * let options = new chrome.Options().setMobileEmulation(
|
263 | * {deviceName: 'Google Nexus 5'});
|
264 | *
|
265 | * let driver = new chrome.Driver(options);
|
266 | *
|
267 | * __Example 2: Using Custom Screen Configuration__
|
268 | *
|
269 | * let options = new chrome.Options().setMobileEmulation({
|
270 | * width: 360,
|
271 | * height: 640,
|
272 | * pixelRatio: 3.0
|
273 | * });
|
274 | *
|
275 | * let driver = new chrome.Driver(options);
|
276 | *
|
277 | *
|
278 | * [em]: https://sites.google.com/a/chromium.org/chromedriver/mobile-emulation
|
279 | * [devem]: https://developer.chrome.com/devtools/docs/device-mode
|
280 | *
|
281 | * @param {?({deviceName: string}|
|
282 | * {width: number, height: number, pixelRatio: number})} config The
|
283 | * mobile emulation configuration, or `null` to disable emulation.
|
284 | * @return {!Options} A self reference.
|
285 | */
|
286 | setMobileEmulation(config: any): Options;
|
287 | }
|
288 |
|
289 | /**
|
290 | * Creates {@link remote.DriverService} instances that manage a ChromeDriver
|
291 | * server.
|
292 | */
|
293 | export class ServiceBuilder extends remote.DriverService.Builder {
|
294 | /**
|
295 | * @param {string=} opt_exe Path to the server executable to use. If omitted,
|
296 | * the builder will attempt to locate the chromedriver on the current
|
297 | * PATH.
|
298 | * @throws {Error} If provided executable does not exist, or the chromedriver
|
299 | * cannot be found on the PATH.
|
300 | * @constructor
|
301 | */
|
302 | constructor(opt_exe?: string);
|
303 |
|
304 | /**
|
305 | * Sets which port adb is listening to. _The ChromeDriver will connect to adb
|
306 | * if an { Options#androidPackage Android session} is requested, but
|
307 | * adb **must** be started beforehand._
|
308 | *
|
309 | * number} port Which port adb is running on.
{ |
310 | * {!ServiceBuilder} A self reference.
|
311 | */
|
312 | setAdbPort(port: number): this;
|
313 |
|
314 | /**
|
315 | * Sets the path of the log file the driver should log to. If a log file is
|
316 | * not specified, the driver will log to stderr.
|
317 | * @param {string} path Path of the log file to use.
|
318 | * @return {!ServiceBuilder} A self reference.
|
319 | */
|
320 | loggingTo(path: string): this;
|
321 |
|
322 | /**
|
323 | * Enables verbose logging.
|
324 | * @return {!ServiceBuilder} A self reference.
|
325 | */
|
326 | enableVerboseLogging(): this;
|
327 |
|
328 | /**
|
329 | * Sets the number of threads the driver should use to manage HTTP requests.
|
330 | * By default, the driver will use 4 threads.
|
331 | * @param {number} n The number of threads to use.
|
332 | * @return {!ServiceBuilder} A self reference.
|
333 | */
|
334 | setNumHttpThreads(n: number): this;
|
335 | }
|
336 |
|
337 | /**
|
338 | * Returns the default ChromeDriver service. If such a service has not been
|
339 | * configured, one will be constructed using the default configuration for
|
340 | * a ChromeDriver executable found on the system PATH.
|
341 | * @return {!remote.DriverService} The default ChromeDriver service.
|
342 | */
|
343 | export function getDefaultService(): remote.DriverService;
|
344 |
|
345 | /**
|
346 | * Sets the default service to use for new ChromeDriver instances.
|
347 | * @param {!remote.DriverService} service The service to use.
|
348 | * @throws {Error} If the default service is currently running.
|
349 | */
|
350 | export function setDefaultService(service: remote.DriverService): void;
|