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