Class sap.ui.test.Opa5Module: sap/ui/test/Opa5

extends Object

UI5 extension of the OPA framework


Since: 1.22.
Constructor Summary
new sap.ui.test.Opa5()Helps you when writing tests for UI5 applications.
Method Summary
sap.ui.test.Opa5.createPageObjects(mPageObjects)Create a page object configured as arrangement, action and assertion to the Opa.config.
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(options)Extends and overwrites default values of the sap.ui.test.Opa#.config.
sap.ui.test.Opa5.getContext()Gives access to a singleton object you can save values in.
sap.ui.test.Opa5.getHashChanger()Returns HashChanger object of the IFrame.
sap.ui.test.Opa5.getJQuery()Returns the jQuery object of the IFrame.
sap.ui.test.Opa5.getPlugin()Returns the Opa plugin used for retrieving controls.
sap.ui.test.Opa5.getUtils()Returns QUnit utils object of the IFrame.
sap.ui.test.Opa5.getWindow()Returns the window object of the IFrame or the current window.
sap.ui.test.Opa5.iStartMyAppInAFrame(sSource, iTimeout?)Starts an app in an IFrame.
sap.ui.test.Opa5.iTeardownMyAppFrame()Removes the IFrame from the DOM and removes all the references to its objects
sap.ui.test.Opa5.resetConfig()Resets Opa.config to its default values.
iStartMyAppInAFrame(sSource, iTimeout?)Starts an app in an IFrame.
iStartMyUIComponent(oOptions)Starts a UIComponent.
iTeardownMyAppFrame()Removes the IFrame from the DOM and removes all the references to its objects
iTeardownMyUIComponent()Destroys the UIComponent and removes the div from the dom like all the references on its objects
waitFor(oOptions)Takes the same parameters as sap.ui.test.Opa#waitFor.
Methods borrowed from class sap.ui.base.Object
Constructor Detail
new sap.ui.test.Opa5()
Helps you when writing tests for UI5 applications. 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, e.g.: waiting for backend data.
Method Detail
sap.ui.test.Opa5.createPageObjects(mPageObjects): map
Create a page object configured as arrangement, action and assertion to the Opa.config. Use it to structure your arrangement, action and assertion based on parts of the screen to avoid name clashes and help to structure your tests.
Parameters:
{map}mPageObjects
{map}mPageObjects.<your-page-object-name> Multiple page objects are possible, provide at least actions or assertions
{function}mPageObjects.<your-page-object-name>.baseClass? Base class for the page object's actions and assertions, default: Opa5
{function}mPageObjects.<your-page-object-name>.namespace? Namespace prefix for the page object's actions and assertions, default: sap.ui.test.opa.pageObject. Use it if you use page objects from multiple projects in the same test build.
{map}mPageObjects.<your-page-object-name>.actions? Can be used as an arrangement and action in Opa tests. Only the test knows if an action is used as arrangement or action
{function}mPageObjects.<your-page-object-name>.actions.<your-action-1> This is your custom implementation containing one or multiple waitFor statements
{function}mPageObjects.<your-page-object-name>.actions.<your-action-2> This is your custom implementation containing one or multiple waitFor statements
{map}mPageObjects.<your-page-object-name>.assertions? Can be used as an assertions in Opa tests.
{function}mPageObjects.<your-page-object-name>.assertions.<your-assertions-1> This is your custom implementation containing one or multiple waitFor statements
{function}mPageObjects.<your-page-object-name>.assertions.<your-assertions-2> This is your custom implementation containing one or multiple waitFor statements
Since:
1.25
Returns:
{map} mPageObject The created page object. It will look like this:

 {
  <your-page-object-name> : {
      actions: // an instance of baseClass or Opa5 with all the actions defined above
      assertions: // an instance of baseClass or Opa5 with all the assertions defined above
  }
 }
sap.ui.test.Opa5.emptyQueue(): jQuery.promise
Waits until all waitFor calls are done See sap.ui.test.Opa#.emptyQueue for the description
Returns:
{jQuery.promise} If the waiting was successful, the promise will be resolved. If not it will be rejected
sap.ui.test.Opa5.extendConfig(options)

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 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;
        });
    
