03.06 - Macros

The basic instructions set covers you need for writing working scripts, but they might be quite verbose. If you find yourself writing the same group of instructions again and again, you will probably find a use for shortcuts (or macros).

A certain number of shortcuts are defined natively in the Squash-TA modules.

What does a shortcut look like ?

A shortcut is simply a sequence of instructions put in a separate file, that defines a hook of your choice that will be replaced by a set of instructions defined below. The syntax is the following :

# <Expression of the macro>

=>

<instruction 1>

<instruction 2>

…

<instruction n>

The part above the => separator is the 'hook', the part below is the 'expansion'. Spacing characters does not matter: you may put any spaces or tabulation between every words, either in the hook or in the expansion, or before and after the separator. Also please respect the following rules:

The hook must hold in one single line, that must be the first line of the shortcut file, and the space between the # and <expression of the macro> is mandatory.

On the next line must immediately follow the separator =>,

The expansion must comply to the rules of the basic instruction set (one instruction per lines etc)

How do I use a macro?

The file you just created must land at the root of the 'shortcuts' directory of your test project, and the filename must end with a '.macro' extension. Nested folders containing more shortcuts are not supported.

You can now write regular tests using your shortcut just like any other basic instruction. You don't have to respect your hooks to the letter: lowercase and uppercase characters are matched equally, and you may put any extra spaces you like. When your script will be executed any hook encountered will be replaced by the corresponding expansion.

Example : load 'myfile.xml' and convert it to type 'dataset.dbunit' under the name 'mydataset.dataset'

# load my favourite dataset

=>

//remember that, although the original extension of

//the file is .xml, as a resource in the Test context,

//its initial type is 'file', not 'xml'

LOAD myfile.xml AS myfile.file

CONVERT myfile.file TO xml AS myfile.intermediate.xml

CONVERT myfile.intermediate.xml TO dataset.dbunit AS mydataset.dataset

Call of the macro

# load my favourite dataset

Variabilized shortcuts

You can define variables in the hook and use them in the expansion. When a variable is defined in the hook it won't be literally matched, the hook will then match solely on the basis of the other tokens. The variables defined in the hook may then be used in the expansion. Variables are declared within curly braces '{}', and are used as follow:

a regular hook using a {variable} here => an instruction using my {variable} another instruction making a good use of {variable}

Example : Definition of the macro

# LOAD {file_name} TO XML DATASET {converted_name}

=>

LOAD {file_name} AS data.file

CONVERT data.file TO xml (structured) AS data.xml

CONVERT data.xml TO dataset.dbunit (dataset) AS {converted_name}

Call of the macro

# LOAD foo.xml TO XML DATASET foo.dataset

Corresponding instructions

LOAD foo.file AS data.file

CONVERT data.file TO xml (structured) AS data.xml

CONVERT data.xml TO dataset.dbunit (dataset) AS foo.dataset

At some point you will probably have to create temporary variables, and thus have to worry about possible conflicting Resource identifiers. Hopefully there is a mechanism of randomization that helps to tackle the problem, using a special expression in the extension that will generate a random number between -32768 and 32767 inclusive. Formally it does look like this :

{%%whatever}, where whatever is a string of your choice.

When the expression {%%whatever} is used in a resource name inside a macro, it's replaced by a character string dynamically generated.

If an identical expression {%%whatever} is used several times inside a macro, she's replaced each time with the same value.

If two different expressions {%%whatever} are used inside a macro (for example %%data1 and %%data2), they're replaced by two different values.

When a script is processed and matches the hook, the variables will be remembered and replaced at their corresponding place in the expression, and random numbers placeholders will be filled as well. Let's rewrite the previous example :

Example : the same shortcut than above, with variables

# LOAD {file_name} TO XML DATASET {converted_name}

=>

LOAD {file_name} AS __{%%data1}.file

CONVERT __{%%data1}.file TO xml (structured) AS result{%%data2}.xml

CONVERT result{%%data2}.xml TO dataset.dbunit (dataset) AS {converted_name}

Call of the macro

# LOAD foo.xml TO XML DATASET foo.dataset

Corresponding instructions

LOAD foo.xml AS __354.file

CONVERT __354.file TO xml(structured) AS result6345.xml

CONVERT result6345.xml TO dataset.dbunit(dataset) AS foo.dataset