1 | // Copyright 2013 Selenium committers |
2 | // Copyright 2013 Software Freedom Conservancy |
3 | // |
4 | // Licensed under the Apache License, Version 2.0 (the "License"); |
5 | // you may not use this file except in compliance with the License. |
6 | // You may obtain a copy of the License at |
7 | // |
8 | // http://www.apache.org/licenses/LICENSE-2.0 |
9 | // |
10 | // Unless required by applicable law or agreed to in writing, software |
11 | // distributed under the License is distributed on an "AS IS" BASIS, |
12 | // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
13 | // See the License for the specific language governing permissions and |
14 | // limitations under the License. |
15 | |
16 | 'use strict'; |
17 | |
18 | var fs = require('fs'), |
19 | util = require('util'); |
20 | |
21 | var webdriver = require('./index'), |
22 | executors = require('./executors'), |
23 | io = require('./io'), |
24 | portprober = require('./net/portprober'), |
25 | remote = require('./remote'); |
26 | |
27 | |
28 | /** |
29 | * Name of the ChromeDriver executable. |
30 | * @type {string} |
31 | * @const |
32 | */ |
33 | var CHROMEDRIVER_EXE = |
34 | process.platform === 'win32' ? 'chromedriver.exe' : 'chromedriver'; |
35 | |
36 | |
37 | /** |
38 | * Creates {@link remote.DriverService} instances that manage a ChromeDriver |
39 | * server. |
40 | * @param {string=} opt_exe Path to the server executable to use. If omitted, |
41 | * the builder will attempt to locate the chromedriver on the current |
42 | * PATH. |
43 | * @throws {Error} If provided executable does not exist, or the chromedriver |
44 | * cannot be found on the PATH. |
45 | * @constructor |
46 | */ |
47 | var ServiceBuilder = function(opt_exe) { |
48 | /** @private {string} */ |
49 | this.exe_ = opt_exe || io.findInPath(CHROMEDRIVER_EXE, true); |
50 | if (!this.exe_) { |
51 | throw Error( |
52 | 'The ChromeDriver could not be found on the current PATH. Please ' + |
53 | 'download the latest version of the ChromeDriver from ' + |
54 | 'http://chromedriver.storage.googleapis.com/index.html and ensure ' + |
55 | 'it can be found on your PATH.'); |
56 | } |
57 | |
58 | if (!fs.existsSync(this.exe_)) { |
59 | throw Error('File does not exist: ' + this.exe_); |
60 | } |
61 | |
62 | /** @private {!Array.<string>} */ |
63 | this.args_ = []; |
64 | this.stdio_ = 'ignore'; |
65 | }; |
66 | |
67 | |
68 | /** @private {number} */ |
69 | ServiceBuilder.prototype.port_ = 0; |
70 | |
71 | |
72 | /** @private {(string|!Array.<string|number|!Stream|null|undefined>)} */ |
73 | ServiceBuilder.prototype.stdio_ = 'ignore'; |
74 | |
75 | |
76 | /** @private {Object.<string, string>} */ |
77 | ServiceBuilder.prototype.env_ = null; |
78 | |
79 | |
80 | /** |
81 | * Sets the port to start the ChromeDriver on. |
82 | * @param {number} port The port to use, or 0 for any free port. |
83 | * @return {!ServiceBuilder} A self reference. |
84 | * @throws {Error} If the port is invalid. |
85 | */ |
86 | ServiceBuilder.prototype.usingPort = function(port) { |
87 | if (port < 0) { |
88 | throw Error('port must be >= 0: ' + port); |
89 | } |
90 | this.port_ = port; |
91 | return this; |
92 | }; |
93 | |
94 | |
95 | /** |
96 | * Sets the path of the log file the driver should log to. If a log file is |
97 | * not specified, the driver will log to stderr. |
98 | * @param {string} path Path of the log file to use. |
99 | * @return {!ServiceBuilder} A self reference. |
100 | */ |
101 | ServiceBuilder.prototype.loggingTo = function(path) { |
102 | this.args_.push('--log-path=' + path); |
103 | return this; |
104 | }; |
105 | |
106 | |
107 | /** |
108 | * Enables verbose logging. |
109 | * @return {!ServiceBuilder} A self reference. |
110 | */ |
111 | ServiceBuilder.prototype.enableVerboseLogging = function() { |
112 | this.args_.push('--verbose'); |
113 | return this; |
114 | }; |
115 | |
116 | |
117 | /** |
118 | * Sets the number of threads the driver should use to manage HTTP requests. |
119 | * By default, the driver will use 4 threads. |
120 | * @param {number} n The number of threads to use. |
121 | * @return {!ServiceBuilder} A self reference. |
122 | */ |
123 | ServiceBuilder.prototype.setNumHttpThreads = function(n) { |
124 | this.args_.push('--http-threads=' + n); |
125 | return this; |
126 | }; |
127 | |
128 | |
129 | /** |
130 | * Sets the base path for WebDriver REST commands (e.g. "/wd/hub"). |
131 | * By default, the driver will accept commands relative to "/". |
132 | * @param {string} path The base path to use. |
133 | * @return {!ServiceBuilder} A self reference. |
134 | */ |
135 | ServiceBuilder.prototype.setUrlBasePath = function(path) { |
136 | this.args_.push('--url-base=' + path); |
137 | return this; |
138 | }; |
139 | |
140 | |
141 | /** |
142 | * Defines the stdio configuration for the driver service. See |
143 | * {@code child_process.spawn} for more information. |
144 | * @param {(string|!Array.<string|number|!Stream|null|undefined>)} config The |
145 | * configuration to use. |
146 | * @return {!ServiceBuilder} A self reference. |
147 | */ |
148 | ServiceBuilder.prototype.setStdio = function(config) { |
149 | this.stdio_ = config; |
150 | return this; |
151 | }; |
152 | |
153 | |
154 | /** |
155 | * Defines the environment to start the server under. This settings will be |
156 | * inherited by every browser session started by the server. |
157 | * @param {!Object.<string, string>} env The environment to use. |
158 | * @return {!ServiceBuilder} A self reference. |
159 | */ |
160 | ServiceBuilder.prototype.withEnvironment = function(env) { |
161 | this.env_ = env; |
162 | return this; |
163 | }; |
164 | |
165 | |
166 | /** |
167 | * Creates a new DriverService using this instance's current configuration. |
168 | * @return {remote.DriverService} A new driver service using this instance's |
169 | * current configuration. |
170 | * @throws {Error} If the driver exectuable was not specified and a default |
171 | * could not be found on the current PATH. |
172 | */ |
173 | ServiceBuilder.prototype.build = function() { |
174 | var port = this.port_ || portprober.findFreePort(); |
175 | var args = this.args_.concat(); // Defensive copy. |
176 | |
177 | return new remote.DriverService(this.exe_, { |
178 | port: port, |
179 | args: webdriver.promise.when(port, function(port) { |
180 | return args.concat('--port=' + port); |
181 | }), |
182 | env: this.env_, |
183 | stdio: this.stdio_ |
184 | }); |
185 | }; |
186 | |
187 | |
188 | /** @type {remote.DriverService} */ |
189 | var defaultService = null; |
190 | |
191 | |
192 | /** |
193 | * Sets the default service to use for new ChromeDriver instances. |
194 | * @param {!remote.DriverService} service The service to use. |
195 | * @throws {Error} If the default service is currently running. |
196 | */ |
197 | function setDefaultService(service) { |
198 | if (defaultService && defaultService.isRunning()) { |
199 | throw Error( |
200 | 'The previously configured ChromeDriver service is still running. ' + |
201 | 'You must shut it down before you may adjust its configuration.'); |
202 | } |
203 | defaultService = service; |
204 | } |
205 | |
206 | |
207 | /** |
208 | * Returns the default ChromeDriver service. If such a service has not been |
209 | * configured, one will be constructed using the default configuration for |
210 | * a ChromeDriver executable found on the system PATH. |
211 | * @return {!remote.DriverService} The default ChromeDriver service. |
212 | */ |
213 | function getDefaultService() { |
214 | if (!defaultService) { |
215 | defaultService = new ServiceBuilder().build(); |
216 | } |
217 | return defaultService; |
218 | } |
219 | |
220 | |
221 | /** |
222 | * @type {string} |
223 | * @const |
224 | */ |
225 | var OPTIONS_CAPABILITY_KEY = 'chromeOptions'; |
226 | |
227 | |
228 | /** |
229 | * Class for managing ChromeDriver specific options. |
230 | * @constructor |
231 | */ |
232 | var Options = function() { |
233 | /** @private {!Array.<string>} */ |
234 | this.args_ = []; |
235 | |
236 | /** @private {!Array.<(string|!Buffer)>} */ |
237 | this.extensions_ = []; |
238 | }; |
239 | |
240 | |
241 | /** |
242 | * Extracts the ChromeDriver specific options from the given capabilities |
243 | * object. |
244 | * @param {!webdriver.Capabilities} capabilities The capabilities object. |
245 | * @return {!Options} The ChromeDriver options. |
246 | */ |
247 | Options.fromCapabilities = function(capabilities) { |
248 | var options = new Options(); |
249 | |
250 | var o = capabilities.get(OPTIONS_CAPABILITY_KEY); |
251 | if (o instanceof Options) { |
252 | options = o; |
253 | } else if (o) { |
254 | options. |
255 | addArguments(o.args || []). |
256 | addExtensions(o.extensions || []). |
257 | detachDriver(!!o.detach). |
258 | setChromeBinaryPath(o.binary). |
259 | setChromeLogFile(o.logFile). |
260 | setLocalState(o.localState). |
261 | setUserPreferences(o.prefs); |
262 | } |
263 | |
264 | if (capabilities.has(webdriver.Capability.PROXY)) { |
265 | options.setProxy(capabilities.get(webdriver.Capability.PROXY)); |
266 | } |
267 | |
268 | if (capabilities.has(webdriver.Capability.LOGGING_PREFS)) { |
269 | options.setLoggingPreferences( |
270 | capabilities.get(webdriver.Capability.LOGGING_PREFS)); |
271 | } |
272 | |
273 | return options; |
274 | }; |
275 | |
276 | |
277 | /** |
278 | * Add additional command line arguments to use when launching the Chrome |
279 | * browser. Each argument may be specified with or without the "--" prefix |
280 | * (e.g. "--foo" and "foo"). Arguments with an associated value should be |
281 | * delimited by an "=": "foo=bar". |
282 | * @param {...(string|!Array.<string>)} var_args The arguments to add. |
283 | * @return {!Options} A self reference. |
284 | */ |
285 | Options.prototype.addArguments = function(var_args) { |
286 | this.args_ = this.args_.concat.apply(this.args_, arguments); |
287 | return this; |
288 | }; |
289 | |
290 | |
291 | /** |
292 | * Add additional extensions to install when launching Chrome. Each extension |
293 | * should be specified as the path to the packed CRX file, or a Buffer for an |
294 | * extension. |
295 | * @param {...(string|!Buffer|!Array.<(string|!Buffer)>)} var_args The |
296 | * extensions to add. |
297 | * @return {!Options} A self reference. |
298 | */ |
299 | Options.prototype.addExtensions = function(var_args) { |
300 | this.extensions_ = this.extensions_.concat.apply( |
301 | this.extensions_, arguments); |
302 | return this; |
303 | }; |
304 | |
305 | |
306 | /** |
307 | * Sets the path to the Chrome binary to use. On Mac OS X, this path should |
308 | * reference the actual Chrome executable, not just the application binary |
309 | * (e.g. "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"). |
310 | * |
311 | * The binary path be absolute or relative to the chromedriver server |
312 | * executable, but it must exist on the machine that will launch Chrome. |
313 | * |
314 | * @param {string} path The path to the Chrome binary to use. |
315 | * @return {!Options} A self reference. |
316 | */ |
317 | Options.prototype.setChromeBinaryPath = function(path) { |
318 | this.binary_ = path; |
319 | return this; |
320 | }; |
321 | |
322 | |
323 | /** |
324 | * Sets whether to leave the started Chrome browser running if the controlling |
325 | * ChromeDriver service is killed before {@link webdriver.WebDriver#quit()} is |
326 | * called. |
327 | * @param {boolean} detach Whether to leave the browser running if the |
328 | * chromedriver service is killed before the session. |
329 | * @return {!Options} A self reference. |
330 | */ |
331 | Options.prototype.detachDriver = function(detach) { |
332 | this.detach_ = detach; |
333 | return this; |
334 | }; |
335 | |
336 | |
337 | /** |
338 | * Sets the user preferences for Chrome's user profile. See the "Preferences" |
339 | * file in Chrome's user data directory for examples. |
340 | * @param {!Object} prefs Dictionary of user preferences to use. |
341 | * @return {!Options} A self reference. |
342 | */ |
343 | Options.prototype.setUserPreferences = function(prefs) { |
344 | this.prefs_ = prefs; |
345 | return this; |
346 | }; |
347 | |
348 | |
349 | /** |
350 | * Sets the logging preferences for the new session. |
351 | * @param {!webdriver.logging.Preferences} prefs The logging preferences. |
352 | * @return {!Options} A self reference. |
353 | */ |
354 | Options.prototype.setLoggingPreferences = function(prefs) { |
355 | this.logPrefs_ = prefs; |
356 | return this; |
357 | }; |
358 | |
359 | |
360 | /** |
361 | * Sets preferences for the "Local State" file in Chrome's user data |
362 | * directory. |
363 | * @param {!Object} state Dictionary of local state preferences. |
364 | * @return {!Options} A self reference. |
365 | */ |
366 | Options.prototype.setLocalState = function(state) { |
367 | this.localState_ = state; |
368 | return this; |
369 | }; |
370 | |
371 | |
372 | /** |
373 | * Sets the path to Chrome's log file. This path should exist on the machine |
374 | * that will launch Chrome. |
375 | * @param {string} path Path to the log file to use. |
376 | * @return {!Options} A self reference. |
377 | */ |
378 | Options.prototype.setChromeLogFile = function(path) { |
379 | this.logFile_ = path; |
380 | return this; |
381 | }; |
382 | |
383 | |
384 | /** |
385 | * Sets the proxy settings for the new session. |
386 | * @param {ProxyConfig} proxy The proxy configuration to use. |
387 | * @return {!Options} A self reference. |
388 | */ |
389 | Options.prototype.setProxy = function(proxy) { |
390 | this.proxy_ = proxy; |
391 | return this; |
392 | }; |
393 | |
394 | |
395 | /** |
396 | * Converts this options instance to a {@link webdriver.Capabilities} object. |
397 | * @param {webdriver.Capabilities=} opt_capabilities The capabilities to merge |
398 | * these options into, if any. |
399 | * @return {!webdriver.Capabilities} The capabilities. |
400 | */ |
401 | Options.prototype.toCapabilities = function(opt_capabilities) { |
402 | var capabilities = opt_capabilities || webdriver.Capabilities.chrome(); |
403 | capabilities. |
404 | set(webdriver.Capability.PROXY, this.proxy_). |
405 | set(webdriver.Capability.LOGGING_PREFS, this.logPrefs_). |
406 | set(OPTIONS_CAPABILITY_KEY, this); |
407 | return capabilities; |
408 | }; |
409 | |
410 | |
411 | /** |
412 | * Converts this instance to its JSON wire protocol representation. Note this |
413 | * function is an implementation not intended for general use. |
414 | * @return {{args: !Array.<string>, |
415 | * binary: (string|undefined), |
416 | * detach: boolean, |
417 | * extensions: !Array.<string>, |
418 | * localState: (Object|undefined), |
419 | * logFile: (string|undefined), |
420 | * prefs: (Object|undefined)}} The JSON wire protocol representation |
421 | * of this instance. |
422 | */ |
423 | Options.prototype.toJSON = function() { |
424 | return { |
425 | args: this.args_, |
426 | binary: this.binary_, |
427 | detach: !!this.detach_, |
428 | extensions: this.extensions_.map(function(extension) { |
429 | if (Buffer.isBuffer(extension)) { |
430 | return extension.toString('base64'); |
431 | } |
432 | return fs.readFileSync(extension, 'base64'); |
433 | }), |
434 | localState: this.localState_, |
435 | logFile: this.logFile_, |
436 | prefs: this.prefs_ |
437 | }; |
438 | }; |
439 | |
440 | |
441 | /** |
442 | * Creates a new ChromeDriver session. |
443 | * @param {(webdriver.Capabilities|Options)=} opt_options The session options. |
444 | * @param {remote.DriverService=} opt_service The session to use; will use |
445 | * the {@link getDefaultService default service} by default. |
446 | * @return {!webdriver.WebDriver} A new WebDriver instance. |
447 | */ |
448 | function createDriver(opt_options, opt_service) { |
449 | var service = opt_service || getDefaultService(); |
450 | var executor = executors.createExecutor(service.start()); |
451 | |
452 | var options = opt_options || new Options(); |
453 | if (opt_options instanceof webdriver.Capabilities) { |
454 | // Extract the Chrome-specific options so we do not send unnecessary |
455 | // data across the wire. |
456 | options = Options.fromCapabilities(options); |
457 | } |
458 | |
459 | return webdriver.WebDriver.createSession( |
460 | executor, options.toCapabilities()); |
461 | } |
462 | |
463 | |
464 | |
465 | // PUBLIC API |
466 | |
467 | |
468 | exports.ServiceBuilder = ServiceBuilder; |
469 | exports.Options = Options; |
470 | exports.createDriver = createDriver; |
471 | exports.getDefaultService = getDefaultService; |
472 | exports.setDefaultService = setDefaultService; |