Commons component plugin - Converters

Since converters create resource of B type using a resource of A type, 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 file type resource to a bundle type resource. 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 (file type resource).
  • 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 (bundle type resource).

Example (with 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 file type resource to a csv type resource. 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 (file type resource).
  • mainPath<Res:file> (OPTIONAL) : The name of the configuration resource. given as the root directory.

> Output :

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

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 file type resource to a directory type resource. 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 (file type resource).

> Output :

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

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 file type resource to another file type resource. In the context of the aging factor a mechanism has been set-up in SKF 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 (positive or negative) at the ‘f’ format.
  • now().addMonth(n).format(f) : return the execution date + ‘n’ months (positive or negative) at the ‘f’ format.
  • now().addYear(n).format(f) : return the execution date + ‘n’ years (positive or negative) at the ‘f’ format.
Examples with an SKF script run on 16/05/2012 :
Function Result
now().format(yyyyMMdd) 20120516
now().addDay(1).format(dd/MM/yyyy) 17/05/2012
now().addDay(-2).addMonth(1).addYear(-3).format(dd MMMM yyyy) 14 June 2009

Since 1.7.0, you can overwrite the default locale of your date, with a language code or a language and a country :

  • now().[…].format(f, l) : return the date at the ‘f’ format in the ‘l’ language, where ‘l’ is a lower-case, two-letter code as defined by ISO-639.
  • now().[…].format(f, l, C) : return the date at the ‘f’ format in the ‘l’ language of the ‘C’ country, where ‘l’ is a lower-case, two-letter code as defined by ISO-639 and ‘C’ is an upper-case, two-letter code as defined by ISO-3166.
Function Result
now().addMonth(1).format(dd MMMM yyyy, fr) 16 juin 2012
now().addMonth(1).format(dd MMMM yyyy, de, DE) 16 Juni 2012

Since 1.10.0, you can manipulate the date in the ${function} with 3 new options :

  • The ensureWorkingDay($param) function adjusts the computed date to the nearest working day before or after the input date ($param must be replaced by AFTER or BEFORE).

  • The addWorkingDay(n) function allows to add a given number of working days to its input date (n is a positive or negative integer).

  • If you want to specify a date which is different from now(), you can use the following method :

    Example :

    LOAD folder/file AS templateData
DEFINE $(date-key=05051978) AS rawProperties
CONVERT rawProperties TO properties(structured) AS prop
CONVERT templateData TO file(param.relativedate) USING prop AS data

Written in the file to process : ${date(date-key,ddMMyyyy).addDay(-1).format(yyyy-MM-dd)}
Function Result
now().addMonth(4).ensureWorkingDay(AFTER).format(dd MMM yyyy, fr) 17 Septembre 2012
now().addMonth(4).ensureWorkingDay(BEFORE).format(dd MMM yyyy, fr) 14 Septembre 2012
now().addWorkingDay(10).format(dd MMM yyyy, fr) 30 Mai 2012

The Working days are read from component configuration through the USING clause.

Example of file :

  • org.squashtest.tf.plugin.commons.parms.data.WorkedSunday=false
  • org.squashtest.tf.plugin.commons.parms.data.WorkedSaturday=false
  • org.squashtest.tf.plugin.commons.parms.data.WorkedMonday=true
  • org.squashtest.tf.plugin.commons.parms.data.nonWorkingDays=2018-05-01,2018-12-25,2019-01-01

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

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.tf.param.exclude OR the squashtest.tf.param.include parameter. Both of them use regular expressions. According to the selected parameter, the file(s) matching the regex will or will not be treated by this converter.

> Output :

  • converted<Res:file> : The name of the converted resource (file type resource). 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 file type resource to another file type resource. 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-z;A-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.
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.tf.param.exclude OR the squashtest.tf.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 (file type resource). 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 file type resource to a properties type resource.

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 (properties type resource).

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 file type resource to a script.java type resource.

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 both

> 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 file type resource to a xml type resource. 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 (xml type resource).

Example :

LOAD myfile.xml AS myfile.file

CONVERT myfile.file TO xml (structured) AS myXMLfile