Path: blob/trunk/javascript/selenium-webdriver/firefox.js
3220 views
// Licensed to the Software Freedom Conservancy (SFC) under one1// or more contributor license agreements. See the NOTICE file2// distributed with this work for additional information3// regarding copyright ownership. The SFC licenses this file4// to you under the Apache License, Version 2.0 (the5// "License"); you may not use this file except in compliance6// with the License. You may obtain a copy of the License at7//8// http://www.apache.org/licenses/LICENSE-2.09//10// Unless required by applicable law or agreed to in writing,11// software distributed under the License is distributed on an12// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY13// KIND, either express or implied. See the License for the14// specific language governing permissions and limitations15// under the License.1617/**18* @fileoverview Defines the {@linkplain Driver WebDriver} client for Firefox.19* Before using this module, you must download the latest20* [geckodriver release] and ensure it can be found on your system [PATH].21*22* Each FirefoxDriver instance will be created with an anonymous profile,23* ensuring browser historys do not share session data (cookies, history, cache,24* offline storage, etc.)25*26* __Customizing the Firefox Profile__27*28* The profile used for each WebDriver session may be configured using the29* {@linkplain Options} class. For example, you may install an extension, like30* Firebug:31*32* const {Builder} = require('selenium-webdriver');33* const firefox = require('selenium-webdriver/firefox');34*35* let options = new firefox.Options()36* .addExtensions('/path/to/firebug.xpi')37* .setPreference('extensions.firebug.showChromeErrors', true);38*39* let driver = new Builder()40* .forBrowser('firefox')41* .setFirefoxOptions(options)42* .build();43*44* The {@linkplain Options} class may also be used to configure WebDriver based45* on a pre-existing browser profile:46*47* let profile = '/usr/local/home/bob/.mozilla/firefox/3fgog75h.testing';48* let options = new firefox.Options().setProfile(profile);49*50* The FirefoxDriver will _never_ modify a pre-existing profile; instead it will51* create a copy for it to modify. By extension, there are certain browser52* preferences that are required for WebDriver to function properly and they53* will always be overwritten.54*55* __Using a Custom Firefox Binary__56*57* On Windows and MacOS, the FirefoxDriver will search for Firefox in its58* default installation location:59*60* - Windows: C:\Program Files and C:\Program Files (x86).61* - MacOS: /Applications/Firefox.app62*63* For Linux, Firefox will always be located on the PATH: `$(where firefox)`.64*65* You can provide a custom location for Firefox by setting the binary in the66* {@link Options}:setBinary method.67*68* const {Builder} = require('selenium-webdriver');69* const firefox = require('selenium-webdriver/firefox');70*71* let options = new firefox.Options()72* .setBinary('/my/firefox/install/dir/firefox');73* let driver = new Builder()74* .forBrowser('firefox')75* .setFirefoxOptions(options)76* .build();77*78* __Remote Testing__79*80* You may customize the Firefox binary and profile when running against a81* remote Selenium server. Your custom profile will be packaged as a zip and82* transferred to the remote host for use. The profile will be transferred83* _once for each new session_. The performance impact should be minimal if84* you've only configured a few extra browser preferences. If you have a large85* profile with several extensions, you should consider installing it on the86* remote host and defining its path via the {@link Options} class. Custom87* binaries are never copied to remote machines and must be referenced by88* installation path.89*90* const {Builder} = require('selenium-webdriver');91* const firefox = require('selenium-webdriver/firefox');92*93* let options = new firefox.Options()94* .setProfile('/profile/path/on/remote/host')95* .setBinary('/install/dir/on/remote/host/firefox');96*97* let driver = new Builder()98* .forBrowser('firefox')99* .usingServer('http://127.0.0.1:4444/wd/hub')100* .setFirefoxOptions(options)101* .build();102*103* [geckodriver release]: https://github.com/mozilla/geckodriver/releases/104* [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29105*106* @module selenium-webdriver/firefox107*/108109'use strict'110111const fs = require('node:fs')112const path = require('node:path')113const Symbols = require('./lib/symbols')114const command = require('./lib/command')115const http = require('./http')116const io = require('./io')117const remote = require('./remote')118const webdriver = require('./lib/webdriver')119const zip = require('./io/zip')120const { Browser, Capabilities, Capability } = require('./lib/capabilities')121const { Zip } = require('./io/zip')122const { getBinaryPaths } = require('./common/driverFinder')123const { findFreePort } = require('./net/portprober')124const FIREFOX_CAPABILITY_KEY = 'moz:firefoxOptions'125126/**127* Thrown when there an add-on is malformed.128* @final129*/130class AddonFormatError extends Error {131/** @param {string} msg The error message. */132constructor(msg) {133super(msg)134/** @override */135this.name = this.constructor.name136}137}138139/**140* Installs an extension to the given directory.141* @param {string} extension Path to the xpi extension file to install.142* @param {string} dir Path to the directory to install the extension in.143* @return {!Promise<string>} A promise for the add-on ID once144* installed.145*/146async function installExtension(extension, dir) {147const ext = extension.slice(-4)148if (ext !== '.xpi' && ext !== '.zip') {149throw Error('File name does not end in ".zip" or ".xpi": ' + ext)150}151152let archive = await zip.load(extension)153if (!archive.has('manifest.json')) {154throw new AddonFormatError(`Couldn't find manifest.json in ${extension}`)155}156157let buf = await archive.getFile('manifest.json')158let parsedJSON = JSON.parse(buf.toString('utf8'))159160let { browser_specific_settings } =161/** @type {{browser_specific_settings:{gecko:{id:string}}}} */162parsedJSON163164if (browser_specific_settings && browser_specific_settings.gecko) {165/* browser_specific_settings is an alternative to applications166* It is meant to facilitate cross-browser plugins since Firefox48167* see https://bugzilla.mozilla.org/show_bug.cgi?id=1262005168*/169parsedJSON.applications = browser_specific_settings170}171172let { applications } =173/** @type {{applications:{gecko:{id:string}}}} */174parsedJSON175if (!(applications && applications.gecko && applications.gecko.id)) {176throw new AddonFormatError(`Could not find add-on ID for ${extension}`)177}178179await io.copy(extension, `${path.join(dir, applications.gecko.id)}.xpi`)180return applications.gecko.id181}182183class Profile {184constructor() {185/** @private {?string} */186this.template_ = null187188/** @private {!Array<string>} */189this.extensions_ = []190}191192addExtensions(/** !Array<string> */ paths) {193this.extensions_ = this.extensions_.concat(...paths)194}195196/**197* @return {(!Promise<string>|undefined)} a promise for a base64 encoded198* profile, or undefined if there's no data to include.199*/200[Symbols.serialize]() {201if (this.template_ || this.extensions_.length) {202return buildProfile(this.template_, this.extensions_)203}204return undefined205}206}207208/**209* @param {?string} template path to an existing profile to use as a template.210* @param {!Array<string>} extensions paths to extensions to install in the new211* profile.212* @return {!Promise<string>} a promise for the base64 encoded profile.213*/214async function buildProfile(template, extensions) {215let dir = template216217if (extensions.length) {218dir = await io.tmpDir()219if (template) {220await io.copyDir(/** @type {string} */ (template), dir, /(parent\.lock|lock|\.parentlock)/)221}222223const extensionsDir = path.join(dir, 'extensions')224await io.mkdir(extensionsDir)225226for (let i = 0; i < extensions.length; i++) {227await installExtension(extensions[i], extensionsDir)228}229}230231let zip = new Zip()232return zip233.addDir(dir)234.then(() => zip.toBuffer())235.then((buf) => buf.toString('base64'))236}237238/**239* Configuration options for the FirefoxDriver.240*/241class Options extends Capabilities {242/**243* @param {(Capabilities|Map<string, ?>|Object)=} other Another set of244* capabilities to initialize this instance from.245*/246constructor(other) {247super(other)248this.setBrowserName(Browser.FIREFOX)249// https://fxdx.dev/deprecating-cdp-support-in-firefox-embracing-the-future-with-webdriver-bidi/.250// Enable BiDi only251this.setPreference('remote.active-protocols', 1)252}253254/**255* @return {!Object}256* @private257*/258firefoxOptions_() {259let options = this.get(FIREFOX_CAPABILITY_KEY)260if (!options) {261options = {}262this.set(FIREFOX_CAPABILITY_KEY, options)263}264return options265}266267/**268* @return {!Profile}269* @private270*/271profile_() {272let options = this.firefoxOptions_()273if (!options.profile) {274options.profile = new Profile()275}276return options.profile277}278279/**280* Specify additional command line arguments that should be used when starting281* the Firefox browser.282*283* @param {...(string|!Array<string>)} args The arguments to include.284* @return {!Options} A self reference.285*/286addArguments(...args) {287if (args.length) {288let options = this.firefoxOptions_()289options.args = options.args ? options.args.concat(...args) : args290}291return this292}293294/**295* Sets the initial window size296*297* @param {{width: number, height: number}} size The desired window size.298* @return {!Options} A self reference.299* @throws {TypeError} if width or height is unspecified, not a number, or300* less than or equal to 0.301*/302windowSize({ width, height }) {303function checkArg(arg) {304if (typeof arg !== 'number' || arg <= 0) {305throw TypeError('Arguments must be {width, height} with numbers > 0')306}307}308309checkArg(width)310checkArg(height)311return this.addArguments(`--width=${width}`, `--height=${height}`)312}313314/**315* Add extensions that should be installed when starting Firefox.316*317* @param {...string} paths The paths to the extension XPI files to install.318* @return {!Options} A self reference.319*/320addExtensions(...paths) {321this.profile_().addExtensions(paths)322return this323}324325/**326* @param {string} key the preference key.327* @param {(string|number|boolean)} value the preference value.328* @return {!Options} A self reference.329* @throws {TypeError} if either the key or value has an invalid type.330*/331setPreference(key, value) {332if (typeof key !== 'string') {333throw TypeError(`key must be a string, but got ${typeof key}`)334}335if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {336throw TypeError(`value must be a string, number, or boolean, but got ${typeof value}`)337}338let options = this.firefoxOptions_()339options.prefs = options.prefs || {}340options.prefs[key] = value341return this342}343344/**345* Sets the path to an existing profile to use as a template for new browser346* sessions. This profile will be copied for each new session - changes will347* not be applied to the profile itself.348*349* @param {string} profile The profile to use.350* @return {!Options} A self reference.351* @throws {TypeError} if profile is not a string.352*/353setProfile(profile) {354if (typeof profile !== 'string') {355throw TypeError(`profile must be a string, but got ${typeof profile}`)356}357this.profile_().template_ = profile358return this359}360361/**362* Sets the binary to use. The binary may be specified as the path to a363* Firefox executable.364*365* @param {(string)} binary The binary to use.366* @return {!Options} A self reference.367* @throws {TypeError} If `binary` is an invalid type.368*/369setBinary(binary) {370if (binary instanceof Channel || typeof binary === 'string') {371this.firefoxOptions_().binary = binary372return this373}374throw TypeError('binary must be a string path ')375}376377/**378* Enables Mobile start up features379*380* @param {string} androidPackage The package to use381* @return {!Options} A self reference382*/383enableMobile(androidPackage = 'org.mozilla.firefox', androidActivity = null, deviceSerial = null) {384this.firefoxOptions_().androidPackage = androidPackage385386if (androidActivity) {387this.firefoxOptions_().androidActivity = androidActivity388}389if (deviceSerial) {390this.firefoxOptions_().deviceSerial = deviceSerial391}392return this393}394395/**396* Enables moz:debuggerAddress for firefox cdp397*/398enableDebugger() {399return this.set('moz:debuggerAddress', true)400}401402/**403* Enable bidi connection404* @returns {!Capabilities}405*/406enableBidi() {407return this.set('webSocketUrl', true)408}409}410411/**412* Enum of available command contexts.413*414* Command contexts are specific to Marionette, and may be used with the415* {@link #context=} method. Contexts allow you to direct all subsequent416* commands to either "content" (default) or "chrome". The latter gives417* you elevated security permissions.418*419* @enum {string}420*/421const Context = {422CONTENT: 'content',423CHROME: 'chrome',424}425426/**427* @param {string} file Path to the file to find, relative to the program files428* root.429* @return {!Promise<?string>} A promise for the located executable.430* The promise will resolve to {@code null} if Firefox was not found.431*/432function findInProgramFiles(file) {433let files = [434process.env['PROGRAMFILES'] || 'C:\\Program Files',435process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)',436].map((prefix) => path.join(prefix, file))437return io.exists(files[0]).then(function (exists) {438return exists439? files[0]440: io.exists(files[1]).then(function (exists) {441return exists ? files[1] : null442})443})444}445446/** @enum {string} */447const ExtensionCommand = {448GET_CONTEXT: 'getContext',449SET_CONTEXT: 'setContext',450INSTALL_ADDON: 'install addon',451UNINSTALL_ADDON: 'uninstall addon',452FULL_PAGE_SCREENSHOT: 'fullPage screenshot',453}454455/**456* Creates a command executor with support for Marionette's custom commands.457* @param {!Promise<string>} serverUrl The server's URL.458* @return {!command.Executor} The new command executor.459*/460function createExecutor(serverUrl) {461let client = serverUrl.then((url) => new http.HttpClient(url))462let executor = new http.Executor(client)463configureExecutor(executor)464return executor465}466467/**468* Configures the given executor with Firefox-specific commands.469* @param {!http.Executor} executor the executor to configure.470*/471function configureExecutor(executor) {472executor.defineCommand(ExtensionCommand.GET_CONTEXT, 'GET', '/session/:sessionId/moz/context')473474executor.defineCommand(ExtensionCommand.SET_CONTEXT, 'POST', '/session/:sessionId/moz/context')475476executor.defineCommand(ExtensionCommand.INSTALL_ADDON, 'POST', '/session/:sessionId/moz/addon/install')477478executor.defineCommand(ExtensionCommand.UNINSTALL_ADDON, 'POST', '/session/:sessionId/moz/addon/uninstall')479480executor.defineCommand(ExtensionCommand.FULL_PAGE_SCREENSHOT, 'GET', '/session/:sessionId/moz/screenshot/full')481}482483/**484* Creates {@link selenium-webdriver/remote.DriverService} instances that manage485* a [geckodriver](https://github.com/mozilla/geckodriver) server in a child486* process.487*/488class ServiceBuilder extends remote.DriverService.Builder {489/**490* @param {string=} opt_exe Path to the server executable to use. If omitted,491* the builder will attempt to locate the geckodriver on the system PATH.492*/493constructor(opt_exe) {494super(opt_exe)495this.setLoopback(true) // Required.496}497498/**499* Enables verbose logging.500*501* @param {boolean=} opt_trace Whether to enable trace-level logging. By502* default, only debug logging is enabled.503* @return {!ServiceBuilder} A self reference.504*/505enableVerboseLogging(opt_trace) {506return this.addArguments(opt_trace ? '-vv' : '-v')507}508509/**510* Overrides the parent build() method to add the websocket port argument511* for Firefox when not connecting to an existing instance.512*513* @return {!DriverService} A new driver service instance.514*/515build() {516let port = this.options_.port || findFreePort()517let argsPromise = Promise.resolve(port).then((port) => {518// Start with the default --port argument.519let args = this.options_.args.concat(`--port=${port}`)520// If the "--connect-existing" flag is not set, add the websocket port.521if (!this.options_.args.some((arg) => arg === '--connect-existing')) {522return findFreePort().then((wsPort) => {523args.push(`--websocket-port=${wsPort}`)524return args525})526}527return args528})529530let options = Object.assign({}, this.options_, { args: argsPromise, port })531return new remote.DriverService(this.exe_, options)532}533}534535/**536* A WebDriver client for Firefox.537*/538class Driver extends webdriver.WebDriver {539/**540* Creates a new Firefox session.541*542* @param {(Options|Capabilities|Object)=} opt_config The543* configuration options for this driver, specified as either an544* {@link Options} or {@link Capabilities}, or as a raw hash object.545* @param {(http.Executor|remote.DriverService)=} opt_executor Either a546* pre-configured command executor to use for communicating with an547* externally managed remote end (which is assumed to already be running),548* or the `DriverService` to use to start the geckodriver in a child549* process.550*551* If an executor is provided, care should e taken not to use reuse it with552* other clients as its internal command mappings will be updated to support553* Firefox-specific commands.554*555* _This parameter may only be used with Mozilla's GeckoDriver._556*557* @throws {Error} If a custom command executor is provided and the driver is558* configured to use the legacy FirefoxDriver from the Selenium project.559* @return {!Driver} A new driver instance.560*/561static createSession(opt_config, opt_executor) {562let caps = opt_config instanceof Capabilities ? opt_config : new Options(opt_config)563564let firefoxBrowserPath = null565566let executor567let onQuit568569if (opt_executor instanceof http.Executor) {570executor = opt_executor571configureExecutor(executor)572} else if (opt_executor instanceof remote.DriverService) {573if (!opt_executor.getExecutable()) {574const { driverPath, browserPath } = getBinaryPaths(caps)575opt_executor.setExecutable(driverPath)576firefoxBrowserPath = browserPath577}578executor = createExecutor(opt_executor.start())579onQuit = () => opt_executor.kill()580} else {581let service = new ServiceBuilder().build()582if (!service.getExecutable()) {583const { driverPath, browserPath } = getBinaryPaths(caps)584service.setExecutable(driverPath)585firefoxBrowserPath = browserPath586}587executor = createExecutor(service.start())588onQuit = () => service.kill()589}590591if (firefoxBrowserPath) {592const vendorOptions = caps.get(FIREFOX_CAPABILITY_KEY)593if (vendorOptions) {594vendorOptions['binary'] = firefoxBrowserPath595caps.set(FIREFOX_CAPABILITY_KEY, vendorOptions)596} else {597caps.set(FIREFOX_CAPABILITY_KEY, { binary: firefoxBrowserPath })598}599caps.delete(Capability.BROWSER_VERSION)600}601602return /** @type {!Driver} */ (super.createSession(executor, caps, onQuit))603}604605/**606* This function is a no-op as file detectors are not supported by this607* implementation.608* @override609*/610setFileDetector() {}611612/**613* Get the context that is currently in effect.614*615* @return {!Promise<Context>} Current context.616*/617getContext() {618return this.execute(new command.Command(ExtensionCommand.GET_CONTEXT))619}620621/**622* Changes target context for commands between chrome- and content.623*624* Changing the current context has a stateful impact on all subsequent625* commands. The {@link Context.CONTENT} context has normal web626* platform document permissions, as if you would evaluate arbitrary627* JavaScript. The {@link Context.CHROME} context gets elevated628* permissions that lets you manipulate the browser chrome itself,629* with full access to the XUL toolkit.630*631* Use your powers wisely.632*633* @param {!Promise<void>} ctx The context to switch to.634*/635setContext(ctx) {636return this.execute(new command.Command(ExtensionCommand.SET_CONTEXT).setParameter('context', ctx))637}638639/**640* Installs a new addon with the current session. This function will return an641* ID that may later be used to {@linkplain #uninstallAddon uninstall} the642* addon.643*644*645* @param {string} path Path on the local filesystem to the web extension to646* install.647* @param {boolean} temporary Flag indicating whether the extension should be648* installed temporarily - gets removed on restart649* @return {!Promise<string>} A promise that will resolve to an ID for the650* newly installed addon.651* @see #uninstallAddon652*/653async installAddon(path, temporary = false) {654let stats = fs.statSync(path)655let buf656if (stats.isDirectory()) {657let zip = new Zip()658await zip.addDir(path)659buf = await zip.toBuffer('DEFLATE')660} else {661buf = await io.read(path)662}663return this.execute(664new command.Command(ExtensionCommand.INSTALL_ADDON)665.setParameter('addon', buf.toString('base64'))666.setParameter('temporary', temporary),667)668}669670/**671* Uninstalls an addon from the current browser session's profile.672*673* @param {(string|!Promise<string>)} id ID of the addon to uninstall.674* @return {!Promise} A promise that will resolve when the operation has675* completed.676* @see #installAddon677*/678async uninstallAddon(id) {679id = await Promise.resolve(id)680return this.execute(new command.Command(ExtensionCommand.UNINSTALL_ADDON).setParameter('id', id))681}682683/**684* Take full page screenshot of the visible region685*686* @return {!Promise<string>} A promise that will be687* resolved to the screenshot as a base-64 encoded PNG.688*/689takeFullPageScreenshot() {690return this.execute(new command.Command(ExtensionCommand.FULL_PAGE_SCREENSHOT))691}692}693694/**695* Provides methods for locating the executable for a Firefox release channel696* on Windows and MacOS. For other systems (i.e. Linux), Firefox will always697* be located on the system PATH.698* @deprecated Instead of using this class, you should configure the699* {@link Options} with the appropriate binary location or let Selenium700* Manager handle it for you.701* @final702*/703class Channel {704/**705* @param {string} darwin The path to check when running on MacOS.706* @param {string} win32 The path to check when running on Windows.707*/708constructor(darwin, win32) {709/** @private @const */ this.darwin_ = darwin710/** @private @const */ this.win32_ = win32711/** @private {Promise<string>} */712this.found_ = null713}714715/**716* Attempts to locate the Firefox executable for this release channel. This717* will first check the default installation location for the channel before718* checking the user's PATH. The returned promise will be rejected if Firefox719* can not be found.720*721* @return {!Promise<string>} A promise for the location of the located722* Firefox executable.723*/724locate() {725if (this.found_) {726return this.found_727}728729let found730switch (process.platform) {731case 'darwin':732found = io.exists(this.darwin_).then((exists) => (exists ? this.darwin_ : io.findInPath('firefox')))733break734735case 'win32':736found = findInProgramFiles(this.win32_).then((found) => found || io.findInPath('firefox.exe'))737break738739default:740found = Promise.resolve(io.findInPath('firefox'))741break742}743744this.found_ = found.then((found) => {745if (found) {746// TODO: verify version info.747return found748}749throw Error('Could not locate Firefox on the current system')750})751return this.found_752}753754/** @return {!Promise<string>} */755[Symbols.serialize]() {756return this.locate()757}758}759760/**761* Firefox's developer channel.762* @const763* @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#developer>764*/765Channel.DEV = new Channel(766'/Applications/Firefox Developer Edition.app/Contents/MacOS/firefox',767'Firefox Developer Edition\\firefox.exe',768)769770/**771* Firefox's beta channel. Note this is provided mainly for convenience as772* the beta channel has the same installation location as the main release773* channel.774* @const775* @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#beta>776*/777Channel.BETA = new Channel('/Applications/Firefox.app/Contents/MacOS/firefox', 'Mozilla Firefox\\firefox.exe')778779/**780* Firefox's release channel.781* @const782* @see <https://www.mozilla.org/en-US/firefox/desktop/>783*/784Channel.RELEASE = new Channel('/Applications/Firefox.app/Contents/MacOS/firefox', 'Mozilla Firefox\\firefox.exe')785786/**787* Firefox's nightly release channel.788* @const789* @see <https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly>790*/791Channel.NIGHTLY = new Channel('/Applications/Firefox Nightly.app/Contents/MacOS/firefox', 'Nightly\\firefox.exe')792793// PUBLIC API794795module.exports = {796Channel,797Context,798Driver,799Options,800ServiceBuilder,801}802803804