05.04 - Converters

Since converters create resources of a category 'B' using a resource of category 'A', the documentation on converters follows a pattern 'from A to B' (e.g. from 'file' to 'query.sql'). Most of the time knowing the category of the resources you have and/or you want to obtain will be enough to find which converter you need using the following list. However remember that a converter is fully qualified by his signature: the only way to disambiguate situations where multiple converters consuming and producing the same categories could apply is to specify the name of the converter too.

Like the other engine components, a converter is configurable. It means that you can pass parameters and tweak the operation.

From file...

A test project is mostly made of files, including the test resources. This is why the 'file' category is so important and overly processed by converters.

• • to bundle

Category-Name: unchecked

What: This 'unchecked' converter will convert a resource of category 'file' to a resource of category 'bundle'. It checks during the conversion that the resource to convert is really pointing to a directory.

CONVERT {resourceToConvert<Res:file>} TO bundle (unchecked) AS {converted<Res:bundle>} [ USING {mainPath<Res:file>} ]

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references the root directory. This root directory should contains the whole files and directories of the bundle. (Resource of category file)

  • mainPath<Res:file> (OPTIONAL): The name of the configuration resource. The content of the file should be: mainpath:relativePathToMainFile (Note: you could use an inline definition). This path to main file should be relative to the directory given as the root directory.

Output:

• • converted<Res:bundle>: The name of the converted resource (Resource of category bundle).

Example: (using the USING clause and an inline definition)

LOAD path/to/rootDirectory AS bundle.file

CONVERT bundle.file TO bundle (unchecked) AS bundle.bundle USING $(mainpath:relative/path/to/mainFile.txt)

• • to csv

Category-Name: structured

What: This 'structured' converter will convert a resource of category 'file' to a resource of category 'csv'. It checks during the conversion that the resource to convert is really pointing to a csv file.

CONVERT {resourceToConvert<Res:file>} TO csv (structured) AS {converted<Res:csv>} [ USING {mainPath<Res:file>} ]

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references the csv file. (Resource of category file)

  • mainPath<Res:file> (OPTIONAL): The name of the configuration resource.

Output:

• • converted<Res:csv>: The name of the converted resource (Resource of category csv).

Example:

LOAD csv1/mycsv.csv AS mycsv.file

CONVERT mycsv.file TO csv (structured) AS mycsv.csv

• • to directory

Category-Name: filesystem

What: This 'filesystem' converter will convert a resource of category 'file' to a resource of category 'directory'. It checks during the conversion that the resource to convert is really pointing to a directory.

CONVERT {resourceToConvert<Res:file>} TO directory (filesystem) AS {converted<Res:directory>}

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references a directory.(Resource of category file)

Output:

• • converted<Res:directory>: The name of the converted resource (Resource of category directory).

Example:

LOAD path/to/Directory AS directory.file

CONVERT directory.file TO directory (filesystem) AS directory.directory

• • to file (using param.relativedate)

Category-Name: param.relativedate

What: This 'param.relativedate' converter will convert a resource of category file to a resource of category file. In the context of the aging factor a mechanism has been set-up in Squash-TA to manage dates. It consists in replacing dates of the data set with formulas of type:

${function}

where function is :

• • now().format(f): return the execution date at the 'f' format

  • now().addDay(n).format(f): return the execution date + 'n' days (positiv or negativ) at the 'f' format

  • now().addMonth(n).format(f): return the execution date + 'n' months (positiv or negativ) at the 'f' format

  • now().addYear(n).format(f): return the execution date + 'n' years (positiv or negativ) at the 'f' format

Note: Date and time formats are specified by date and time pattern strings, as described here.

Examples:

The fourth parameter list all the non working days, you must declare the date like yyyy-mm-dd and separate them with a comma.

Note: the "to file(param)" converter must only use text files. If you want to use it on a bundle that contains binary files, you must exclude them in the converter. You can use either squashtest.ta.param.exclude OR squashtest.ta.param.include parameters.

The converter transforms formulas '${function}' in valid dates at the execution.

CONVERT {resourceToConvert<Res:file>} TO file (param.relativedate) [USING {properties<Res:properties>}] AS {converted<Res:file>}

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references a file. All the dates of the file must have been replaced by formulas like '${function}'.

  • properties<Res:properties>: If the resourceToConvert is a bundle containing binary file, this properties file must contain either the squashtest.ta.param.exclude OR the squashtest.ta.param.include parameter. Both of them are regular expression the file contained in the bundle must match to be or not to be treated by this converter.

Output:

