Parser Template Syntax

A parser template is a JSON structure:

Its fields specify the properties of a test execution item that Zephyr will create for a test run:

Field	Description
status	A string that specifies the test status. Can be an arbitrary string. Typical values are Passed, OK, Failed, Failure, and so on. For more information, on how Zephyr checks if a test failed or not, see below.
statusExistPass	An additional indicator of the test status. Can be `true` or `false`. For more information, on how Zephyr treats this field value, see below.
statusString	An expected value for the status field. Zephyr uses this field to check if a test failed or not. See below.
statusFailAttachment	An additional description of test results used when a test failed. Typically, has an extended error message or a call stack for a failed function. Zephyr saves this extended description to a file and then attaches this file to an automation item:
statusPassAttachment	An additional description of test results used when a test passed. Typically, has information on the test case name and execution time. Zephyr saves this extended description to a file and then attaches this file to an automation item. See the image above.
packageName	This property is used only if you commanded Zephyr to create a package-like hierarchy of test execution items. The property specifies the name of the last level in the hierarchy.
testcase name	The name of the executed test case. Will be displayed in the Name column of the Test Execution screen in Zephyr.
tag	A string of tags set for the test in the test results file. Zephyr pulls these values, parses and adds them to your test case. You will see them in the Tags attribute of the test case. Test results can have one or multiple tags: One tag: <testcase> ... <tag>sample1</tag> ... </testcase> Multiple tags: <testcase> ... <tags> <tag>sample1</tag> <tag>sample2</tag> </tags> ... </testcase> Depending on the format of test results, you use different patterns to parse the tag values: One tag Sample contents of the results .xml file: `<testsuite>` `<testcase>` `...` `<tag>sample1</tag>` `...` `</testcase>` `</testsuite>` Parser template (as you can see, it is similar to patterns used for other elements): `tag: "${testsuite.testcase.tag}"` Multiple tags Sample contents of the results .xml file: `<testsuite>` `<testcase>` `...` `<tags>` `<tag>sample1</tag>` `<tag>sample2</tag>` `</tags>` `...` `</testcase>` `</testsuite>` You need to combine the `tags/tag` values into a single string to assign it to the `tag` item. To do this, you use the `group_concat(…)` function. It has the following parameters: `group_concat(path.to.parent.element, child-element, 'separator')` For example: `tag: ${group_concat(testsuite.testcase.tags, tag, ' ')}` The pattern above will extract `tags/tag` values, concatenate them into a single string and use spaces as a separator. A Zephyr test case will get the following Tags attribute: `sample1 sample2`. The default parser template has a tag pattern for parsing tags from Cucumber test results. If you use another framework or tool to run your tests, please change the template accordingly. The Tags attribute of a Zephyr test case is limited to 4,000 characters.
skipTestcaseNames	An XML file can have information on one or multiple test cases. By default, Zephyr will create a test execution item for every test case it finds in the XML file. This field is a string of test case names that which Zephyr will skip and for which it will not create a test run item. The names are case-sensitive. Separate multiple test case names with a comma. Don’t put extra spaces around test case names.
requirements id	An array of requirement IDs or alternative IDs with which a test run is linked. IDs should start with the `ID_` prefix, for example, `ID_17` or `ID_74`. Alternative IDs start with the `AltID_` prefix, for instance, `AltID_MYPROJ-234` or `AltID_simpleTest`. Often, alternative IDs are used to indicate the Jira ticket to which a requirement relates, so the `AltID_` string includes the project name and ID of that Jira ticket.
attachments filePath	An array that specifies additional files to be attached to the item. You should specify the path in terms of the computer, where the test ran. The path can be relative or absolute. If you use a relative file name, then it should be relative to the folder, where the test result XML file is located.
strict	Affects XML node matching with $-expressions. If `strict` is `true`, `${A.B.C}` will search for the specified nodes only within direct children of a parent node. If `strict` is `false` (the default value), all $-expressions in the template work recursively, that is, `${A.B.C}` will find B nodes on any level inside A, and find C nodes on any level inside B nodes. Depending on the XML file structure, non-strict templates may cause creation of extra test cases, which may or may not be desired. See the example below.

How Zephyr determines if a test failed or passed

Zephyr uses the following field values to determine the overall test result:

status
statusExistPass

statusString

The status field indicates the test results briefly. It might have or have no contents (for instance, the expression you use can refer to a non-existing element in the resulting XML file, or this expression can return an empty string). The other two fields specify how Zephyr treats the status value.

If statusString is null …

	`status` has contents	`status` has no content
`statusExistPass: true`	Test passed	Test failed
`statusExistPass: false`	Test failed	Test passed

If statusString is some string …

Zephyr uses statusString as an expected value for status:

