Example of SKF Script¶
Contents :
In this example, we are going to use an SKF script which contains standard instructions and macros.
A script is a plain text file (with .ta extension) containing lists of instructions. All you have to do is to drop it in the ‘tests’ directory (or anywhere in its sub hierarchy) of your project.
Here is the script :
// Step 1 SETUP : // Step 2 LOAD queries/sql/select.sql AS select.file CONVERT select.file TO query.sql AS query // Step 3 # LOAD dbunit/resultsets/mytable_simple_select.xml TO XML DATASET expected.dataset // Step 4 TEST : // Step 5 EXECUTE execute WITH query ON my_database AS raw_result // Step 6 CONVERT raw_result TO dataset.dbunit AS actual.dataset // Step 7 ASSERT actual.dataset IS equal WITH expected.dataset |
What does this SKF script do ?¶
This script executes an SQL query and compares the result to the content of a DbUnit dataset.
We can notice several elements :
- Some comments (lines beginning with ‘//’)
- Phases (SETUP : and TEST :)
- Instructions (multi-colored lines)
- Macros (brown lines).
Now we will break down and analyze that script, identify its components and see how they work together.
SETUP phase declaration :
// Step 1 SETUP : |
The SETUP phase groups instructions that will prepare the test. Note that the instructions in that phase could also be set in the main TEST phase.
Differences lie in the handling of test failures : when an instruction fails during the SETUP phase, it means that the script itself is wrong or that the resource is not avalaible. On the other hand, a failure happening during the TEST phase means that the System Under Test (SUT) has a problem.
To sum up, the SETUP phase sets the test prerequisites.
Loading an SQL query :
// Step 2 LOAD queries/sql/select.sql AS select.file CONVERT select.file TO query.sql AS query |
This pair of instructions will load a file and declare that it contains an SQL query (in that order).
Loading a DbUnit dataset :
// Step 3 # LOAD dbunit/resultsets/mytable_simple_select.xml TO XML DATASET expected.dataset |
The standard way to load a DbUnit dataset requires the same steps than above : load the file and convert it to make it a DbUnit dataset.
However, instead of explicitly writing the corresponding instructions, SKF proposes a shortcut (macro) to achieve that goal.
The line in the script is not syntax colored because it is a macro and not a standard instruction.
TEST phase declaration :
// Step 4 TEST : |
The TEST phase groups the main test instructions. The following instructions will interact with the SUT (System Under Test) and the resources created during the SETUP phase remain available.
If an instruction fails, the test will end and the status displayed in the test result will be set according to the nature of the error.
Execution of the query :
// Step 5 EXECUTE execute WITH query ON my_database AS raw_result |
We use the query created during SETUP and execute it against the database. The name of the database here is my_database.
The resulting data are stored in the context under the name supplied at the end of the instruction (raw_result).
Data transformation :
// Step 6 CONVERT raw_result TO dataset.dbunit AS actual.dataset |
In step 3 we prepared the (expected) data, formatted as a DbUnit dataset. If we are to compare the actual data with the expected data, we must first convert the actual data to a suitable type. In this case it must be formatted as a DbUnit dataset.
Perform the comparison :
// Step 7 ASSERT actual.dataset IS equal WITH expected.dataset |
Now we’re all set to proceed and test the data against each other. The status of the test will depend on the status of that comparison.
If the comparison fails, the test will be flagged as failed, while if the comparison is a success the script continues to the next instruction.
Here there are no further instruction and the test will terminate with SUCCESS status.
Some more insights¶
So now you should have a glimpse of what an SKF script is made of.
There is a TEARDOWN phase too which is optional (just like SETUP phase) but it was not used in this example.
When looking closer at an instruction (e.g. step 5), we can distinguish two kinds of elements : the tokens (red words) and the variable elements (black, blue, pink and yellow words).
The tokens never change whereas identifiers are variable and refer to elements available in the script, including :
- A file or other physical resource (e.g. step 2 : queries/sql/select.sql).
- The assertion type : a command or a converter (e.g. step 5 : EXECUTE execute WITH query ON my_database AS raw_result).
- The resource type (e.g. step 6 : CONVERT raw_result TO dataset.dbunit).
- The name of a target, a repository, an already loaded resource or a resource to be created (e.g. step 5 : EXECUTE execute WITH query ON my_database AS raw_result).
Basically the tokens tell the engine to execute or activate some components and make them interact with each others.