Show TOC

Object documentationStructure of the Query API

 

The query API hides the HTML complexity and searches for UI elements with filters and conditions.

 

Query Types

The query approach is similar, regardless of the underlying technology, but some additional capabilities can be available for some UI technologies. The queries are application-specific. The following table shows the query types and their UI technologies.

Query Type

UI Technology

Applications

CRM Queries

WebCUIF

SAP CRM applications

LS Queries

Unified Rendering Light Speed (LS)

Web Dynpro application (ABAP)

Web Dynpro applications (Java)

Web GUI – SAP GUI content displayed in MS Internet Explorer

Web Queries

BSP and Plain HTML

Web applications

JWDP Queries

Java Web Dynpro (old releases)

Java Web Dynpro applications

Example query: "Search for all UI elements in an HTML table in which the Partner Function is Sales employee and the Partner ID is244."

Application Controllers

Application controllers are the main entry point to the application being tested, and provide access to the HTML content that the current session displays.

As of CBTA 3.0 SP2, several application controllers are provided, each for a specific use-case, depending on the underlying UI technology:

  • Light Speed Controller: Controller for applications that are built on top of the Unified Rendering Light Speed framework (such as Web Dynpro ABAP applications).

  • CRM Controller: Controller for SAP CRM applications that rely on the WebCUIF UI technology.

  • Web Controller: Controller for Web applications whose underlying UI technology is unknown, or Web applications that do not have a specific controller (like BSP applications).

  • Java Web Dynpro Controller: Controller for applications based on previous releases of Java Web Dynpro.

The controller interfaces are the entry points to the query interfaces. Each controller has at least one method to create query objects.

Creating a Web Query Object: The following script creates a query object to search for Web controls:.

Syntax Syntax

  1. Dim controller, query
  2. Set controller = WebController()
  3. Set query = controller.CreateQuery()
End of the code.

Creating a WebCUIF query object: The following script creates a query object to search for WebCUIF controls (for SAP CRM applications), using theCrmController.

Syntax Syntax

  1. Dim controller, query
  2. Set controller = CrmController()
  3. Set query = controller.CreateQuery()
End of the code.

Creating a Light Speed query object: The following script creates a query object to search for Light Speed controls. The code is similar; the only difference is that the Light Speed controller is used instead of the Web controller.

Syntax Syntax

  1. Dim controller, query
  2. Set controller = LsController()
  3. Set query = controller.CreateQuery()
End of the code.

Creating a Web query object from any controller: In the following example, we ask for a Web query instead of a Light Speed query, explicitly, by calling theCreateWebQuery method.

Syntax Syntax

  1. Dim controller, query
  2. Set controller = LsController()
  3. Set query = controller.CreateWebQuery()
End of the code.

Query Creations with Options: The query objects can be created with options that are specific to the underlying UI technology. This additional parameter is optional. The following example shows the creation of a Light Speed query using the option /ls, which activates optimization. For more details, see the following sections.

Syntax Syntax

  1. Dim query
  2. Set query = LsController().CreateQuery("/ls")
End of the code.
Web Controls

Light Speed Web Controls

Applications that are built on top of the Light Speed framework generate controls in which at least one of the HTML elements provides meta-information by additional HTML attributes:

  • ct: control type

  • lsdata: Light Speed data; a collection of key/value pairs that describe the control and its current state.

Example of Light Speed attributes for a control of type checkbox:

  • Checked: state of the checkbox

  • Enabled: false when the checkbox is disabled (its state is not relevant)

  • Readonly: false when the state cannot be changed

  • Text: the text displayed next to the checkbox

  • Tooltip: the text in the tooltip

The Light Speed query interfaces are specialized to use this meta-information, so you can search for a control using the Light Speed data.

CRM Web controls

CRM applications generate their content with the WebCUIF UI technology, in which each control has a hidden SPAN HTML element that provides meta-information by its ID attribute. Such an ID can look like this, for example: A_btpartner:V_Partner:T_ROW_SELECTOR:C_btpartner:I_partner_fct:R_1

The ID consists of the following elements:

  • A_: application name

  • V_: view name

  • T_: type og the control

  • C_: context

  • I_: interface, which is a field name or an attribute name in the C_ context

  • R_: row number; for example when the control embedded in a table container

  • K_: key; for example an item in a dropdown list box can be selected by key

The CRM query interfaces are specialized to use this meta-information, so you can search for a control with these fragments.

Example Example

The screenshot below shows the kind of toolbar that a CRM application can display. In this example, the links are illustrated with an icon:

......................................................................

You can use the developer tool (F12 in MS Internet Explorer) to visualize the internal structure of the Save button. The result will show the following HTML elements:

......................................................................

Even for this simple toolbar, the internal structure is complex. A lot of information is available, and the query API hides this complexity. With the query API, the test engineers can, for example, search the Save button using the text which is visible to the end user, which is in the innerText HTML property.

End of the example.
Queries, Filter,s and Conditions

The query API searches controls in HTML pages. The objects created with this API have the following characteristics:

  • Queries are created with an application controller. Select the one for the UI technology that is tested.

  • The query can have one or more filters.

  • Each filter can have one or more conditions.

  • Each filter can have sub-filters.

  • Each condition can check the values of the UI element attributes and properties.

Queries have a restricted lifecycle. They can only be used in the same context in which they are created. A query can be used several times, but only for the current set of HTML documents, so you need to create a new query when you navigate to a different HTML page, that is, after each roundtrip to the HTTP server.

Interface Overview

Controller Interface

The controller is the entry point to the query API. You can create queries with it.

With the CreateQuery method, you can create objects for the query.

There is one controller for each UI technology. Select the one for the element you are looking for.

For more information, see Technical Information for the Query API.

Query Interface

The main methods of the query interface are the following:

  • SetFilter: removes all filters and defines the first one

  • AddFilter: adds an additional filter

  • Select: executes the query and returns a set of controls

  • SelectSingle: executes the query and returns the first control matching the criteria

The query property ParentControlUri defines the scope in which you search for controls.

You can specify the query interfaces to leverage the meta-information for the underlying UI technology.

For more information, see Technical Information for the Query API.

Filter and Conditions Interface

The filter contains the criteria that the controls must meet. Methods:

  • SetCondition: removes all conditions, and defines the first one

  • AddCondition: adds an additional condition

  • SetFilter: removes all sub-filters and defines the first one

  • AddFilter: adds an additional sub-filter

A condition contains information about the criteria that were defined before, using the SetCondition method.

Properties:

  • AttributeName: name of the attribute (or property) used by this condition

  • BooleanOperator: operator used when evaluating this condition

  • Value: expected value of the attribute or property

  • Option: evaluation options for condition

For more information, see Technical Information for the Query API.

Web Control Interfaces

A query searches the HTML content for controls, and returns one or more of them. These controls implement interfaces providing access to the HTML attributes and properties of the underlying HTML elements.

A single control can be a combination of several HTML elements, and the API is specialized to provide access to the meta-information by additional interfaces, such as:

For more information, see Technical Information for the Query API.