firefox/index.js

1// Copyright 2014 Selenium committers
2// Copyright 2014 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/**
17 * @fileoverview Defines the {@linkplain Driver WebDriver} client for Firefox.
18 * Each FirefoxDriver instance will be created with an anonymous profile,
19 * ensuring browser historys do not share session data (cookies, history, cache,
20 * offline storage, etc.)
21 *
22 * __Customizing the Firefox Profile__
23 *
24 * The {@link Profile} class may be used to configure the browser profile used
25 * with WebDriver, with functions to install additional
26 * {@linkplain Profile#addExtension extensions}, configure browser
27 * {@linkplain Profile#setPreference preferences}, and more. For example, you
28 * may wish to include Firebug:
29 *
30 * var firefox = require('selenium-webdriver/firefox');
31 *
32 * var profile = new firefox.Profile();
33 * profile.addExtension('/path/to/firebug.xpi');
34 * profile.setPreference('extensions.firebug.showChromeErrors', true);
35 *
36 * var options = new firefox.Options().setProfile(profile);
37 * var driver = new firefox.Driver(options);
38 *
39 * The {@link Profile} class may also be used to configure WebDriver based on a
40 * pre-existing browser profile:
41 *
42 * var profile = new firefox.Profile(
43 * '/usr/local/home/bob/.mozilla/firefox/3fgog75h.testing');
44 * var options = new firefox.Options().setProfile(profile);
45 * var driver = new firefox.Driver(options);
46 *
47 * The FirefoxDriver will _never_ modify a pre-existing profile; instead it will
48 * create a copy for it to modify. By extension, there are certain browser
49 * preferences that are required for WebDriver to function properly and they
50 * will always be overwritten.
51 *
52 * __Using a Custom Firefox Binary__
53 *
54 * On Windows and OSX, the FirefoxDriver will search for Firefox in its
55 * default installation location:
56 *
57 * * Windows: C:\Program Files and C:\Program Files (x86).
58 * * Mac OS X: /Applications/Firefox.app
59 *
60 * For Linux, Firefox will be located on the PATH: `$(where firefox)`.
61 *
62 * You can configure WebDriver to start use a custom Firefox installation with
63 * the {@link Binary} class:
64 *
65 * var firefox = require('selenium-webdriver/firefox');
66 * var binary = new firefox.Binary('/my/firefox/install/dir/firefox-bin');
67 * var options = new firefox.Options().setBinary(binary);
68 * var driver = new firefox.Driver(options);
69 *
70 * __Remote Testing__
71 *
72 * You may customize the Firefox binary and profile when running against a
73 * remote Selenium server. Your custom profile will be packaged as a zip and
74 * transfered to the remote host for use. The profile will be transferred
75 * _once for each new session_. The performance impact should be minimal if
76 * you've only configured a few extra browser preferences. If you have a large
77 * profile with several extensions, you should consider installing it on the
78 * remote host and defining its path via the {@link Options} class. Custom
79 * binaries are never copied to remote machines and must be referenced by
80 * installation path.
81 *
82 * var options = new firefox.Options()
83 * .setProfile('/profile/path/on/remote/host')
84 * .setBinary('/install/dir/on/remote/host/firefox-bin');
85 *
86 * var driver = new (require('selenium-webdriver')).Builder()
87 * .forBrowser('firefox')
88 * .usingServer('http://127.0.0.1:4444/wd/hub')
89 * .setFirefoxOptions(options)
90 * .build();
91 */
92
93'use strict';
94
95var url = require('url'),
96 util = require('util');
97
98var Binary = require('./binary').Binary,
99 Profile = require('./profile').Profile,
100 decodeProfile = require('./profile').decode,
101 webdriver = require('..'),
102 executors = require('../executors'),
103 httpUtil = require('../http/util'),
104 io = require('../io'),
105 net = require('../net'),
106 portprober = require('../net/portprober');
107
108
109/**
110 * Configuration options for the FirefoxDriver.
111 * @constructor
112 */
113var Options = function() {
114 /** @private {Profile} */
115 this.profile_ = null;
116
117 /** @private {Binary} */
118 this.binary_ = null;
119
120 /** @private {webdriver.logging.Preferences} */
121 this.logPrefs_ = null;
122
123 /** @private {webdriver.ProxyConfig} */
124 this.proxy_ = null;
125};
126
127
128/**
129 * Sets the profile to use. The profile may be specified as a
130 * {@link Profile} object or as the path to an existing Firefox profile to use
131 * as a template.
132 *
133 * @param {(string|!Profile)} profile The profile to use.
134 * @return {!Options} A self reference.
135 */
136Options.prototype.setProfile = function(profile) {
137 if (typeof profile === 'string') {
138 profile = new Profile(profile);
139 }
140 this.profile_ = profile;
141 return this;
142};
143
144
145/**
146 * Sets the binary to use. The binary may be specified as the path to a Firefox
147 * executable, or as a {@link Binary} object.
148 *
149 * @param {(string|!Binary)} binary The binary to use.
150 * @return {!Options} A self reference.
151 */
152Options.prototype.setBinary = function(binary) {
153 if (typeof binary === 'string') {
154 binary = new Binary(binary);
155 }
156 this.binary_ = binary;
157 return this;
158};
159
160
161/**
162 * Sets the logging preferences for the new session.
163 * @param {webdriver.logging.Preferences} prefs The logging preferences.
164 * @return {!Options} A self reference.
165 */
166Options.prototype.setLoggingPreferences = function(prefs) {
167 this.logPrefs_ = prefs;
168 return this;
169};
170
171
172/**
173 * Sets the proxy to use.
174 *
175 * @param {webdriver.ProxyConfig} proxy The proxy configuration to use.
176 * @return {!Options} A self reference.
177 */
178Options.prototype.setProxy = function(proxy) {
179 this.proxy_ = proxy;
180 return this;
181};
182
183
184/**
185 * Converts these options to a {@link webdriver.Capabilities} instance.
186 *
187 * @return {!webdriver.Capabilities} A new capabilities object.
188 */
189Options.prototype.toCapabilities = function(opt_remote) {
190 var caps = webdriver.Capabilities.firefox();
191 if (this.logPrefs_) {
192 caps.set(webdriver.Capability.LOGGING_PREFS, this.logPrefs_);
193 }
194 if (this.proxy_) {
195 caps.set(webdriver.Capability.PROXY, this.proxy_);
196 }
197 if (this.binary_) {
198 caps.set('firefox_binary', this.binary_);
199 }
200 if (this.profile_) {
201 caps.set('firefox_profile', this.profile_);
202 }
203 return caps;
204};
205
206
207/**
208 * A WebDriver client for Firefox.
209 *
210 * @param {(Options|webdriver.Capabilities|Object)=} opt_config The
211 * configuration options for this driver, specified as either an
212 * {@link Options} or {@link webdriver.Capabilities}, or as a raw hash
213 * object.
214 * @param {webdriver.promise.ControlFlow=} opt_flow The flow to
215 * schedule commands through. Defaults to the active flow object.
216 * @constructor
217 * @extends {webdriver.WebDriver}
218 */
219var Driver = function(opt_config, opt_flow) {
220 var caps;
221 if (opt_config instanceof Options) {
222 caps = opt_config.toCapabilities();
223 } else {
224 caps = new webdriver.Capabilities(opt_config);
225 }
226
227 var binary = caps.get('firefox_binary') || new Binary();
228 if (typeof binary === 'string') {
229 binary = new Binary(binary);
230 }
231
232 var profile = caps.get('firefox_profile') || new Profile();
233
234 caps.set('firefox_binary', null);
235 caps.set('firefox_profile', null);
236
237 /** @private {?string} */
238 this.profilePath_ = null;
239
240 var self = this;
241 var serverUrl = portprober.findFreePort().then(function(port) {
242 var prepareProfile;
243 if (typeof profile === 'string') {
244 prepareProfile = decodeProfile(profile).then(function(dir) {
245 var profile = new Profile(dir);
246 profile.setPreference('webdriver_firefox_port', port);
247 return profile.writeToDisk();
248 });
249 } else {
250 profile.setPreference('webdriver_firefox_port', port);
251 prepareProfile = profile.writeToDisk();
252 }
253
254 return prepareProfile.then(function(dir) {
255 self.profilePath_ = dir;
256 return binary.launch(dir);
257 }).then(function() {
258 var serverUrl = url.format({
259 protocol: 'http',
260 hostname: net.getLoopbackAddress(),
261 port: port,
262 pathname: '/hub'
263 });
264
265 return httpUtil.waitForServer(serverUrl, 45 * 1000).then(function() {
266 return serverUrl;
267 });
268 });
269 });
270
271 var executor = executors.createExecutor(serverUrl);
272 var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
273
274 webdriver.WebDriver.call(this, driver.getSession(), executor, opt_flow);
275};
276util.inherits(Driver, webdriver.WebDriver);
277
278
279/**
280 * This function is a no-op as file detectors are not supported by this
281 * implementation.
282 * @override
283 */
284Driver.prototype.setFileDetector = function() {
285};
286
287
288/** @override */
289Driver.prototype.quit = function() {
290 return this.call(function() {
291 var self = this;
292 return Driver.super_.prototype.quit.call(this).thenFinally(function() {
293 if (self.profilePath_) {
294 return io.rmDir(self.profilePath_);
295 }
296 });
297 }, this);
298};
299
300
301// PUBLIC API
302
303
304exports.Binary = Binary;
305exports.Driver = Driver;
306exports.Options = Options;
307exports.Profile = Profile;