Custom functions

In your scripts, you can call custom JavaScript functions to perform operations that are not possible in the codeless scripts.

Overview

Use a custom function to perform operations that are not possible in the codeless scripts. For example, functions can retrieve multiple values and perform mathematical operations on those values. Alternatively, functions can perform actions such as setText to enter an encoded password.

Arguments

Use function arguments to pass string values or AI Objects from your scripts to the called functions.

You can define default values for arguments in the function definition. Then, when you call the function from your script, you can replace those values with values that are more relevant for the current run.

Example

One scenario you could use a JavaScript function for is to check the accuracy of a total sum in a shopping cart. In your script, find the prices of each item and assign them to parameters. Then, pass the prices to a function like the one below to add up the prices and return the sum to the script.

In the script, verify that the total amount in the shopping cart is equal to the sum returned by the function.

The JavaScript function might look like this: 

Copy code 
Function Sum (application, Value1, Value2)
 
const cleanedVal = Value1.replace(/[$,]/g, '');

const cleanedVa2 = Value2.replace(/[$,]/g, '');
 
return  (Number(cleanedVal)+Number(cleanedVa2)).toString();
 

Back to top

Create a custom function

Create a custom JavaScript function, defining what arguments the script has to pass to the function.

In the function, you can use JavaScript, as well as functions from the LFT, AI, and Web namespaces in the OpenText Functional Testing for Developers JavaScript reference. For details, see the OpenText Functional Testing for Developers Help Center.

Note: The following methods in the AI namespace are not supported in Design:

snapshot, getVisibleText, getTextLocations, doubleClick, longClick, highlightMatches, rightClick, verifyImageExists, verifyImageMatch, verifyImageMatchWithMask, registerCustomClass.

To create a JavaScript function

  1. In the script editor, add a Call function step. You can type Call function or click the Add step button button and select Call function.

  2. Hover over the word function, click the down arrow that is displayed, and click Create new function.

  3. Provide a name for the function, and specify where in the Function tree to save it.

    For function naming rules, see Naming conventions.

    Note: After you create the first function, a Functions node is added to the Design Assets pane. You can create subsequent functions from the Add new button in this node.

  4. Define your function's signature; the arguments it expects to receive from the calling script.

    • Every function's first implicit argument is application, which is passed to the function by the calling script. This argument describes the application being tested, providing the context for the function.

    • In the Function details pane, specify any other arguments to pass from the script to the function.

      Arguments can be strings or AI Objects. Because you cannot specify an argument's type, make sure the argument names clearly describe their use.

      Argument names are case-sensitive and must be unique within the function.

      Argument names must not include JavaScript keywords or reserved keywords, such as require, LFT, Web and AI.

    • (Optional) Define default values for the arguments. All default argument values are of type String.

    • (Optional) Provide descriptions of the function and its arguments, to assist in understanding and maintaining the function.

  5. Write your function, using JavaScript and the OpenText Functional Testing for Developers SDK.

    The following items from this SDK are automatically included in your tests, so you don't have to explicitly include them:

    • Namespaces: Web, LFT, AI.

    • Functions:  leanft/expect, leanft/verify.

    For additional details, see Tips for writing custom functions.

  6. (Optional) Add a return statement to specify a value to return to the script.

    If you plan to set this value into a script parameter, the return value must be of type String.

    Returning any other type of value into a parameter will result in an error.

Back to top

Tips for writing custom functions

When writing your custom functions, keep in mind the following issues:

Synchronize your function with the tested application

Because this function is asynchronous, preface each statement that affects the application with the await keyword. This instructs the function to wait until the operation is completed in the application before moving on to the next statement. Otherwise, when the function runs the next statement, the application may not yet be in the expected state.

Example of using await:

Copy code 
// Navigate to product page
await application.navigate("https://advantageonlineshopping.com/#/product/20");
await application.sync();

// Open sign in form
await application.$(AI.AiObject({
    aiClass: AI.AiTypes.profile
})).click();

Using AI Objects passed from the script

If the calling script passes an AI Object as an argument to your script, you can use that argument name directly to call the AI Object's operations. For example, if you define a function with an argument named MyObject, which is used to pass an AI Object, you can use a MyObject.getValue() step to retrieve the test from that object.

In the following example, the script passes the checkout button object to a function that checks whether the sum in the button's text is greater than the sum passed in the second argument.

Script: 

Copy code 
Click the "ADD TO CART" button
Click the shopping_cart
Call verifyLargerThan with checkoutButton = button whose name begins with "CHECKOUT (", baseline = "1000"

Function: 

Copy code 
async function verifyLargerThan (application, checkoutButton, baseline)

var expect = require("leanft/expect");

const textWithNumber = await checkoutButton.getValue();
 
const textWithNumberOnly = textWithNumber.match(/-?(\d+(\.\d*)?|\.\d+)/);
const numToCompare = parseFloat(textWithNumberOnly[0]);

const baselineNum = parseFloat(baseline);

await expect(numToCompare).toBeGreaterThan(baselineNum);

Stopping a script after verification or report steps

By default, a failed verify step or a Reporter step that reports a failure, marks the step and script as failed, but does not stop the script run.

To stop the script run after a verify or Reporter step, the function must return an exception.

Tip: To stop the run when a verification step fails, use the expect function instead of verify.

Back to top

Modify a custom function

To modify an existing function, open it from the Design Assets pane.

Alternatively, in the script editor, select a Call function step, and in the step editing pane click the Open code button.

Modify the function following the rules described in the Create a custom function section. Click the Save button when you want your changes to take effect.

Modifying any of the following might affect scripts that call this function:

  • Function name or location

  • Function argument names

  • The number of function arguments

  • Whether the function returns a value

The scripts are not updated automatically. Review and adjust the function calls in the scripts to accommodate any modifications.

Back to top

Call a custom function from a codeless script

  1. In the script editor, add a Call function step. You can type Call function or click the Add step button button and select Call function.

  2. Hover over the word function, and click the down arrow that is displayed, and select from the available functions.

    Alternatively, you can select a function in the step editing pane.

    Note: You must select the function from the list and not type the name of the function in the step. If the function name changes, you must reselect it from the list of functions in the step.

    The step is automatically constructed with the arguments required for the function.

  3. Update the argument values this step passes to the function.

    The step must include the exact number of argument defined in the function and their values. The arguments do not need to be listed in the order they are defined in the function.

    • Provide values for any arguments that do not have default values.

    • (Optional) Replace default values with values more relevant for your script's flow.

    The values you pass to the function can be strings (constants or variables) or AI Objects. Make sure that you pass the value type expected by the function.

    To enter argument values in the editor, use the syntax rules described in Call function.

    To enter argument values in step editing pane, click the drop-down arrow near the argument value, and select the relevant option: 

    The value type to pass The option to select Next steps
    None Default value None
    String Custom value Enter a constant value or click the Use script parameter button to use a parameter.
    AI Object AI Object Describe your AI Object by selecting an Object class, and optionally providing Identification text and a position. For more details on describing objects, see Specify object identification details. 

  4. (Optional) If the function returns a string value, you can set it into an output parameter.

    Click Return result into output parameter and select an existing parameter or create a new one.

Back to top

See also: