Instructions


The valid instruction set is defined as follow :

Blank lines (no instruction)

Comments : starting by a double slash ‘//’ (no instruction)

DEFINE $(raw data) AS {nameInTheContext<Res:File>}

LOAD {path_To_Resource} [ FROM {resourceLibrary<Rep>}] [ AS {nameInTheContext<Res:File>} ]

CONVERT {resourceToConvert<Res>} TO {<Cat:Res>} ( {<Conv>} ) [ USING {config<Res>} ] AS {convertedResource<Res>}

EXECUTE {<Cmd>} WITH {<Res>} ON {<Tar>} [ USING {config<Res>} ] AS {result<Res>}

ASSERT {resourceToTest<Res>} ( IS | HAS | DOES ) {<Asr>} [ ( WITH | THAN | THE ) {expectedResult<Res>} ] [ USING {config<Res>} ]

VERIFY {resourceToTest<Res>} (IS | HAS | DOES ) {<Asr>} [ ( WITH | THAN | THE ) {expectedResult<Res>} ] [ USING {config<Res>} ]

Note

The VERIFY instruction is available since Squash TA 1.6.0. It’s a new type of assertion instruction.

Syntax convention

  • Red words : They represent the language tokens. They are in uppercase and they never change.

  • Black words : They represent a physical resource.

  • Blue words : Identifiers which point to a resource component. They have the following structure : {name<Type:Category_name>} or {name<Type>} or {<Type>} with :

    • name : A name which corresponds to the element that should be pointed by the identifier.
    • Type : The component type of the element pointed by the identifier : Res for resources, Tar for targets, Repo for repositories.
    • Category_Name : The category of the component which wraps the pointed element.
  • Pink words : Identifiers which reference an engine component : {<Cmd>} for commands, {<Asr>} for assertions and {<Conv>} for converters.

  • Yellow word : The category of the expected resource after a conversion.

  • [ ] : Element inside this square brackets can be omitted in some cases.

Note

For convenience, name is often use instead of identifier in the documentation.

One instruction per line and one line per instruction. In other words, the end of line means that the instruction ends here and will be parsed as is. The language tokens are case-insensitive and accept inline resource definitions (just like in a DEFINE instruction, see below). On the other hand the identifier we discussed above are case-sensitive (i.e. you should respect lowercase and uppercase letters).

An instruction can be divided into clauses. Some are mandatory while others are optional. A clause can be recognized by its language token (uppercased words) and an identifier that immediately follows it.

For each instruction the most obvious mandatory clause is the first one that states which instruction you are referring to. This first clause is also named head clause.

The optional clauses are stated here between enclosing brackets ‘[]’.

Caution

Those brackets aren’t part of the language and just serve the purpose of delimiting those optional clauses.

Except for the head clause which determines the kind of instruction, the order of other clauses is not fixed.

Also note that the DSL does not support nested instructions.



Comments

TA Scripts can contain comments. They start with a ‘//’. To write a multiline comment, start each line of the comment with the ‘//’. It’s not allowed to write a comment on the same line that an instruction.

Example of a not allowed comment :

LOAD example.txt AS example.file //This comment is not allowed


DEFINE instruction / Inlined instruction $(…)

DEFINE $(raw data) AS {nameInTheContext<Res:File>}

> Input :

  • raw data : A string (If there is more than one line, each line must be separate with ‘\n’)

> Output :

  • {nameInTheContext<Res:File>} : The identifier of the resource created in the test context.

The DEFINE instruction is rarely used but may come handy. Basically it let you define any text content directly within the script, and binds it to a name.

This content will be stored in the Test context as a file resource, under the name supplied in AS clause.

This resource will be available throughout the whole test but won’t exist anymore when another test begins.

Example 1 : Simple DEFINE resource

DEFINE $(select * from MY_TABLE) AS query.file

Example 2 : Structured DEFINE resource

DEFINE $(some letters, a tabulation t and n the rest after a linefeed.) AS structured-text.file

A more common use for resource definition is to simply inline them within the instruction that will use it.

Example : Resource inlined in a CONVERT instruction

CONVERT $(select * from MY_TABLE) TO query.sql AS my_query.query.sql

The advantage of explicitly using DEFINE is to bind the newly created file resource to a name, thus allowing you to refer to it again later in the script. If you won’t need to reuse that resource, an inlined definition is fine.