• • converted<Res:file>: The name of the converted resource (Resource of category file). The finale resource is the same than the input resource, the difference is that formulas have been replaced with valid dates.

Example:

LOAD path/myfile AS myfile.file

CONVERT myfile.file TO file (param.relativedate) AS myfile2.file

• to file (using param)

Category-Name: param

Since: 1.6.0

What: This 'param' converter will convert a resource of category file to another resource of category file. After the conversion all the placeholder, whose key was found in the properties resource given in the USING clause, should have been replace by it's valid value (the value associate to the key in the property resource file). The initial File resource could be a file or a directory. If it's a directory then all the file contained in this directory should be process. Here are the rule used:

• Placeholder syntax: ${key}

• Authorized characters for properties key: letters (a-zA-Z), digits (0-9), underscore (_), dot (.) and dash (-)

• The convert instruction could take one or many properties file AND one or many inline statements

• If a property key is defined many times, then it's the last stated which is take into account

• If a placeholder is surrounding with character @, then the placeholder is escaped. For example if we have in the file to process: @${test}@, then we will have in the final file : ${test}

• If a placeholder key is not found in the properties key, then the placeholder is escaped.

Note: the "to file(param)" converter must be used only text files. If you use it on a bundle that contains binary files then you must exclude them. To do this you can use either squashtest.ta.param.exclude OR squashtest.ta.param.include parameters.

CONVERT {resourceToConvert<Res:file>} TO file (param) USING {properties<Res:properties>} AS {converted<Res:file>}

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references a file.

  • properties<Res:properties>: This properties file contains the mapping key-value.

  • If the resourceToConvert is a bundle containing binary file, this properties file must also contain either the squashtest.ta.param.exclude OR the squashtest.ta.param.include parameter. Both of them are regular expression the file contained in the bundle must match to be or not to be treated by this converter.

Output:

• • converted<Res:file>: The name of the converted resource (Resource of category file). The finale resource is the same than the input resource, the difference is that the placeholder ${...} have been replaced with their valid values.

Example:

LOAD sahi/placeholder.properties AS placeholder.file

CONVERT placeholder.file TO properties(structured) AS placeholder.properties

LOAD sahi/main/simple-script.sah AS sahiFile

CONVERT sahiFile TO file(param) USING placeholder.properties AS processedSahiFile

CONVERT processedSahiFile TO script.sahi(script) AS suite

where :

• placeholder.properties contains: c3p0.data=Using c3p0

• simple-script.sah contains: _click(_link("${c3p0.data}"));

Then :

• processedSahiFile should contains: _click(_link("Using c3p0"));

  • to properties

Category-Name: structured

What: This 'structured' converter will convert a resource of category 'file' to a resource of category 'properties'.

CONVERT {resourceToConvert<Res:file>} TO properties (structured) AS {converted<Res:properties>}

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references the '.properties' file (list of properties key / value) where the used separator is '='.

Output:

• • converted<Res:properties>: The name of the converted resource (Resource of category properties)

Example:

LOAD path/myfile.properties AS myfile.file

CONVERT myfile.file TO properties (structured) AS myfile.prop

• • to script.java

Category-Name: compile

What: This 'compile' converter will convert a resource of category 'file' to a resource of category 'script.java'.

CONVERT {resourceToConvert<Res:file>} TO script.java (compile) AS {converted<Res:script.java>} [ USING {mainPath<Res:file>} ]

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references the root directory of the java code bundle which contains.resources and the java's source code.

  • mainPath<Res:file> (OPTIONAL): The name of the configuration resource. It represents a configuration file containing java compilation options.(Possible options are those of the Java compiler present on the machine). In this file options can be written:

    • In line separated with a space character

    • One option per line

    • A mix of the two

Output:

• • converted<Res:script.java>: The name of the converted resource (Resource of type script.java). It contains the compiled java code.

Example:

LOAD path/to/javaBundle AS bundleJava.file

CONVERT bundleJava.file TO script.java (compile) AS bundleJava.compiled USING $(mainpath:relative/path/to/compileOptions)

• • to xml

Category-Name: structured

What: This 'structured' converter will convert a resource of category 'file' to a resource of category 'xml'. It checks during the conversion that the resource to convert is really xml category.

CONVERT {resourceToConvert<Res:file>} TO xml (structured) AS {converted<Res:xml>}

Input:

• • resourceToConvert<Res:file>: The name (in the context) of the resource which references the xml file.

Output:

• • converted<Res:xml>: The name of the converted resource (Resource of category xml).

Example:

LOAD myfile.xml AS myfile.file

CONVERT myfile.file TO xml (structured) AS myXMLfile