Selenium Ref

From STIQ
Jump to: navigation, search

Concepts

A command is what tells Selenium what to do. Each command call is one line in the test table of the form.


Entered as:

| command | target | value |


Rendered in the UI as:

command target value


Selenium commands come in three 'flavors' - Action, Accessor and Assertion.


Actions

Actions are commands that generally manipulate the state of the application. They do things like "click this link" and "select that option". If an Action fails, or has an error, the execution of the current test is stopped.

Many Actions can be called with the "AndWait" suffix (e.g. "clickAndWait"). This suffix tells Selenium that the action will cause the browser to make a call to the server, and that Selenium should wait for a new page to load.

Accessor and Assertion

Accessors examine the state of the application and store the results in variables (e.g. "storeTitle").

Assertions are like Accessors, but they verify that the state of the application conforms to what is expected. Examples include "make sure the page title is X" and "verify that this checkbox is checked".

All Selenium Assertions can be used in three modes: "assert", "verify", and "waitFor".

For example, you can
  • "assertText"
  • "verifyText"
  • "waitForText".
When an "assert" fails, the test is aborted.
When a "verify" fails, the test will continue execution, logging the failure.

This allows a single "assert" to ensure that the application is on the correct page, followed by a bunch of "verify" assertions to test form field values, labels, etc.

"waitFor" commands wait for some condition to become true (which can be useful for testing Ajax applications). They will succeed immediately if the condition is already true. However, they will fail and halt the test if the condition does not become true within the current timeout setting (refer to the setTimeout action).


Element Locators

Element Locators tell Selenium which HTML element a command refers to. Many commands require an element locator as the "target" attribute. Examples of Element Locators include "elementId" and "document.forms[0].element". These are described more clearly in the next section.

Select Option Specifiers

Select Option Specifiers provide different ways of specifying options of an HTML. Select element (e.g. for selecting a specific option or asserting that the select option satisfies a specification). There are several forms of Select Option Specifier.

Locator Strategies

All locateElementByFoo methods on the PageBot prototype are added as locator-strategies. A locator strategy takes two parameters, the first being the locator string (minus the prefix), and the second being the document in which to search.


Pattern

Patterns are used for various reasons (e.g. to specify the expected value of an input field or identify a select option). Selenium supports various types of patterns, including regular-expressions, all of which are described in more detail later.

Parameter construction and Variables

All Selenium command parameters can be constructed using both simple variable substitution as well as full JavaScript. Both of these mechanisms can access previously stored variables, but do so using different syntax.

Extending Selenium

It can be quite simple to extend Selenium, adding your own actions, assertions and locator-strategies. This is done with JavaScript by adding methods to the Selenium object prototype, and the PageBot object prototype. On startup, Selenium will automatically look through methods on these prototypes, using name patterns to recognize which ones are actions, assertions and locators.

The following examples try to give an indication of how Selenium can be extended with JavaScript.


Automatic availability of storeFoo, assertFoo, assertNotFoo, waitForFoo and waitForNotFoo for every getFoo

All getFoo and isFoo methods on the Selenium prototype automatically result in the availability of storeFoo, assertFoo, assertNotFoo, verifyFoo, verifyNotFoo, waitForFoo, and waitForNotFoo commands.

Example, if you add a getTextLength() method, the following commands will automatically be available: storeTextLength, assertTextLength, assertNotTextLength, verifyTextLength, verifyNotTextLength, waitForTextLength, and waitForNotTextLength commands.

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


Also note that the assertValueRepeated method described above could have been implemented using isValueRepeated, with the added benefit of also automatically getting assertNotValueRepeated, storeValueRepeated, waitForValueRepeated and waitForNotValueRepeated.

project-extensions.js

By default, STIQ looks for a file called "project-extensions.js", and loads the JavaScript code found in that file. This file provides a convenient location for adding features to STIQ.

The file can be found in the \repository\extensions directory.

When you reload the browser (F5 key) (the entire STIQ page, within which are embedded the four STIQ frames). You don't have to restart the browser--just reload the entire page. Note that reloading each frame will not cause project-extensions.js to be read; only reloading the entire page.

Debug loading of project-extensions.js with alerts. Put alert('project-extensions.js loaded successfully'); at the end of your project-extensions.js file. If you see that alert when you reload your browser, you know it loaded successfully. If not, you have a syntax error somewhere in the file.

ui-map.js

Version RC4+ includes a new UI Map feature. You can use JSON in the ui-map.js file to map more readable locators to less readable ones. In addition to increased readability, your tests will be less fragile if you use this technique because the UI Map locators act as a kind of globally available Fascade.

The file can be found in the \repository\extensions directory.

Flow Control (While Loops; If conditional)

Selenium is capable of flow control commands. To add these (unsupported) commands to STIQ download the file goto_sel08.js http://wiki.openqa.org/pages/viewpageattachments.action?pageId=379 from OpenQA.

Put the contents of the goto_sel08.js into STIQ's project-extensions.js file.

See http://wiki.openqa.org/display/SEL/flowControl for how to use the new commands.

This will add STIQ commands while - endWhile and gotoIf - label to your available commands.