Inlined resources are notably useful when passing configuration to Engine Components. Engine Components sometimes need a few text to be configured properly, which can be inlined instead of explicitly creating a file for it.



LOAD instruction

LOAD {path_To_Resource} [FROM {resourceRepository<Rep>}] [AS {nameInTheContext<Res:File>}]

> Input :

  • {path_To_Resource} : The path to the resource to load
  • {resourceRepository<Rep>} : The name of the resource repository in which is located the resource to load.

> Output :

  • {nameInTheContext<Res:File>} : The name of the resource created in the test context.

The LOAD instruction will search for a resource in all of the existing repositories. When it is finally found it will be brought to the test context as a file resource. If no AS clause is supplied, the name of this file resource will be the name under which it was searched for (including folder hierarchy if it was hidden in a deep file tree).

The path of the resource doesn’t need to be a full URL, as that kind of details will be handled by the repositories. In case of a repository looking for the file system it generally have a base directory, you can then omit the full path and only supply a path relative to the base directory.

Also note that the directory separator is a slash ‘/’ regardless of the underlying operating system. More precisely, no backslashes ‘' needed under Windows. Backslashes aren’t a valid character for an identifier and will be rejected anyway.

If by chance two or more repositories could answer the query (i.e. if a given file name exists in two file systems, each of them being addressed by a distinct repository), the file resource returned depends on which of them replied first. Consider it as random, and if problems happen you could be interested in the FROM clause (see below).

If the loading fails because the resource was not found, the test will end with a status depending on the phase it was executed in.

The FROM clause is optional. If specified, instead of searching every repository for the resource it will search only the one you specified. It may speed up file retrieval if some of repositories are very slow or busy.

The AS clause is optional. If specified, instead of binding the new file resource to the name used in the first clause, the engine will bind it to this alias instead.

Example 1 : Simple file loading

LOAD data-folder/myfile // that’s it, the file resource will be accessible under the name ‘data-folder/myfile’

Example 2 : Load with alias

LOAD long/path/to/the/resource AS my_resource.file

Example 3 : Load from a specific repository

LOAD myfile FROM my.repository


CONVERT instruction

CONVERT {resourceToConvert<Res>} TO {<Cat:Res>} ( <Conv> ) [ USING {config<Res>} ] AS {convertedResource<Res>}

> Input :

  • {resourceToConvert<Res>} : The name of the resource to convert
  • {<Cat:Res>} : The category of the resource expected after the conversion.
  • <Conv> : The category of the converter used for the conversion.
  • {config<Res>} : The name of the complementary resource needed for the conversion.

> Output :

  • {convertedResource<Res>} : The name of the converted resource.

The CONVERT instruction will take an input resource and produce a new resource, that will then be available under the name mentioned in the AS clause. The resource must exist in the Test context beforehand (for instance as resulting from a LOAD instruction).

Remember that no Engine Component will ever modify the input resource, and it will still be available as it was after the conversion is over.

Depending on the invoked converter, a CONVERT instruction will perform at least one of the two operations :

  • Produce a resource with the same data than the input resource but wrapped in a different category.
  • Produce a resource with new data based on the input resource but the category stays the same.

Some converters do even both. In any case you should refer to the documentation of this converter.

The TO clause is mandatory, as it is where you specify the category of the output (which may be the same than the category of the input resource).

However in some cases, it may happen that two or more converters, accepting the same input and output categories, exist together in the engine, thus leading to an error.

In such cases one should deambiguate the situation by specifying which specific converter you need.

This is the only case where you need to expand the full signature of that converter. You can specify that converter by immediately appending its name to the output category, surrounded by parenthesis ( ).

Warning

Even in the cases where you don’t need to specify the converter name, we highly advise you to do it.

Indeed this could prevent you from encountering problems if a new converter with the same input and output is created (making mandatory to specify the converter category).

The optional USING clause lets you specify an arbitrary number or resources that will be treated as configuration for this operation. The category of resources, or which informations they should convey depends on the converter being used. Having a look at the documentation of that converter is certainly useful.

Example 1 : Simple CONVERT from file to CSV

CONVERT mydata.file TO csv AS mydata.csv

Example 2 : CONVERT with configuration

CONVERT my_result.resultset TO dataset.dbunit USING $(tablename : MY_TABLE) AS mydata.csv