Parameters:
{object}options The values to be added to the existing config
Since:
1.40 The own properties of 'arrangements, actions and assertions' will be kept. Here is an example:
    
        // An opa action with an own property 'clickMyButton'
        var myOpaAction = new Opa5();
        myOpaAction.clickMyButton = // function that clicks MyButton
        Opa.config.actions = myOpaAction;

        var myExtension = new Opa5();
        Opa5.extendConfig({
            actions: myExtension
        });

        // The clickMyButton function is still available - the function is logged out
        console.log(Opa.config.actions.clickMyButton);

        // If
        var mySecondExtension = new Opa5();
        mySecondExtension.clickMyButton = // a different function than the initial one
        Opa.extendConfig({
            actions: mySecondExtension
        });

        // Now clickMyButton function is the function of the second extension not the first one.
        console.log(Opa.config.actions.clickMyButton);
    
sap.ui.test.Opa5.getContext(): object
Gives access to a singleton object you can save values in. See sap.ui.test.Opa#.getContext for the description
Since:
1.29.0
Returns:
{object} the context object
sap.ui.test.Opa5.getHashChanger(): sap.ui.core.routing.HashChanger
Returns HashChanger object of the IFrame. If the IFrame is not loaded it will return null.
Returns:
{sap.ui.core.routing.HashChanger} The HashChanger instance
sap.ui.test.Opa5.getJQuery(): jQuery
Returns the jQuery object of the IFrame. If the IFrame is not loaded it will return null.
Returns:
{jQuery} The jQuery object
sap.ui.test.Opa5.getPlugin(): sap.ui.test.OpaPlugin
Returns the Opa plugin used for retrieving controls. If an IFrame is used it will return the iFrame's plugin.
Returns:
{sap.ui.test.OpaPlugin} The plugin instance
sap.ui.test.Opa5.getUtils(): sap.ui.test.qunit
Returns QUnit utils object of the IFrame. If the IFrame is not loaded it will return null.
Returns:
{sap.ui.test.qunit} The QUnit utils
sap.ui.test.Opa5.getWindow(): oWindow
Returns the window object of the IFrame or the current window. If the IFrame is not loaded it will return null.
Returns:
{oWindow} The window of the IFrame
sap.ui.test.Opa5.iStartMyAppInAFrame(sSource, iTimeout?): jQuery.promise
Starts an app in an IFrame. Only works reliably if running on the same server.
Parameters:
{string}sSource The source of the IFrame
{number}iTimeout?, Default: 80 The timeout for loading the IFrame in seconds - default is 80
Returns:
{jQuery.promise} A promise that gets resolved on success
sap.ui.test.Opa5.iTeardownMyAppFrame(): jQuery.promise
Removes the IFrame from the DOM and removes all the references to its objects
Returns:
{jQuery.promise} A promise that gets resolved on success
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:
  • viewNamespace: empty string
  • arrangements: instance of OPA5
  • actions: instance of OPA5
  • assertions: instance of OPA5
  • visible: true
  • timeout : 15 seconds, is increased to 5 minutes if running in debug mode e.g. with URL parameter sap-ui-debug=true
  • pollingInterval: 400 milliseconds
Since:
1.25
iStartMyAppInAFrame(sSource, iTimeout?): jQuery.promise
Starts an app in an IFrame. Only works reliably if running on the same server.
Parameters:
{string}sSource The source of the IFrame
{int}iTimeout?, Default: 80 The timeout for loading the IFrame in seconds - default is 80
Returns:
{jQuery.promise} A promise that gets resolved on success
iStartMyUIComponent(oOptions): jQuery.promise
Starts a UIComponent.
Parameters:
{object}oOptions An Object that contains the configuration for starting up a UIComponent.
{object}oOptions.componentConfig Will be passed to component, please read the respective documentation.
{string}oOptions.hash? 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 - "".
{number}oOptions.timeout?, Default: 15 The timeout for loading the UIComponent in seconds - sap.ui.test.Opa5#waitFor.
Returns:
{jQuery.promise} A promise that gets resolved on success.
iTeardownMyAppFrame(): jQuery.promise
Removes the IFrame from the DOM and removes all the references to its objects
Returns:
{jQuery.promise} A promise that gets resolved on success
iTeardownMyUIComponent(): jQuery.promise
Destroys the UIComponent and removes the div from the dom like all the references on its objects
Returns:
{jQuery.promise} a promise that gets resolved on success.
waitFor(oOptions): jQuery.promise
Takes the same parameters as sap.ui.test.Opa#waitFor. Also allows you to specify additional parameters:
Parameters:
{object}oOptions An Object containing conditions for waiting and callbacks
{string|regexp}oOptions.id? The global ID of a control, or the ID of a control inside a view. If a regex and a viewName is provided, Opa5 will only look for controls in the view with a matching ID.
Example of a waitFor:
    
        this.waitFor({
            id: /my/,
            viewName: "myView"
        });
    
