Commands for JSON Creation, Manipulation and Validation
If you are not familiar with JSON, it stands for JavaScript Object Notation, a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language. If you want to learn more about JSON, please click here.
In Worksoft SaaS the commands related to JSON can be used in the context of the following common use cases:
- You want to read the data from a Web Service (that returns a JSON document) and use the data as part of the automated tests running in Worksoft SaaS.
- You want your automated test running in Worksoft SaaS to read some values from the User Interface of your AUT and/or Data Files within Worksoft SaaS and feed such data into a Web Service (that accepts JSON document as input) that does some processing that is a precursor for any additional automated tests to be executed in Worksoft SaaS.
- When you need to store a relatively small set of key-value pairs, it may be more efficient for you to store the data in JSON format.
| Command | Purpose |
|---|---|
| jsonAppendToObject | This command is used to append values to the end of the indicated arrays within a JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH" |
| jsonAssertPathExists | This command is used to check if the given path exists within a JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH" |
| jsonAssertValidity | This command is used to check if the input provided is a valid JSON document. If the input is not a valid JSON document, the command fails with error "INVALID_JSON". |
| jsonCompare | This command is used to compare the JSON documents. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH" |
| jsonCreateObjectFromDataFile | This command is used to create a JSON Object from the contents of a data file. If the mentioned data file is not avaialble run fails with error "Datafile name provided in the 'Target' field field does NOT exist in the scope of the project". In Worksoft SaaS a data file is always associated to a data definition. Attributes/Fields in the data definition are converted to "Key" in the JSON document while the contents of the data file make up for "Value" in the JSON document. |
| jsonCreateObjectFromDataSet | This command is used to create a JSON document from the contents of a dataset. If the dataset mentioned in the variable is not created in the same run, then run fails with error "For one or more Instructions within the Test Run that use the "ddCreateDataset" command, the Dataset name provided in the 'Target' field does NOT exist in the scope of the <runname>" In Worksoft SaaS data set is a temporary storage area that consists of columns & rows. Column names makes up "Key" while row values make up "Value" in the JSON document |
| jsonExtractValuesByPaths | This command is used to retrieve data selected from the parts of the document matched by the path arguments. If the number of values returned are more than the columns in the dataset, command fails with error "The Number of columns returned are more than the number of attributes in the data definition |
| jsonGetDepth | This command is used to return maximum depth of the JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". |
| jsonGetLength | This command is used to get number of elements present in the JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH" |
| jsonInsertIntoObject | This command is used to insert data into a JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON" If the path indicates a nonexistent path in the JSON, it adds the value to the JSON if:: 1) A member is not present in an existing object. The member is added to the object and associated with the new value. 2) A position past the end of an existing array. The array is extended with the new value. If the existing value is not an array, it is auto wrapped as an array, then extended with the new value. Otherwise, a path/value pair for a nonexistent path in the document is ignored and has no effect. |
| jsonMergeObjects | This command is used to merge two or more JSON documents to a single document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON" Merging takes place according to the following rules 1) Adjacent arrays are merged to a single array. 2) Adjacent objects are merged to a single object. 3) A scalar value is autowrapped as an array and merged as an array. 4) An adjacent array and object are merged by autowrapping the object as an array and merging the two arrays. |
| jsonRemoveFromObject | This command is used to remove data from a JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON" The document produced by evaluating one path becomes the new value against which the next path is evaluated. It is not an error if the element to be removed does not exist in the document; in that case, the path does not affect the JSON. If the path is "$" or contain wildcard characters, command fails with error "One of the JSON Path is either Null or having wild card characters" |
| jsonReplaceKeysByPaths | This command is used to replace existing keys in the JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH" The document produced by evaluating one pair becomes the new value against which the next pair is evaluated. A path/value pair for an existing path in the document overwrites the existing document value with the new value. If the path is "$" or contain wildcard characters, command fails with error "One of the JSON Path is either Null or having wild card characters" |
| jsonReplaceValuesByPaths | This command is used to replace existing values in the JSON document. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If the path mentioned is not part of the JSON document, command fails with error "INVALID_JSON_PATH".The document produced by evaluating one pair becomes the new value against which the next pair is evaluated. A path/value pair for an existing path in the document overwrites the existing document value with the new value. If the path is "$" or contain wildcard characters, command fails with error "One of the JSON Path is either Null or having wild card characters" |
| jsonSearchValueOccurrence | JSONSearchValueOccurrence({Json/VariableName} || "val"(, path),VariableName) [path is OPTIONAL] If path is not given, then the search_string should be on the first level of JSON. The search_string "val" should be enclosed in Double quotes if the search_string is an Object or an Array. |
| jsonStoreArrayByIndex | This command retrieves values from JSON document using "index" as reference. [If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If index mentioned is not part of the JSON document, command fails with error "INDEX_NOT_PRESENT". If the found value is not an array type, then command fails with error "INCOMPATIBLE_TYPE" |
| jsonStoreArrayByName | This command retrieves values from JSON document using "name" as reference. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If arrayName mentioned is not part of the JSON document, command fails with error "KEY_NOT_PRESENT". If the found value is not an array type, then command fails with error "INCOMPATIBLE_TYPE" |
| jsonStoreObjectByIndex | This command retrieves object from JSON document using "index" as a reference. If the JSON document supplied in input is invalid, command fails with error "INVALID_JSON". If index mentioned is not part of the JSON document, command fails with error "INDEX_NOT_PRESENT". If the found value is not an object type, then command fails with error "INCOMPATIBLE_TYPE" |
| jsonUnquoteValue | This command is used to remove escape characters within the string. Escape Sequence Character Represented by Sequence \" A double quote (") character \b A backspace character \f A formfeed character \n A newline (linefeed) character \r A carriage return character \t A tab character \\ A backslash (\) character \uXXXX UTF-8 bytes for Unicode value XXXX |