# 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 |
95 | var url = require('url'),
96 | util = require('util');
97 |
98 | var 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 | */
113 | var 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 | */
136 | Options.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 | */
152 | Options.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 | */
166 | Options.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 | */
178 | Options.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 | */
189 | Options.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 | */
219 | var 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 | };
276 | util.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 | */
284 | Driver.prototype.setFileDetector = function() {
285 | };
286 |
287 |
288 | /** @override */
289 | Driver.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 |
304 | exports.Binary = Binary;
305 | exports.Driver = Driver;
306 | exports.Options = Options;
307 | exports.Profile = Profile;