New feature: manipulate variables using jq

Utilizing the power of jq, Assertible now supports manipulating and transforming variables before they're used in the test.

The need to modify or manipulate variables before they're used in a test run comes up frequently. To handle these use-cases, Assertible has adopted the powerful program jq. Using jq, it's possible to transform and operate on variables before the final value is used in a test run.

jq can be used to "slice and filter and map and transform structured data with the same ease that sed, awk, grep." ^[1]. And now, it can be used to modify variables in Assertible. Learn more about how it works and how to use it in the sections below:

• What you can do with jq
• Where you can use jq
• Next steps and future development

What you can do with jq

Transforming structured data into a format fit to use in your API's headers, query parameters, etc, is a use-case that comes up often. To outline a few of these scenarios, here's a few examples:

• Formatting a timestamp
• Adding or concatenating two or more fields
• Slicing strings or other values
• Finding the length of a string, array, or other values

Within the context of Assertible, all jq functionality from version 1.6 is available to use. See the jq user manual for a comprehensive list of functions. The one exception worth noting is that Assertible does not support functions that return multiple values -- or a stream of values. For example, assuming there is a variable named {{myVar}} whose value is the following JSON:

[{ "key": 1 }, { "key": 2 }, { "key": 3 }]

You cannot, then, use a jq function that operates and returns a value from each item in the array. Here are some concreate examples:

• Valid: . | length (returns: 3)
• Invalid: .[] | length (returns: 1, 1, 1)

Variables must resolve to a single value that can be injected into the test at the time it is run. Outside of this, however, you can use any other function supported by jq.

Where you can use jq

Assertible now supports a function that can be used anywhere a variable is used by calling the .jq(). See the documentation on test variables for more information on how they work. To make this more tangible, let's go over a few more examples.

• Usage in assertions: In the image below, jq is used to calculate the length of a string in an assertion.

  

  
  

• Usage in query parameters: This example uses the fromdate function to transform a datetime string into a unix timestamp to use in a query parameter.

  

  
  

• Usage in request headers: This shows how to concatenate two strings to create a value for a request header.

  

  
  

Anywhere you use a variable (with the {{ }} syntax) the .jq() method can be added to the end. The .jq() function is passed the value of the variable, which can be an array, object, string, or number, and will operate on the value of that variable. Then, the final return value of the jq function is used in place of the variable.

jq offers many ways of working with and wrangling your data; by utilizing this powerful tool, it's possible to transform.

Next steps and future development

We strongly believe in integrating with existing tools and specifications that are widely adopted and applicable to users of Assertible. Taking advantage of everything jq supports opens up myriad possibilities for API testing.

Your feedback is valuable: we'd love to hear your thoughts on the jq integration, or if you have any other ideas for making Assertible the easiest way to test and monitor your web services.

Useful related resources

• Get started with test variables
• Working with environment variables
• Using variables in setup steps
• Default test run variables

:: Cody Reichert