If status is not equal to statusString, then Zephyr considers the test failed.
If status is equal to statusString, then Zephyr checks the statusExistPass property:
- If it is true, the test passed.
- If is false, the test failed.

Examples

Example 1. Custom test case name

Suppose, you want the test execution item’s name to include both the test suite name and the test case name. In this case, you can use an expression like this (the “-” symbol will be a separator in the resulting name):

…
"testcase": {
    "name": "${testsuite:name}-testsuite.testcase:name"
}
…

Example 2. Include additional data

You may want to retrieve extra properties from the XML file and store them along with a test execution item. To do this, specify their names in the statusFailAttachment or statusPassAttachment property. For example:

… 
statusFailAttachment: "name: ${testsuite.testcase:name} \ntime: ${testsuite.testcase:time}\ndata: ${testsuite.testcase.message}" 
…

Example 3. Handle Error and Fail tags

If you want Zephyr to set the test status to Fail when the Error and Failure tabs are used, you need to create a parser template that will do that. To do that, use the following custom template, send the following API request to your Zephyr server:

POST http://{your-zephyr}/flex/services/rest/latest/parsertemplate

Here, your-zephyr is the IP address or host name of your Zephyr server.

Use the following payload for this request:

{
   "name": "custom-junit",
   "jsonTemplate": [
      {
         "requirements": [
            {
               "id": "${testsuite.testcase.requirements.requirement}"
            }
         ],
         "statuses": [
            {
               "statusId": "2",
               "attachmentText": "${group_concat(testsuite.testcase,failure,'\n')}",
               "status": "${group_concat(testsuite.testcase,failure,'\n')}"
            },
            {
               "statusId": "2",
               "attachmentText": "${group_concat(testsuite.testcase,error,'\n')}",
               "status": "${group_concat(testsuite.testcase,error,'\n')}"
            },
            {
               "default": true,
               "statusId": "1",
               "attachmentText": "classname: ${testsuite.testcase:classname} name: ${testsuite.testcase:name} time: ${testsuite.testcase:time}"
            }
         ],
         "skipTestcaseNames": "",
         "packageName": "${testsuite.testcase:classname}",
         "testcase": {
            "name": "${testsuite.testcase:name}"
         },
         "attachments": [
            {
               "filePath": "${testsuite.testcase.attachments.attachment}"
            }
         ]
      }
   ]
}

Example 4. Using the “strict” option

Suppose, a test case's child nodes include status nodes. You can force the parser ignore them, and thus avoid creating individual test cases for such status nodes while parsing test results. To do that, set the new strict option to true in your parser template: "strict": true. If you use the default value (false), a new test case will be created for each status node on all levels.

{
  "jsonTemplate": "[
      {
        \"statuses\":[
            {
              \"statusId\":\"2\",\"attachmentText\":\"Name: ${robot.suite.test:name} 
              \\nResult:${robot.suite.test.status:status} \\nMessage: ${robot.suite.test.status}\",\"status\":\
              "${robot.suite.test.status:status}\",\"statusString\":\"FAIL\"},{\"statusId\":\"1\",
              \"attachmentText\":\"Classname: ${robot.suite:name} \\nTestcaseName: ${robot.suite.test:name}
              \\nResult: ${robot.suite.test.status:status}\",\"default\":true}
              ],
              \"skipTestcaseNames\":\"\",\"packageName\":\"${robot.suite:name}\",\"testcase\":{\"name\":
              \"${robot.suite.test:name}\"
              },
              \"strict\":true
            }
        ]",
  "name": "robot"
}

Example 5. Handel the tag <failure type=””

You may have to create a custom template of the Junit when a Junit xml have <failure type="" /> instead of <failure message="" />.

For example:

{
   "name": "junit temp",
   "jsonTemplate": "[{\"requirements\":[{\"id\":\"${testsuite.testcase.requirements.requirement}\"}],\"statuses\":[{\"statusId\":\"2\",\"attachmentText\":\"${testsuite.testcase.failure}\",\"status\":\"${exists(testsuite.testcase.failure)}\",\"statusString\":\"true\"},{\"default\":true,\"statusId\":\"1\",\"attachmentText\":\"classname: ${testsuite.testcase:classname} name: ${testsuite.testcase:name} time: ${testsuite.testcase:time}\"}],\"skipTestcaseNames\":\"\",\"packageName\":\"${testsuite.testcase:classname}\",\"testcase\":{\"name\":\"${testsuite.testcase:name}\"},\"attachments\":[{\"filePath\":\"${testsuite.testcase.attachments.attachment}\"}]}]"
   }

More examples

To get the idea of how to perform this or that action, explore the preconfigured templates that comes along with Zephyr. See how you can get them.

In this section: