macroFlex(macro,input,output)

base » macroFlex(macro,input,output)

Description

The main idea with this command is to extend the existing base » macro(file,sheet,name) command, where a series of ephemeral (temporal, more on this below) input and output data can be specified per invocation.

The existing base » macro(file,sheet,name) command works well in terms of reusability. One can utilize the same macro in multiple scripts to automate a series of steps uniformly. With the ability to add flow controls, section and repeat-until, a macro provides a reasonably sound approach to capturing and reusing repeating steps. For more details about macros, please visit base » macro(file,sheet,name).

However, the design of macro comes with a few different constraints that might hinder flexibility and maintainability:

The data variables used by a macro must be correctly defined prior to invocation.
The data variables created or modified by a macro could possibly conflict (and override) with its calling script.
A macro might modify one or more System variables, which could adversely impact the rest of the execution.
So, the data variables created or modified by a macro will not be accessible after completion of macro.

Such are the initial impetus to creating macroFlex. The main idea is to isolate a set of data variables, assigned as “inputs”, to a macro and to extract a set of “outputs” produced by the same macro into data variables – with minimum disruption to the calling script and other test artifacts during execution. Consider the following simple example:

Macro (macro1)

cmd type	command	param 1	param 2	param 3
`number`	`increment(var,amount)`	`num1`	`${num2}`
`base`	`verbose(text)`	`The sum is ${num1}`

Script

cmd type	command	param 1	param 2	param 3
`base`	`save(var,value)`	`num1`	`37`
`base`	`save(var,value)`	`num2`	`5`
`base`	`macroFlex(macro,input,output)`	${macro}	`num1=${num1}` `num2=${num2}`	`num1=total`
`base`	`verbose(text)`	`${num1} + ${num2} = ${total}`

Th macro macro1 is invoked from the script (line 3) via the macroFlex command. Looking at the macro, it is no different than any other Nexial macros (hence it is also usable via base » macro(file,sheet,name)). Notice that the data variable num1 is modified within the macro via the number » increment(var,amount) command. If one is invoking this macro via the base » macro(file,sheet,name)), then the updated value of num1 would persist when the macro has been executed. However, invoked via the macroFlex command, the data variable changes are localized within the macro itself.

During execution, the base » verbose(text) command in the macro would print out:

The sum is 42

This is as one would expects. This demonstrates the value of num1 updated by the preceding number » increment(var,amount) command.

However the base » verbose(text) command in the script (last line) would print out:

37 + 5 = 42

Ths means that the value of num1 is retained and unaffected by the invoked macro. This is the concept of data localization (or, data ephemerality). Within the scope of the macro execution, data variable changes are localized. When a macro is finished, the affected data variables are restored to their respective value. For those that are geek-at-heart or developers by trait, you might recognize this as a form of “pass-by-value”. Moreover one can optionally assign any data variable created or modified within a macro to another data variable (via the output parameter). If such assignment is not needed, one can simply ignore the “output” generated by the invoked macro.

Note in the example script above, the $(projectfile) built-in function was used to reference the macro. More information about this, visit the $(profilefile|macro) page.

Parameters

macro - refers to the macro to invoke via the $(projectfile|macro) built-in function. Detail such as macro file, sheet and macro name must be provided.
input - refers to one or more input assignment represented in the form of key=value, each assignment in separate line. The key will be localized variable (of the macro) and value will be its value.
output - refers to one or more output assignment represented in the form of key=value, each assignment in separate line. Here, key represents the data variable “exported” from the macro, and value represents the data variable to receive the exported value.

Example

In below example, this macro accepts values for url, title, searchButtonLoc and sectionLoc. Also, it passes result data values back to script like matched to result1 in this example. In this case, if user have variable matched outside this macro (probably in script or data), it will not be overridden. So, matched variable will be accessible within this macro only. User can specify multiple output params in separate lines.

Script
script