Testing Commerce Manager Functionality

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

Testing Framework

Commerce Manager is rendered in the browser by Eclipse RAP (Remote Application Platform) 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 visibility 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 visibility to the user. This allows you to consistently test different user interaction scenarios without accidentally selecting invisible or incorrect UI elements.

Running Tests

For commands to run and debug Selenium tests, see Running Individual Tests. For information about the other levels of tests in Self-Managed Commerce, see Testing.

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 {
  @Override
  protected void loadLocalizedMessages() {
    CustomMessages.load();
  }
}

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 Selenium Tests

If you wish to create your own 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.

• automation-id

  Status: current, ideal

  Highest priority for testing. Use this ID for testing if it is present.

• widget-id

  Status: current

  Locale dependent; 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

  Status: 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

  Status: current

  Dynamic (non-deterministic) internal RAP widget ID, used at runtime by automation-id. Should not be used for testing.

• widget-type

  Status: current

  Identifies the type of the widget in Eclipse RCP (Rich Client Platform). The value is generated by Java. The value may be slightly different from appearance-id.

• appearance-id

  Status: 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

  Status: 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

  Status: legacy - to be deprecated

  Same as the text for that column. Use if automation-id is not there or is undefined.

• row-num

  Status: legacy - to be deprecated

  Identifies the row number in the table, starting with 0.

• column-num

  Status: 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 automation-id and widget-id to disambiguate between UI elements:

• seeable
• appearance-id
• widget-type

Assigning Automation IDs to Tables

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

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