UI5 extension of the OPA framework.
Helps you when writing tests for UI5 apps. Provides convenience to wait and retrieve for UI5 controls without relying on global IDs. Makes it easy to wait until your UI is in the state you need for testing, for example waiting for back-end data.
Method | Description |
---|---|
sap.ui.test.Opa5.createPageObjects |
Creates a set of page objects, each consisting of actions and assertions and adds them to the Opa configuration. Use page objects to structure your actions and assertions based on parts of the screen. This helps to avoid name clashes and to structure your tests. |
sap.ui.test.Opa5.emptyQueue |
Waits until all waitFor calls are done See sap.ui.test.Opa.emptyQueue for the description |
sap.ui.test.Opa5.extendConfig |
Extends and overwrites default values of the sap.ui.test.Opa.config. Most frequent usecase:
Sample usage:
|
sap.ui.test.Opa5.getContext |
Gives access to a singleton object you can save values in. See sap.ui.test.Opa.getContext for the description |
sap.ui.test.Opa5.getHashChanger |
Returns the HashChanger object in the current context. If an iframe is launched, it will return the iframe's HashChanger. |
sap.ui.test.Opa5.getJQuery |
Returns the jQuery object in the current context. If an iframe is launched, it will return the iframe's jQuery object. |
sap.ui.test.Opa5.getPlugin |
Returns the Opa plugin used for retrieving controls. If an iframe is launched, it will return the iframe's plugin. |
sap.ui.test.Opa5.getTestLibConfig |
Return particular test lib config object. This method is intended to be used by test libraries to access their configuration provided by the test in the testLibs section in sap.ui.test.Opa5.extendConfig |
sap.ui.test.Opa5.getUtils |
Returns the QUnit utils object in the current context. If an iframe is launched, it will return the iframe's QUnit utils. |
sap.ui.test.Opa5.getWindow |
Returns the window object in the current context. If an iframe is launched, it will return the iframe's window. |
hasAppStarted |
Checks if the application has been started using sap.ui.test.Opa5#iStartMyAppInAFrame or sap.ui.test.Opa5#iStartMyUIComponent |
hasAppStartedInAFrame |
Checks if the application has been started using sap.ui.test.Opa5#iStartMyAppInAFrame |
hasUIComponentStarted |
Checks if the application has been started using sap.ui.test.Opa5#iStartMyUIComponent |
iStartMyAppInAFrame |
Starts an app in an iframe. Only works reliably if running on the same server. |
sap.ui.test.Opa5.iStartMyAppInAFrame |
Starts an app in an iframe. Only works reliably if running on the same server. |
iStartMyUIComponent |
Starts a UIComponent. |
iTeardownMyApp |
Tears down the started application regardless of how it was started. Removes the iframe launched by sap.ui.test.Opa5#iStartMyAppInAFrame or destroys the UIComponent launched by sap.ui.test.Opa5#iStartMyUIComponent. This function is designed to make the test's teardown independent of the startup. Use sap.ui.test.Opa5#hasAppStarted to ensure that the application has been started and teardown can be safely performed. |
iTeardownMyAppFrame |
Removes the iframe from the DOM and removes all the references to its objects Use sap.ui.test.Opa5#hasAppStartedInAFrame to ensure that an iframe has been started and teardown can be safely performed. |
sap.ui.test.Opa5.iTeardownMyAppFrame |
Removes the iframe from the DOM and removes all the references to its objects. Use sap.ui.test.Opa5#hasAppStartedInAFrame to ensure that an iframe has been started and teardown can be safely performed. |
iTeardownMyUIComponent |
Destroys the UIComponent and removes the div from the dom like all the references on its objects. Use sap.ui.test.Opa5#hasUIComponentStarted to ensure that a UIComponent has been started and teardown can be safely performed. |
iWaitForPromise |
Schedule a promise on the OPA5 queue.The promise will be executed in order with all waitFors - any subsequent waitFor will be executed after the promise is done. The promise is not directly chained, but instead its result is awaited in a new waitFor statement. This means that any "thenable" should be acceptable. |
sap.ui.test.Opa5.resetConfig |
Resets Opa.config to its default values. See sap.ui.test.Opa5#waitFor for the description Default values for OPA5 are:
|
sap.ui.test.Opa5.stopQueue |
Clears the queue and stops running tests so that new tests can be run. This means all waitFor statements registered by sap.ui.test.Opa5#waitFor will not be invoked anymore and the promise returned by sap.ui.test.Opa5.emptyQueue will be rejected. When its called inside of a check in sap.ui.test.Opa5#waitFor the success function of this waitFor will not be called. |
waitFor |
Takes a superset of the parameters of sap.ui.test.Opa#waitFor. |
Creates a set of page objects, each consisting of actions and assertions and adds them to the Opa configuration.
Use page objects to structure your actions and assertions based on parts of the screen. This helps to avoid name clashes and to structure your tests.
Param | Type | DefaultValue | Description |
---|---|---|---|
mPageObjects | Object<string,sap.ui.test.PageObjectDefinition> |
Multiple page objects are possible, provide at least actions or assertions |
Waits until all waitFor calls are done See sap.ui.test.Opa.emptyQueue for the description
Extends and overwrites default values of the sap.ui.test.Opa.config. Most frequent usecase:
// Every waitFor will append this namespace in front of your viewName
Opa5.extendConfig({
viewNamespace: "namespace.of.my.views."
});
var oOpa = new Opa5();
// Looks for a control with the id "myButton" in a View with the name "namespace.of.my.views.Detail"
oOpa.waitFor({
id: "myButton",
viewName: "Detail"
});
// Looks for a control with the id "myList" in a View with the name "namespace.of.my.views.Master"
oOpa.waitFor({
id: "myList",
viewName: "Master"
});
Sample usage:
var oOpa = new Opa5();
// this statement will will time out after 15 seconds and poll every 400ms.
// those two values come from the defaults of {@link sap.ui.test.Opa.config}.
oOpa.waitFor({
});
// All wait for statements added after this will take other defaults
Opa5.extendConfig({
timeout: 10,
pollingInterval: 100
});
// this statement will time out after 10 seconds and poll every 100 ms
oOpa.waitFor({
});
// this statement will time out after 20 seconds and poll every 100 ms
oOpa.waitFor({
timeout: 20;
});
Param | Type | DefaultValue | Description |
---|---|---|---|
options | object |
The values to be added to the existing config |
Gives access to a singleton object you can save values in. See sap.ui.test.Opa.getContext for the description
Returns the HashChanger object in the current context. If an iframe is launched, it will return the iframe's HashChanger.
Returns the jQuery object in the current context. If an iframe is launched, it will return the iframe's jQuery object.
Returns the Opa plugin used for retrieving controls. If an iframe is launched, it will return the iframe's plugin.
Return particular test lib config object. This method is intended to be used by test libraries to access their configuration provided by the test in the testLibs section in sap.ui.test.Opa5.extendConfig
Param | Type | DefaultValue | Description |
---|---|---|---|
sTestLibName | string |
test library name |
Returns the QUnit utils object in the current context. If an iframe is launched, it will return the iframe's QUnit utils.
Returns the window object in the current context. If an iframe is launched, it will return the iframe's window.
Checks if the application has been started using sap.ui.test.Opa5#iStartMyAppInAFrame or sap.ui.test.Opa5#iStartMyUIComponent
Checks if the application has been started using sap.ui.test.Opa5#iStartMyAppInAFrame
Checks if the application has been started using sap.ui.test.Opa5#iStartMyUIComponent
Starts an app in an iframe. Only works reliably if running on the same server.
Param | Type | DefaultValue | Description |
---|---|---|---|
vSourceOrOptions | string object |
The source URL of the iframe or, since 1.53, you can provide a startup configuration object as the only parameter. |
|
source | string |
The source of the iframe |
|
timeout | number | 80 |
The timeout for loading the iframe in seconds - default is 80 |
autoWait | boolean | false |
Since 1.53, activates autoWait while the application is starting up. This allows more time for application startup and stabilizes tests for slow-loading applications. This parameter is false by default, regardless of the global autoWait value, to prevent issues in existing tests. |
width | string number | Opa.config.frameWidth |
Since 1.57, sets a fixed width for the iframe. |
height | string number | Opa.config.frameHeight |
Since 1.57, sets a fixed height for the iframe. Setting width and/or height is useful when testing responsive applications on screens of varying sizes. By default, the iframe dimensions are 60% of the outer window dimensions. |
iTimeout | number | 80 |
The timeout for loading the iframe in seconds - default is 80 |
autoWait | boolean | false |
Since 1.53, activates autoWait while the application is starting up. This allows more time for application startup and stabilizes tests for slow-loading applications. This parameter is false by default, regardless of the global autoWait value, to prevent issues in existing tests. |
width | string number | Opa.config.frameWidth |
Since 1.57, sets a fixed width for the iframe. |
height | string number | Opa.config.frameHeight |
Since 1.57, sets a fixed height for the iframe. Setting width and/or height is useful when testing responsive applications on screens of varying sizes. By default, the iframe dimensions are 60% of the outer window dimensions. |
Starts an app in an iframe. Only works reliably if running on the same server.
Param | Type | DefaultValue | Description |
---|---|---|---|
vSourceOrOptions | string object |
The source URL of the iframe or, since 1.53, you can provide a startup configuration object as the only parameter. |
|
source | string |
The source of the iframe |
|
timeout | number | 80 |
The timeout for loading the iframe in seconds - default is 80 |
autoWait | boolean | false |
Since 1.53, activates autoWait while the application is starting up. This allows more time for application startup and stabilizes tests for slow-loading applications. This parameter is false by default, regardless of the global autoWait value, to prevent issues in existing tests. |
width | string number | Opa.config.frameWidth |
Since 1.57, sets a fixed width for the iframe. |
height | string number | Opa.config.frameHeight |
Since 1.57, sets a fixed height for the iframe. Setting width and/or height is useful when testing responsive applications on screens of varying sizes. Since 1.65, by default, the iframe dimensions are 60% of the default screen size, considered to be 1280x1024. |
iTimeout | number | 80 |
The timeout for loading the iframe in seconds - default is 80. |
autoWait | boolean | false |
Since 1.53, activates autoWait while the application is starting up. This allows more time for application startup and stabilizes tests for slow-loading applications. This parameter is false by default, regardless of the global autoWait value, to prevent issues in existing tests. |
width | string number | Opa.config.frameWidth |
Since 1.57, sets a fixed width for the iframe. |
height | string number | Opa.config.frameHeight |
Since 1.57, sets a fixed height for the iframe. Setting width and/or height is useful when testing responsive applications on screens of varying sizes. By default, the iframe dimensions are 60% of the outer window dimensions. |
Starts a UIComponent.
Param | Type | DefaultValue | Description |
---|---|---|---|
oOptions | object |
An Object that contains the configuration for starting up a UIComponent. |
|
componentConfig | object |
Will be passed to UIComponent, please read the respective documentation. |
|
hash | string |
Sets the hash sap.ui.core.routing.HashChanger#setHash to the given value. If this parameter is omitted, the hash will always be reset to the empty hash - "". |
|
timeout | number | 15 |
The timeout for loading the UIComponent in seconds - sap.ui.test.Opa5#waitFor. |
autoWait | boolean | false |
Since 1.53, activates autoWait while the application is starting up. This allows more time for application startup and stabilizes tests for slow-loading applications. This parameter is false by default, regardless of the global autoWait value, to prevent issues in existing tests. |
Tears down the started application regardless of how it was started. Removes the iframe launched by sap.ui.test.Opa5#iStartMyAppInAFrame or destroys the UIComponent launched by sap.ui.test.Opa5#iStartMyUIComponent. This function is designed to make the test's teardown independent of the startup. Use sap.ui.test.Opa5#hasAppStarted to ensure that the application has been started and teardown can be safely performed.
Removes the iframe from the DOM and removes all the references to its objects Use sap.ui.test.Opa5#hasAppStartedInAFrame to ensure that an iframe has been started and teardown can be safely performed.
Removes the iframe from the DOM and removes all the references to its objects. Use sap.ui.test.Opa5#hasAppStartedInAFrame to ensure that an iframe has been started and teardown can be safely performed.
Destroys the UIComponent and removes the div from the dom like all the references on its objects. Use sap.ui.test.Opa5#hasUIComponentStarted to ensure that a UIComponent has been started and teardown can be safely performed.
Schedule a promise on the OPA5 queue.The promise will be executed in order with all waitFors - any subsequent waitFor will be executed after the promise is done. The promise is not directly chained, but instead its result is awaited in a new waitFor statement. This means that any "thenable" should be acceptable.
Param | Type | DefaultValue | Description |
---|---|---|---|
oPromise | jQuery.promise Promise |
promise to schedule on the Opa5 queue |
Resets Opa.config to its default values. See sap.ui.test.Opa5#waitFor for the description Default values for OPA5 are:
Clears the queue and stops running tests so that new tests can be run. This means all waitFor statements registered by sap.ui.test.Opa5#waitFor will not be invoked anymore and the promise returned by sap.ui.test.Opa5.emptyQueue will be rejected. When its called inside of a check in sap.ui.test.Opa5#waitFor the success function of this waitFor will not be called.
Takes a superset of the parameters of sap.ui.test.Opa#waitFor.
Param | Type | DefaultValue | Description |
---|---|---|---|
options | object |
An object containing conditions for waiting and callbacks. The allowed keys are listed below. If a key is not allowed, an error is thrown, stating that "the parameter is not defined in the API". As of version 1.72, in addition to the listed keys, declarative matchers are also allowed. Any matchers declared on the root level of the options object are merged with those declared in |
|
id | string RegExp |
The global ID of a control, or the ID of a control inside a view. If a regex and a viewName is provided, Opa5 only looks for controls in the view with a matching ID. Example of a waitFor:
The view that is searched in:
Will result in matching two controls, the image with the effective ID myView--myImage and the button myView--myButton. Although the IDs of the controls myView--bar and myView--baz contain a my, they will not be matched since only the part you really write in your views will be matched. |
|
viewName | string |
The name of a view. If viewName is set, controls will be searched only inside this view. If control ID is given, it will be considered to be relative to the view. |
|
viewNamespace | string |
viewName prefix. Recommended to be set in sap.ui.test.Opa5.extendConfig instead. |
|
viewId | string |
@since 1.62 The ID of a view. Can be used alone or in combination with viewName and viewNamespace. * Always set view ID if there are multiple views with the same name. |
|
fragmentId | string |
@since 1.63 The ID of a fragment. If set, controls will match only if their IDs contain the fragment ID prefix. |
|
matchers | function array object sap.ui.test.matchers.Matcher |
Matchers used to filter controls. Could be a function, a single matcher instance, an array of matcher instances, or, since version 1.72, a plain object to specify matchers declaratively. For a full list of built-in matchers, see sap.ui.test.matchers. Matchers are applied to each control found by the If the previous output is a truthy value, the next matcher will receive this value as an input parameter. If there is a matcher that does not match a control (for example, returns a falsy value), then the control is filtered out. Check function is only called if the matchers matched at least one control, for example, it is not called if matchers filter out all controls/values. Check and success are be called with all matching controls as an input parameter. A matcher inline function has one parameter - an array of controls, and returns an array of the filtered controls. A matcher instance could extend A declarative matcher object is a set of key-value pairs created by the object literal notation, such that:
|
|
controlType | string |
Selects all control by their type. It is usually combined with a viewName or searchOpenDialogs. If no control is matching the type, an empty array will be returned. Here are some samples: this.waitFor({ controlType: "sap.m.Button", success: function (aButtons) { // aButtons is an array of all visible buttons } }); // control type will also return controls that extend the control type // this will return an array of visible sap.m.List and sap.m.Table since both extend List base this.waitFor({ controlType: "sap.m.ListBase", success: function (aLists) { // aLists is an array of all visible Tables and Lists } }); // control type is often combined with viewName - only controls that are inside of the view // and have the correct type will be returned this.waitFor({ viewName: "my.View" controlType: "sap.m.Input", success: function (aInputs) { // aInputs are all sap.m.Inputs inside of a view called 'my.View' } }); |
|
searchOpenDialogs | boolean | false |
If set to true, Opa5 will only look in open dialogs. All the other values except control type will be ignored |
visible | boolean | true |
If set to false, Opa5 will also look for unrendered and invisible controls. |
enabled | boolean | false |
@since 1.66 If set to false, Opa5 will look for both enabled and disabled controls. Note that this option's default value is related to the autoWait mechanism:
|
interactable | boolean | false |
@since 1.80 If set to true, the sap.ui.test.matchers.Interactable matcher will be applied. If autoWait is true, this option has no effect and interactable will always be true. If autoWait is false, which is the default state, the value of the interactable property will have an effect. When interactable is true, enabled will also be set to true, unless declared otherwise. |
editable | boolean | false |
@since 1.80 If set to true, Opa5 will match only editable controls. If set to false, Opa5 will match both editable and non-editable controls. |
timeout | int | 15 |
(seconds) Specifies how long the waitFor function polls before it fails.O means it will wait forever. |
debugTimeout | int | 0 |
@since 1.47 (seconds) Specifies how long the waitFor function polls before it fails in debug mode.O means it will wait forever. |
pollingInterval | int | 400 |
(milliseconds) Specifies how often the waitFor function polls. |
check | function |
Will get invoked in every polling interval. If it returns true, the check is successful and the polling will stop. The first parameter passed into the function is the same value that gets passed to the success function. Returning something other than boolean in check will not change the first parameter of success. |
|
success | function |
Will get invoked after the following conditions are met:
|
|
error | function |
Invoked when the timeout is reached and the check never returned true. |
|
errorMessage | string |
Will be displayed as an errorMessage depending on your unit test framework. Currently the only adapter for Opa5 is QUnit. This message is displayed if Opa5 has reached its timeout before QUnit has reached it. |
|
actions | function Array<function()> sap.ui.test.actions.Action sap.ui.test.actions.Action[] |
Available since 1.34.0. An array of functions or Actions or a mixture of both. An action has an 'executeOn' function that will receive a single control as a parameter. If there are multiple actions defined all of them will be executed (first in first out) on each control of, similar to the matchers. Here is one of the most common usages:
this.waitFor({ id: "myButton", actions: function (oButton) { // this action is executed first this.waitFor({ id: "anotherButton", actions: function () { // This is the second function that will be executed // Opa will also wait until anotherButton is Interactable before executing this function }, success: function () { // This is the third function that will be executed } }) }, success: function () { // This is the fourth function that will be executed } });Executing multiple actions will not wait between actions for a control to become "Interactable" again. If you need waiting between actions you need to split the actions into multiple 'waitFor' statements. |
|
autoWait | boolean | false |
@since 1.42 Only has an effect if set to true. Since 1.53 it can also be a plain object. When autoWait is true, the waitFor statement will not execute success callbacks as long as there is pending asynchronous work such as for example: open XMLHTTPRequests (requests to a server), scheduled delayed work and promises, unfinished UI navigation. In addition, the control state will be checked with the sap.ui.test.matchers.Interactable matcher, and the control will have to be enabled. So when autoWait is enabled, success behaves like an action in terms of waiting. It is recommended to set this value to true for all your waitFor statements using: Opa5.extendConfig({ autoWait: true });Why it is recommended: When writing a huge set of tests and executing them frequently you might face tests that are sometimes successful but sometimes they are not. Setting the autoWait to true should stabilize most of those tests. The default "false" could not be changed since it causes existing tests to fail. There are cases where you do not want to wait for controls to be "Interactable": For example when you are testing the Busy indication of your UI during the sending of a request. But these cases are the exception so it is better to explicitly adding autoWait: false to this waitFor. this.waitFor({ id: "myButton", autoWait: false, success: function (oButton) { Opa5.assert.ok(oButton.getBusy(), "My Button was busy"); } });This is also the easiest way of migrating existing tests. First extend the config, then see which waitFors will time out and finally disable autoWait in these Tests. |