Browsers vendors MAY choose to implement WebDriver support in their browsers to allow for the automated testing of browser extensions. To implement this support, the browser MUST support:

In addition to the codes defined in the Handling Errors section of the WebDriver specification [[webdriver]], support for browser extensions requires support the following additional error codes:

In addition to the endpoints defined in the WebDriver specification [[webdriver]], support for browser extensions requires these additional endpoints.

No browser extension will be installed or pre-loaded during a WebDriver session unless it is explicitly specified in the enabledBrowserExtensions array. Browser extensions loaded during the session will not be available to other active instances of the browser that are not part of the WebDriver session. When the session ends, the array of browser extensions are unloaded and uninstalled.

In addition to the Capabilities defined in the WebDriver specification [[webdriver]], support for browser extensions requires the following additional entry on the server capabilities JSON object:

Browser Extensions Commands

Users interact with extensions through several means. First there are actions embedded in the UI of the browser, which can do something directly or open a popup. If the extension uses a popup, it can contain any html content. Finally, extensions can add items to the browser's context menu. WebDriver needs to be able to emulate user actions for all three of these controls in order to completely emulate user interaction.

In addition to the commands defined in the WebDriver specification [[webdriver]], support support for browser extensions requires the following additional commands.

installBrowserExtensions() HTTP Method Path Template Notes POST /session/{ sessionId }/browserext This command installs any number of specified extensions from disk at runtime To install an extension located at "/ext/" in a session with ID 0, the local end would POST to /session/0/browserext/ with the request body { "extensionPaths" : [ "/ext/" ] } The value of the extensionPaths property MUST be an array of absolute paths which point to the location of browser extension files. The path MUST point to either a single file appropriate for a specific brower (e.g. .crx) or a folder which contains the extension source files. If a folder is specified, the folder itself MUST contain a manifest.json file. Subfolders containing manifest.json files will not be searched. If any of the absolute paths specified in the extensionPaths property are invalid, a no such extension path status code MUST be returned. If the installation of any extensions specified in the extensionPaths property fail, an extension not installable status code MUST be returned.

uninstallBrowserExtensions() HTTP Method Path Template Notes DELETE /session/{ sessionId }/browserext/{extensionId} This command uninstalls an extension in a specified browsing session. DOMString extensionId The unique identifier of the browser extension to be uninstalled from the session. If the extensionId specified does not correspond to a browser extension in the current sesssion, a no such browser extension status code MUST be returned.

getBrowserExtensions() HTTP Method Path Template Notes GET /session/{ sessionId }/browserexts This command returns a list of all browser extensions available to the current browsing session. Let extension be a new JSON Object.

Set the property id on extension to a string which is unique for each browser extension.

Set the property name on extension to a string which corresponds to the browser extension's "name" entry in manifest.json .

getBrowserExtActions() HTTP Method Path Template Notes GET /session/{ sessionId }/browserext/{ extensionId }/actions This command returns a list of browser extension actions available for a particular browser extension. Note that this can change from page to page. It MUST return a list of objects which describes the available browser extension actions using the following algorithm for each action: Let action be a new JSON Object.

Set the property type on action to a string which represents the type of browser extension action

Set the property actionTitle on action to the mouseover text for the action.

Set the property icon on action to the filename of the icon file or an empty string if none is displayed. If the icon is dynamically generated, the current icon MUST be returned as a lossless PNG image encoded using Base64.

If the action supports the badgeText property, set the property badgeText on action to the badge text displayed over the action or an empty string if none is present.

Return success with data action DOMString extensionId The unique identifier of the browser extension whose available actions are to be queried. Returned by the getBrowserExtensions() command. If the id specified does not correspond to a browser extension in the current sesssion, a no such browser extension status code MUST be returned.

takeBrowserExtAction() HTTP Method Path Template Notes POST /session/{ sessionId }/browserext/action/{ browserExtActionId } This command causes a browser extension action to be activated. Depending on the extensionActionType specified, this will have one of several effects: extensionActionType Effect browserAction This extensionActionType causes a browserAction to be activated, as if the user had clicked the browser extension's browserAction icon in the browser's chrome. Depending on the browser extension, this may cause a popup to be opened. pageAction This extensionActionType causes a pageAction to be activated, as if the user had clicked the browser extension's pageAction icon in the browser's address bar. Depending on the browser extension, this may cause a popup to be opened. enable This extensionActionType causes the specified extension to be enabled, as if the user had turned the extension on from the browser's management UI. If the extension is already enabled, this command has no effect. disable This extensionActionType causes the specified extension to be disabled, as if the user had turned the extension off from the browser's management UI. If the extension is already disabled, this command has no effect. DOMString browserExtId The unique identifier of the browser extension whose available actions are to be invoked. Returned by the getBrowserExtensions() command. If the extensionId specified does not correspond to a browser extension in the current sesssion, a no such browser extension status code MUST be returned. DOMString extensionActionType The type of the browser extension action to be taken, as returned by the getBrowserExtensionActions() command. This value SHOULD be one of the following: " pageAction ", " browserAction ", " enable ", or " disable " To click a pageAction of an extension with ID 1 in a session with ID 0, the local end would POST to /session/0/browserext/1/action/ with the request body { "type" : "pageAction" } If the type specified does not correspond to a browser extension action available in the browser/on the current page, a no such browser extension action status code MUST be returned.

getBrowserExtContextMenuItems() HTTP Method Path Template Notes GET /session/{ sessionId }/element/{ elementId }/browserext/contexMenuItems This command opens a context menu for a given element. It MUST return a list of objects which describes the available context menu items using the following algorithm for each menu item: Let menuitem be a new JSON Object.