The view that is searched in:
    
        <core:View xmlns:core="sap.ui.core" xmlns="sap.m">
            <Button id="myButton">
            </Button>
            <Button id="bar">
            </Button>
            <Button id="baz">
            </Button>
            <Image id="myImage"></Image>
        </core:View>
    
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.
{string}oOptions.viewName? The name of a view. If this is set the id of the control is searched inside of the view. If an id is not be set, all controls of the view will be found.
{string}oOptions.viewNamespace? This string gets appended before the viewName - should probably be set to the sap.ui.test.Opa5#extendConfig.
{function|array|sap.ui.test.matchers.Matcher}oOptions.matchers? A single matcher or an array of matchers sap.ui.test.matchers. Matchers will be applied to an every control found by the waitFor function. The matchers are a pipeline: the first matcher gets a control as an input parameter, each subsequent matcher gets the same input as the previous one, if the previous output is 'true'. If the previous output is a truthy value, the next matcher will receive this value as an input parameter. If any matcher does not match an input (i.e. returns a falsy value), then the input is filtered out. Check will not be called if the matchers filtered out all controls/values. Check/success will be called with all matching values as an input parameter. Matchers also can be define as an inline-functions.
{string}oOptions.controlType? For example "sap.m.Button" will search for all buttons inside of a container. If an id ID given, this is ignored.
{boolean}oOptions.searchOpenDialogs? If set to true, Opa5 will only look in open dialogs. All the other values except control type will be ignored
{boolean}oOptions.visible?, Default: true If set to false, Opa5 will also look for unrendered and invisible controls.
{int}oOptions.timeout?, Default: 15 (seconds) Specifies how long the waitFor function polls before it fails. Timeout will increased to 5 minutes if running in debug mode e.g. with URL parameter sap-ui-debug=true.
{int}oOptions.pollingInterval?, Default: 400 (milliseconds) Specifies how often the waitFor function polls.
{function}oOptions.check? 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.
{function}oOptions.success? Will get invoked after the following conditions are met:
  1. One or multiple controls were found using controlType, Id, viewName. If visible is true (it is by default), the controls also need to be rendered.
  2. The whole matcher pipeline returned true for at least one control, or there are no matchers
  3. The check function returned true, or there is no check function
The first parameter passed into the function is either a single control (when a single string ID was used), or an array of controls (viewName, controlType, multiple ID's, regex ID's) that matched all matchers. Matchers can alter the array or single control to something different. Please read the documentation of waitFor's matcher parameter.
{function}oOptions.error? Invoked when the timeout is reached and the check never returned true.
{string}oOptions.errorMessage? 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.
{function|function()[]|sap.ui.test.actions.Action|sap.ui.test.actions.Action[]}oOptions.actions 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. But actions will only be executed once and only after the check function returned true. Before an action is executed the sap.ui.test.matchers.Interactable matcher will check if the action may be exected. That means actions will only be executed if the control is not:
  • Behind an open dialog
  • Inside of a navigating NavContainer
  • Busy
  • Inside a Parent control that is Busy
If there are multiple controls in Opa5's result set the action will be executed on all of them. The actions will be invoked directly before success is called. In the documentation of the success parameter there is a list of conditions that have to be fulfilled. They also apply for the actions. There are some predefined actions in the sap.ui.test.actions namespace.
Returns:
{jQuery.promise} A promise that gets resolved on success