Macros¶
The basic instructions set covers your 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 SKF 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 :
# <macro expression> => <instruction 1> <instruction 2> … <instruction n> |
The part above the => separator is the hook and the part below is the expansion.
Spacing characters don’t matter : you may put any spaces or tabulations between every word, either in the hook or in the expansion, or before and after the separator.
Please respect the following rules :
The hook must :
- Hold in one single line.
- Be the first line of the shortcut file.
- Have a space between # and <macro expression>. This is mandatory.
After the hook, the next line must immediately have the separator =>.
The expansion must comply to the rules of the basic instruction set (one instruction per line, etc…).
How do I use a macro ?¶
The file you just created must land in the shortcuts directory (or its subdirectories) of your test project, and the filename must end with a ‘.macro’ extension.
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 is 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 |
Macro usage :
| # 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 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 :
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.file CONVERT data.xml TO dataset.dbunit (dataset) AS {converted_name} |
Macro usage :
| # LOAD foo.xml TO XML DATASET foo.dataset |
Corresponding instructions :
LOAD foo.file AS data.file CONVERT data.file TO xml (structured) AS data.file 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.
Thankfully 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.
It looks 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 string dynamically generated.
If an identical expression {%%whatever} is used several times inside a macro, it’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 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} |
Macro usage :
| # LOAD foo.xml TO XML DATASET foo.dataset |
Corresponding instructions :
LOAD foo.file AS __354.file CONVERT __354.file TO xml (structured) AS result6345.xml CONVERT result6345.xml TO dataset.dbunit (dataset) AS foo.dataset |