Set the property id on menuitem to a string which is unique for the current session.

Set the property menuItemTitle on menuitem to the text that is displayed in the UI.

Set the property icon on menuitem to the filename of the icon file or an empty string if none is displayed. If the icon is set because of the type of the context menu item (such as a radio button or checkbox), the icon property MUST be set to a string which is consistent for all icons of that type and status (e.g. checked), including across sessions.

Set the property parent on menuitem to the id of the item's parent or an empty string if the menuitem does not have a parent.

Set the property itemType on menuitem to a string value identifying the control type. String Value Description checkbox A checkbox element normal A standard menuItem element (text label) radio A radio element. Within a radio group, only one menuItem will have a value of true separator A horizontal line separator, typically used between groups of related items such as radio groups

Set the property itemChecked on menuitem to a boolean value indicating state of the item according to the following table. This applies only to items of itemType checkbox or radio . Within a radio group, only one menuItem will have a value of true . Boolean Value Description true Selected false Not selected

Return success with data menuitem This list MUST contain all context menu items added by browser extensions and MUST NOT contain any other context menu items. This list MUST contain all context menu items added by browser extensions and MUST NOT contain any other context menu items. After this command has been run, the context menu MUST remain open until the next command that dismisses it (e.g. clicking, navigation) has been run. WebElement elementId The id of the element for which the context menu should be opened.

selectBrowserExtContextMenuItem() HTTP Method Path Template Notes POST /session/{ sessionId }/element/{ elementId }/browserext/contextMenuItem/{ menuitemId } This command causes a context menu item to be selected. This MUST have the same effect as a user clicking or tapping the item in the open context menu. If the menu item is a parent of other menu items, this command MAY open a submenu, but MUST NOT have any other effect. This command MUST be executed even if there is no context menu open. String menuitemId The context menu item id, as returned by the getBrowserExtContextMenuItems() command. If no context menu is currently open, a no such extension context menu item status code MUST be returned.

getBrowserExtPermissionPrompt() HTTP Method Path Template Notes GET /session/{ sessionId }/browserext/permissionPrompt Upon installation of a browser extension, a browser MAY notify the user of potential privacy-related capabilities of the extension. For example, if an extension's manifest.json requests the "tabs" or "webNavigation" permission, the browser MAY request user confirmation of these permissions. This command returns a JSON object that includes the names of permissions which require user confirmation and other information about the prompt. A similar prompt MAY also occur if an extension has been updated and the newer version requires additional permisisons. If there is no prompt at the time this API is called, the error "no such browser extension permission prompt" is returned. Let permissionPrompt be a new JSON Object.

be a new JSON Object. Set the property promptId to a string which is unique for each time a prompt is displayed.

to a string which is unique for each time a prompt is displayed. Set the property promptMessageText to a string which represents the text shown to the user, localized to the default locale specified in manifest.json .

to a string which represents the text shown to the user, localized to the default locale specified in . Set the property promptDefaultLocale to the default locale code specified in manifest.json . If locales are not used by the extension, the property SHOULD be omitted, but MAY return an empty string ("").

to the default locale code specified in . If locales are not used by the extension, the property SHOULD be omitted, but MAY return an empty string (""). Set the property promptRequestingUrl to a string representing the relevant URL. Strings returned here are the same strings defined in the "permissions": [ ] section of manisfest.json . If a URL is not applicable to the prompt, the property SHOULD be omitted but MAY also return an empty string ("").

to a string representing the relevant URL. Strings returned here are the same strings defined in the section of . If a URL is not applicable to the prompt, the property SHOULD be omitted but MAY also return an empty string (""). Set the property promptPermissions to an array of strings which correspond to requested permissions. Strings returned here are the same strings defined in the "permissions": [ ] section of manisfest.json . If permissions are not applicable to the prompt, the property SHOULD be omitted, but MAY include an empty array ([]) or an array of empty strings ([""]).

to an array of strings which correspond to requested permissions. Strings returned here are the same strings defined in the section of . If permissions are not applicable to the prompt, the property SHOULD be omitted, but MAY include an empty array ([]) or an array of empty strings ([""]). Set the property promptActions to an array of strings which correspond to possible actions the user could take. The actions allow and deny are required. Other optional values MAY be returned, but the behavior is not prescribed in this specification. promptAction Required Description allow Required Allows the extension to use or access the capabilities or sites deny Required Denies extension's use of the requested capabilities or sites. The browser implementation of deny is not prescribed in this specification, and MAY result in the cancellation of the extension's installation. dismiss Optional Some browsers MAY provide the user with an option to close a prompt without taking an accept or deny action. The browser implementation of dismiss is not prescribed in this specification, and MAY result in the cancellation of the extension's installation. {custom} Optional Some browsers MAY provide additional options not prescribed in this table. For example, alwaysAllow , allowOnce or allowForThisSiteOnly may be presented in a permission prompt. The browser implementation for these custom actions is not prescribed in this specification. This extension, which does not use locales, prompts to request broad permissions that do not correspond to a specific URL. { "promptId" : "1" , "promptMessageText" : "A new extension Sample1 has been installed. It can access your browsing activity. Do you wish to continue? Yes No Close" , "promptPermissions" : ["tabs","webNavigation"] , "promptActions" : ["allow","deny","dismiss"] } This extension, which uses locales to provide translated strings, prompts for permissions specific to a banking URL. { "promptId" : "2" , "promptMessageText" : "A new extension RegionalBankAssistant1 has been installed. It can read and modify data on regionalbank1.com. Enable Cancel" , "promptDefaultLocale" : "en" , "promptRequestingUrl" : ["http://*.regionalbank1.com"] , "promptActions" : ["allow","deny"] }