Selenium Core Extensions (User-Extensions.js)

Selenium Core Extensions

To understand extensions, let us first understand the three pillars of Selenium IDE. Every command you record or type in the IDE belongs to one of the three categories below, and each screenshot shows how that category appears in the IDE command list.

1. Action: What operation you are performing on the UI screen.

   

2. Accessors / Assertion: What verification you perform on the data you get from the UI.

   

3. Locator Strategy: How you find the element in the UI.

   

Selenium IDE ships with a mature library that already contains plenty of actions, accessors and assertions, and locator strategies.

Sometimes, however, a project needs functionality that is not in that library. In that situation you can expand the library by adding your own custom extension. These custom extensions are called a user extension.

For example, suppose you need an action that converts text to upper case before filling it into a web element. No such action exists in the default library, so you create your own user extension. In this tutorial you will learn how to build a user extension that converts text to upper case.

⚠️ Before you start: the workflow described here belongs to Selenium Core and the original Firefox-plugin Selenium IDE. Selenium Core has been retired, and user-extension support was dropped from the Selenium jars in Selenium 3. The steps and code below are preserved because a large number of legacy Selenese suites still depend on them; the modern replacement is described later in this article.

Requirement to Create a Selenium User Extension

To create a user extension for Selenium IDE, you need the basic concepts of JavaScript and, in particular, the JavaScript prototype object. The diagram below shows the two prototype objects that a user extension attaches itself to.

To create your user extension, you write JavaScript methods and add them to the Selenium object prototype and to the PageBot object prototype.

How Selenium IDE Recognizes a User Extension

After a user extension is added to Selenium IDE and the IDE is started, every function registered on those JavaScript prototypes is loaded, and Selenium IDE recognizes each one by its name. That is why the naming prefixes in the next section are not a style choice — they are how the IDE classifies your command.

How to Create a User Extension

Step 1) Action – all actions start with do. If the action converts text to upper case, its name is doTextUpperCase. When you add this action method to Selenium IDE, the IDE itself creates a matching wait method, so doTextUpperCase also produces the wait function textUpperCaseAndWait. The method can accept two parameters.

Example: Upper Case Text Action

Selenium.prototype.doTextUpperCase = function(locator, text) {
// Here findElement is itself capable to handle all type of locator(xpath,css,name,id,className), We just need to pass the locator text
var element = this.page().findElement(locator);

// Create the text to type
text = text.toUpperCase();

// Replace the element text with the new text
this.page().replaceText(element, text);
};

Step 2) Accessors / Assertion – all accessors registered on the Selenium object prototype are prefixed by get or is, for example getValueFromCompoundTable or isValueFromCompoundTable. An accessor can accept two parameters, one for the target and one for the value field in the test case. The screenshot below shows how those prefixes appear once the extension is loaded.

For each accessor, Selenium IDE generates the corresponding verification functions prefixed by verify and assert, plus a wait function prefixed by waitFor.

Example: For Upper Case Text accessors

Selenium.prototype.assertTextUpperCase = function(locator, text) {
// All locator-strategies are automatically handled by "findElement"
var element = this.page().findElement(locator);

// Create the text to verify
text = text.toUpperCase();

// Get the actual element value
var actualValue = element.value;

// Make sure the actual value matches the expected
Assert.matches(expectedValue, actualValue);
};

Selenium.prototype.isTextEqual = function(locator, text) {
return this.getText(locator).value===text;
};

Selenium.prototype.getTextValue = function(locator, text) {
return this.getText(locator).value;
};

Step 3) Locator strategy – if you want to create your own function to locate an element, extend the PageBot prototype with a function prefixed by locateElementBy. It takes two parameters: the locator string, and the document in which the element should be searched.

Example: For Upper Case Text Locator

// The "inDocument" is a document you are searching.
PageBot.prototype.locateElementByUpperCase = function(text, inDocument) {
// Create the text to search for
var expectedValue = text.toUpperCase();

// Loop through all elements, looking for ones that have
// a value === our expected value
var allElements = inDocument.getElementsByTagName("*");
// This star '*' is a kind of regular expression it will go through every element (in HTML DOM every element surely have a tag name like<body>,<a>,<h1>,<table>,<tr>,<td> etc. ). Here our motive is to find an element which matched with the Upper Case text we have passed so we will search it with all elements and when we get match we will have the correct web element.
for (var i = 0; i < allElements.length; i++) {
var testElement = allElements[i];
if (testElement.innerHTML && testElement.innerHTML === expectedValue) {
return testElement;
}
}
return null;
};

Save all three functions in a single file named user-extensions.js. The file is plain JavaScript, so any text editor is sufficient.

How to Use the Newly Created Core Extension

Loading the file is a four-step task in the original Firefox-plugin IDE. Each screenshot below corresponds to the numbered step beside it.

1. Go to Selenium IDE and click Options -> Options…

   

2. In the General section, select the location of the newly created Selenium Core extension.

   

3. Click OK and restart Selenium IDE.

   

4. You will find the extension in the command list.

   

Selenium Core Extensions vs Selenium IDE Extensions

The two terms are used interchangeably in older material, but they describe different layers, and the distinction matters when you decide where to put custom logic.

In short, a Core extension changes what a test can do, while an IDE extension changes what the tool can do.

How the Modern Selenium IDE Replaces user-extensions.js

The Firefox-plugin Selenium IDE stopped working when Firefox moved to the WebExtensions architecture, and the IDE was rewritten as a Chrome, Firefox and Edge browser extension. That rewrite removed the Options field shown above, so there is no place to point at a user-extensions.js file. Two supported alternatives cover the same ground.

• The execute script command. For one-off JavaScript, add an execute script or execute async script step directly in the test and store the result in a variable. This is the closest equivalent to a small custom action.
• A plugin. For reusable commands, build a browser extension that registers a manifest with the IDE. The manifest declares each new command with an id, a name, an optional type and documentation, and it may also declare new locators.

The manifest is registered by sending a message to the IDE extension, as shown in the official Selenium IDE plugin documentation.

browser.runtime.sendMessage(SIDE_ID, {
uri: "/register",
verb: "post",
payload: {
name: "Selenium IDE plugin",
version: "1.0.0",
commands: [
{ id: "textUpperCase", name: "text upper case" }
]
}
}).catch(console.error);

The naming discipline survives the migration: a plugin command is still declared once and then reused across every test, exactly as a Core extension was.

Popular Extensions and Plug-ins Used in Selenium IDE

The add-ons below were the most widely used in the legacy IDE. Several of them, such as flow control and screenshot-on-failure, are now built into the current IDE or available as maintained plugins.

The old SeleniumHQ download page that hosted these files no longer exists. Current plugins and the IDE itself are distributed from the Selenium IDE project site and from the Chrome, Firefox and Edge add-on stores.

Download the Selenium Core Extension used in this Tutorial

FAQs