Example 3 : CONVERT with an inline definition

CONVERT $(select * from MY_TABLE) TO query.sql (query) AS my_query.query.sql


EXECUTE instruction

EXECUTE {<Cmd>} WITH {<Res>}` ON {<Tar>} [ USING {config<Res>} ] AS {result<Res>}

> Input :

  • {<Cmd>} : The command to execute.
  • {<Res>} : The name of the resource to use with the command.
  • {<Tar>} : The name of the target.
  • {config<Res>} : The name of the complementary resource needed to use with the command.

> Output :

  • {convertedResource<Res>} : The name of the resource generated by the command.

The EXECUTE instruction will perform an operation involving a resource (WITH clause), on a given target (ON clause). The result of this operation, if any, will be returned as a resource published in the Test context under the name supplied in the AS clause.

If the operation returns some results, the actual type of the resulting resource depends on the command being executed, so you should refer to the documentation of that command to know how to handle it in the rest of the test.

The optional USING clause lets you specify an arbitrary number of resources that will be treated as configuration for this operation. The category of resources, or which informations they should convey depends on the command being used.

You MUST provide an input resource, a target and an alias for the result, even if the command does not actually use all of theses features.

Example 1 : Command using a dummy identifier for the result name (because that command doesn’t return any)

EXECUTE put WITH my_file.file ON my_ftp AS no_result_anyway

Example 2 : Command with configuration

EXECUTE get WITH $() ON my_ftp USING $(remotepath : data/the-file.txt, filetype : ascii) AS my_new_file.file

Note that in the last example we used a dummy inlined resource $(), since in that case the get command doesn’t use any input resource.



Assertion instructions (ASSERT / VERIFY)

ASSERT {resourceToTest<Res>} ( IS | HAS | DOES ) {<Asr>} [ ( WITH | THAN | THE ) {expectedResult<Res>} ] [ USING {config<Res>} ]

VERIFY {resourceToTest<Res>} ( IS | HAS | DOES ) {<Asr>} [ ( WITH | THAN | THE ) {expectedResult<Res>} ] [ USING {config<Res>} ]

> Input :

  • {resourceToTest<Res>} : The name of the resource to validate.
  • {<Asr>} : The kind of assertion to use.
  • {expectedResult<Res>} : The name of the reference resource.
  • {config<Res>} : The name of the complementary resource needed for the assertion.

The assertion instructions will perform a test on the supplied resource, optionally compared to another resource.

If the assertion is successful, the test will continue.

If the assertion failed or finished in error :

  • In ASSERT mode, the execution of the current test phase is stopped. The teardown test phase is then executed (if it was not already in this teardown test phase).
  • In VERIFY mode, the next instructions is executed.

The test final status will always be the most severe status of its instructions.

For details on the execution workflow and test status please see this page.

The VERIFY assertion mode is available since Squash TA 1.6.0. Before only the ASSERT mode was available.

Note that, unlike other instructions, an assertion can have multiple choices.

The first multi-token clause is the one identifying the assertion ({<Asr>}, in the syntax above).

The second one is identifying the secondary resource ({expectedResult<Res>}, in the syntax above).

In either case you only need to pick one, and it makes sense to pick the one that fits the most to the grammar of the instruction (see examples below).

The optional (WITH | THAN | THE) clause specifies another resource. In that case, the primary resource will be compared to the secondary resource.

If that clause is used, then we talk of a ‘binary assertion’, and the primary resource usually represents the actual result from the SUT while the secondary result represents the expected result.

If no (WITH | THAN | THE) clause is used, the resource and the assertion are assumed self-sufficient to perform the check. We then talk of a ‘unary assertion’.

The optional USING clause let you specify an arbitrary number or resources that will be treated as configuration for this operation. The category of resources, or which information they should convey depends on the assertion being used, so having a look at the documentation of that assertion is certainly useful.

Example 1 : Simple unary assertion

ASSERT my_result.result.sahi IS success

Example 2 : Simple binary assertion (awkward)

ASSERT actual_result.dataset.dbunit IS contain WITH expected_result.dataset.dbunit

In this example, the sentence is grammatically wrong but it will work as expected. You might prefer the following syntax :

Example 3 : Simple binary assertion (better)

ASSERT actual_result.dataset.dbunit DOES contain THE expected_result.dataset.dbunit

This version does exactly the same thing but is better.