Best Practices¶
TestScript Path Evaluation (XPath, JSONPath)¶
The TestScript assert.path definition is “The XPath or JSONPath expression to be evaluated against the fixture representing the response received from server.”
Touchstone supports both XPath and JSONPath expressions for all the TestScript path elements: “variable.path”, “assert.compareToSourcePath” and “assert.path”. This support includes the ability to evaluate XPath and JSONPath against fixtures formatted as either XML or JSON. For example, a JSONPath expression can evaluate against an XML formatted fixture or, an XPath expression can evaluate against a JSON formatted fixture.
When Touchstone performs a path expression evaluation where either of these conditions occur, the path expression is first converted from JSONPath to XPath or vice versus. This path expression conversion is performed following basic syntax equivalency rules where known conversion exceptions are rejected. The following table provides some illustrative conversion examples:
XPath |
JSONPath |
|
|---|---|---|
entry[1]/resource/Patient/name/family |
<-> |
entry[0].resource.name.family |
/Bundle/entry[1]/resource/Patient/id |
<-> |
$.entry[0].resource.id |
entry[position() = 1]/resource/Patient/name/family |
|
|
meta/tag[system==’http://terminology.hl7.org/CodeSystem/v3-ObservationValue’)]/code |
<-> |
$.meta.tag[?(@.system=’http://terminology.hl7.org/CodeSystem/v3-ObservationValue’)].code |
It is highly recommended to define XPath expressions against known XML formatted fixtures and, JSONPath expressions against known JSON formatted fixtures. If the fixture format cannot be definitively known, avoid complex XPath and JSONPath expressions or use FHIRPath expressions.
Version Control¶
Although Touchstone does detect changes to uploaded test scripts and its dependenct resources, the versioning in Touchstone is rudimentary. You should not rely on Touchstone as the sole repository for your test scripts.
It is highly recommended to manage your test scripts in a proper Version Control system (e.g. Git, Subversion, TFVC, etc.) outside of Touchstone. These tools are specifically engineered to manage versioning, conflicts, branching, concurrent commits, etc.
In the event that your test group gets corrupted in Toucshtone through concurrent uploads by different users, you could re-upload the test group using the right version in your Version Control system.
Location¶
It is recommended to store the fixtures and rules for your test scripts in a separate folder and call the folder “_references”. This will make it easier to tell apart these definitions from test scripts when browsing.
Paths to resources¶
For resources that your test scripts are depending on and that are specific to the test scripts in the test group you’re uploading, it is highly recommended to use relative paths to reference those resources. Doing so will allow you to change the location of your test groups much more easily.
If you used absolute paths, then you’d have to go through all your test scripts and change the paths of the referenced fixtures. That can be time-consuming and error prone.
In the test script snippet below where a fixture is defined, we’re using a relative path:
If you’re defining resources that are going to be used across many test groups (especially test groups shared among different Org Group members), it would be better to define the resources in a separate test group and use absolute paths to refer to those resources.
In the test script snippet below where a rule is defined, we’re using an abolute path. The rule is used across many test groups in Touchstone.
