Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Testing Commerce Manager Functionality

Testing Commerce Manager Functionality

When extending or altering existing Commerce Manager functionality, Elastic Path provides a suite of automated unit tests to ensure that new functionality does not cause existing functionality to fail.

Understanding the Testing Framework

Commerce Manager is rendered in the browser by RAP as <div> elements with automatically generated ids attached. The ids are sequential, and change based on the interactions a user takes within the UI. Based on a user's interaction with an UI element, in-line CSS sets a <div>'s visiblility to visible or hidden. The nature of how RAP renders UI elements makes automated testing difficult to achieve out of the box.

The testing framework uses JavaScript to assign consistent IDs to specific UI elements, like tabs, and indicates an element's visilibity to the user. This allows you to consistently test different user interaction scenarios without accidentally selecting invisible or incorrect UI elements.

Enabling and Disabling Tests

The testing framework is implemented as a standalone plugin, /commerce-manager-client/cm-plugins/test-util . It is included in Commerce Manager's out of the box feature.xml by default, and only needs to be enabled.

To enable the test-util bundle, rebuild Commerce Manager from cm/ext-cm-modules/ext-cm-webapp-runner, adding -Dorg.eclipse.rap.rwt.enableUITests=true to your maven call:
mvn clean tomcat7:run-war -Dorg.eclipse.rap.rwt.enableUITests=true

Adding Test IDs to Your UI Elements

To add Test IDs to your UI elements, you must extend com.elasticpath.cmclient.core.ui.AbstractEpUiPlugin and implement AbstractEpUiPlugin.loadLocalizedMessages().

public class CustomUIPlugin extends AbstractUIPlugin {
  protected void loadLocalizedMessages() {

This should delegate to a Messages class, which then calls LocalizedMessagePostProcessor.getUTF8Encoded() to process the messages:

public static CustomMessages load() {
  return LocalizedMessagePostProcessor.getUTF8Encoded(BUNDLE_NAME, CustomMessages.class);

Writing Your Own Unit Tests

If you wish to create your own unit tests for custom UI elements, you can use Elastic Path's automation IDs to write Selenium tests against.

The following are all the automation IDs attached to UI elements by the test-util plugin.

Table 1.
Test identifier Status Notes
automation-id current, ideal Highest priority for testing. Use this ID for testing if it is present.
widget-id current Locale dependant; use automation-id if possible. (See tables section). Data created at runtime is assigned a widget-id corresponding to the text/title of the widget. Assigned via the EpWidgetIdUtil class.
seeable current Used in conjunction with other IDs to uniquely identify HTML elements. Used to disambiguate currently viewable components with same IDs (generally superseded by automation-id).
wid current Dynamic (non-deterministic) internal RAP widget ID, used at runtime by automation-id. Should not be used for testing.
widget-type current Identifies the type of the widget in RCP. The value is generated by Java. The value may be slightly different from appearance-id.
appearance-id current, to be removed Identifies the type of the widget in RWT. The value is generated by JavaScript. Helps identify the type of the widget.
row-id legacy - to be deprecated Same as the text of the first text-containing column in that row. Use if automation-id is not there or is undefined.
column-id legacy - to be deprecated Same as the text for that column. Use if automation-id is not there or is undefined.
row-num legacy - to be deprecated Identifies the row number in the table, starting with 0.
column-num legacy - to be deprecated Identifies the column number in the row, starting with 0.

Writing Tests Against Automation IDs

In general, write all tests against automation-id if it is available and its value is not undefined. Tests should next be written against widget-id if required.

In addition, you can use the following automation IDs in conjunction with autiomation-id and widget-id to disambiguate between UI elements:

  1. seeable
  2. appearance-id
  3. widget-type

Assigning Automation IDs to Tables

The following automation IDs are automatically assigned to all tables created through EpControlFactory to assist in identifiying specific rows and columns of a table:

  • row-id
  • column-id
  • row-num
  • column-num