JSON Objects in SoapUI

In my last post I started looking at handling JSON response data in Groovy script using the JsonPathFacade class.  In the example I covered there, we checked to make sure all the countries returned in a response matched a search string-- each country entity returned had three properties: a 2 character code, a 3 character code, and a name.  Since the search string was so long (greater than three characters), we only had to check the name property of returned countries.  But what about a search on a shorter two-character string that could potentially match any of a given country's properties-- for example, what if our search string was "kh"?

Here's the corresponding response returned by the service:

{"RestResponse": {
   "messages":    [
      "More webservices are available at http://www.groupkt.com/post/f2129b88/services.htm",
      "Total [2] records found."
   ],
   "result":    [
            {
         "name": "Cambodia",
         "alpha2_code": "KH",
         "alpha3_code": "KHM"
      },
            {
         "name": "Kazakhstan",
         "alpha2_code": "KZ",
         "alpha3_code": "KAZ"
      }
   ]
}}


The method we used before to check names wouldn't work here-- Cambodia is only a match by virtue of its alpha codes, while Kazakhstan's only match is its name.  We have three string properties to check per country instead of one, so a simple one-dimensional array of strings isn't enough.  One approach we can take is to retrieve each country entity as a JSON object and check each object's set of properties.

Here's our new Groovy assertion (line numbers added by me for reference):

01  import com.eviware.soapui.support.JsonPathFacade
02
03  def failCount = 0
04  def jpf = new JsonPathFacade(messageExchange.responseContent)
05  def testArray = jpf.readObjectValue("RestResponse.result")
06  testArray.each {
07    def countryName = it.get("name")
08    def countryAlphaTwo = it.get("alpha2_code")
09    def countryAlphaThree = it.get("alpha3_code")
10    if(!countryName.toUpperCase().contains("KH") 
11      && !countryAlphaTwo.toUpperCase().contains("KH") 
12      && !countryAlphaThree.toUpperCase().contains("KH")) {
13   log.info("    Non-matching country: $countryName")
14   failCount++
15    }
16  } 
17  assert failCount == 0

I'll skip the first few lines (including the import statement and the creation of the failCount and jpf variables)-- these are the same as in the sample assertion from my last post.  The first difference is in line 5 where the readObjectValue() method is used with the JsonPathFacade object to retrieve the array of country entities (using the JsonPath expression RestResponse.result).  The resulting object assigned to the testArray variable is a JSONArray object from the net.sf.json library.  You can find more information about the library at http://json-lib.sourceforge.net.

Like the ListArray class in my last post, the JSONArray class is compatible with Groovy's each() method.  In line 6 it's called to step through the members of the JSONArray's collection of objects of the JSONObject class (also from the net.sf.json library).

The JSONObject class has a get() method that takes a property name and returns the corresponding property value.  In lines 7 through 9 the method is used to get the name, alpha2_code, and alpha3_code properties of each country object, assigning them to the countryName, countryAlphaTwo, and countryAlphaThree variables, respectively.

Once we've gotten the property values into variables, we can check them against our match string.  The if block's conditional statement is a bit gnarly; I've broken it up across lines 10 through 12.  It roughly translates to "if countryName, countryAlphaTwo, and countryAlphaThree do not contain the string 'KH'..."  Note that for each variable, I use the toUpperCase() method to convert all its characters to uppercase before applying the contains() method.  The contains() method is case sensitive, so converting to uppercase (including the match string) "normalizes" everything for easy comparison-- just as easily, I could have used the toLowerCase() method with the match string "kh".

The last few lines are similar to the last post: if the if conditional is true-- if we do indeed find a case where none of the country's properties contain the match string-- then we log information identifying the country (line 13) and increment the failCount variable by one (line 14).  Finally, after wrapping up our each block we assert that our failCount variable still equals zero after checking all the properties for all countries returned by the service.

SoapUI: Handling JSON in Groovy with the JsonFacade Class

As with XML response data, you may come across situations dealing with JSON where you need a little more than what's offered by the standard JsonPath-based assertions. Fortunately, SoapUI provides the JsonPathFacade class for manipulating and retrieving Json in Groovy script, analogous to the XmlHolder class with Xml data.

In my last post, I looked at a service that returned country ISO codes. One type of request searched on a string and returned any countries with matching names, ISO-2 codes, or ISO-3 codes; here's the response JSON for a request searching on the string "United":

{"RestResponse": {
   "messages":    [
      "More webservices are available at http://www.groupkt.com/post/f2129b88/services.htm",
      "Total [5] records found."
   ],
   "result":    [
            {
         "name": "Tanzania, United Republic of",
         "alpha2_code": "TZ",
         "alpha3_code": "TZA"
      },
            {
         "name": "United Arab Emirates",
         "alpha2_code": "AE",
         "alpha3_code": "ARE"
      },
            {
         "name": "United Kingdom of Great Britain and Northern Ireland",
         "alpha2_code": "GB",
         "alpha3_code": "GBR"
      },
            {
         "name": "United States of America",
         "alpha2_code": "US",
         "alpha3_code": "USA"
      },
            {
         "name": "United States Minor Outlying Islands",
         "alpha2_code": "UM",
         "alpha3_code": "UMI"
      }
   ]
}}

Ideally, we'd want to test that all the names returned for the test request do indeed match our input string.  Here's a short example Groovy script assertion that does that using the JsonPathFacade class (line numbers added by me for the walk-through below):

01  import com.eviware.soapui.support.JsonPathFacade
02  
03  def failCount = 0
04  def jpf = new JsonPathFacade(messageExchange.responseContent)
05  def testArray = jpf.readObjectValue("RestResponse.result[*].name")
06  testArray.each{
07    if(!it.contains("United"))
08    {
09      log.info("    Non-matching name: $it")
10      failCount++
11    }
12  }
13  assert failCount == 0

Let's take a look at it line by line:

After importing the JsonPathFacade class (note the XmlHolder class is in the same package) in line 1, line 3 defines a failCount variable we'll use to keep track of failures and check later in our main pass/fail assertion.

In line 4 we create a new JsonPathFacade object and assign it to the jpf variable.  The JsonPathFacade constructor takes JSON response content (as a string) as its only argument.  Within a Groovy script assertion, we can access response content via the responseContent property of the built-in messageExchange variable and pass that into the constructor.

The readObjectValue() and readStringValue() methods of the JsonPathFacade class are the two you'll probably encounter most frequently.  Both take a JsonPath expression (as a string) as input and return the corresponding JSON content; readStringValue() returns the content as a string while readObjectValue() returns it as an object.

In line 5, we use the readObjectValue() method with the JsonPath expression RestResponse.result[*].name to get the names of all the country entities in our response.  This returns a Groovy ArrayList object that gets assigned to the testArray variable.

The ArrayList class is compatible with Groovy's each() method, so starting in line 6 we use it to iterate through the names contained in the testArray variable.  Line 7 checks each name against our match string ("United" in this case).  If the name doesn't match, we log an informational message (line 9) and increment the failCount variable (line 10).

Finally, once our each() method is finished checking all of the country names returned in the response, we assert the failCount variable should still equal 0 in line 13-- if any of the country names didn't contain "United", the assertion and test step fail.

Just to confirm that our script works as expected, let's look at the output if we change our match string (in line 8) to "States", artificially generating failures:


Groovy assertion results and output

Next time we'll look at a more complex example working with JSON objects.

SoapUI: Building JsonPath Expressions

The 5.2 release of SoapUI OS contains some significant changes.  Most obviously, there's been an overhaul of its basic look with new icons and some high-level actions (creating new test suites, importing suites, etc.) added to the main screen.  For the most part, these graphical changes are for ease-of-use and aesthetics; very little has really changed with basic workflows and 5.2 should be compatible with test suites created in pre-5.2 versions.  But in keeping with SoapUI's recent trend of improved support for non-SOAP services, several new JsonPath-based assertion types have also been added:

1) JsonPath Match - Verifies the value specified by a JsonPath expression matches some expected value

2) JsonPath Existence Match - Verifies the element specified by a JsonPath expression exists in the target JSON

3) JsonPath Count Match - Verifies the number of matching instances for a given JsonPath expression (if the expression evaluates to an array, the count is the length of the array) equals some expected value

4) JsonPath Regex Match - Similar to the basic JsonPath Match assertion, but the value specified by the JsonPath expression is matched to a regular expression

For those of you unfamiliar with it, JSON stands for JavaScript Object Notation.  Like XML, it provides a standardized way to represent complex data across different operating systems, architectures, etc.  Here's a typical JSON data block:
{"response":
   {
      "library":[
         {
            "title":"War and Peace",
            "author":"Tolstoy, Leo",
            "pages":1296,
            "tags":["literature","Russian","classic"]
         },
         {
            "title":"Harry Potter and the Chamber of Secrets",
            "author":"Rowling, J.K.",
            "pages":341,
            "tags":["fiction","fantasy"]
         },
         {
            "title":"In the Garden of Beasts",
            "author":"Larson, Erik",
            "pages":448,
            "tags":["non-fiction","history"]
         }
      ],
      "requestId":12345,
      "requestStatus":"OK"
   }      
}
This JSON defines an object (enclosed in braces in JSON) called response that consists of library, requestId, and requestStatus properties.  The library property is an array (enclosed in squared brackets) of objects representing books.  Each book object has a title, author, pages, and tags property; the tags property is itself another array of strings.

JsonPath is JSON's equivalent of XPath-- it provides a simple way to reference a particular value in JSON.  You can read a detailed description of JsonPath at http://goessner.net/articles/JsonPath, but I'll present some quick starting rules here with examples using the JSON data above.  JsonPath actually supports two different basic syntaxes, one using bracketed property names to navigate through successive levels of data (e.g., ['parent']['child']), and another using parent.child dot notation syntax similar to what's used in most programming languages.  For the sake of brevity, I'll focus on dot notation syntax in this post.

DescriptionExample ExpressionExample Result
To get the value of an object's property, separate the property name from the object name (or the portion of the JsonPath expression designating the object) with a dot-- again, if you're familiar with dot notation in programming, it's pretty much the same idea.response.requestStatusOK - The response object's requestStatus value
Zero-based indexing using brackets indicates a particular element in a JSON array.  Note the use of zero-based indexing (i.e., representing the first item with index 0, the second with index 1, etc.) is a key difference from XPath's one-based indexing.response.library[0].authorTolstoy, Leo - The author property of the first object in the library array
Using * instead of an index number with an array returns all elements in the array.response.library[*].title[War and Peace, Harry Potter and the Chamber of Secrets, In the Garden of Beasts] - A JSON array of every title in the library array
The JSON data root is designated by $, although this is optional in expressions that explicitly start with the first element of the target JSON data (the examples given above safely omit the $ since they start with the root response element).$.response.requestStatusOK - Equivalent to the first example; the requestStatus property of the response object
A pair of dots indicates a recursive search for the following property; i.e., the property can be found at any level beneath the property preceding the dots.  This is equivalent to double slashes in XPath.$..requestId12345 - The response object's requestId property (note we didn't have to explicitly designate the response object here)
You can access the length property of an array to determine the index of its last (or some position relative to the last) member.  In the example expression, @ represents the last evaluated element-- in this case, the library array-- in the bracketed expression.  Remember that because of zero-based indexing, the index of the last member of an array is one less than the array's length, so we subtract 1 from the length to find its index.  JsonPath is very particular about brackets and parentheses; the parentheses around the @.length - 1 expression may seem optional, but omitting them will result in an "invalid expression" error.$..library[(@.length - 1)].authorLarson, Erik - The author property of the last member in the library array.
You can also build basic predicate statements within squared brackets to filter on specific criteria.  The ? enclosed in brackets indicates a predicate, followed by a test expression in parentheses.  Within the predicate expression, the @ character acts as a placeholder for each array member being evaluated by the predicate.  So in this example expression we're starting with the result array, then evaluating each member's name property and returning those members where the title property matches 'War and Peace' (note the use of == instead of = to check for equality here).  Finally, for each array member that passed the predicate test, we get the value of its pages property.result.library[?(@.pages > 400)].title[War and Peace, In the Garden of Beasts] - The title property of every book object with a pages property greater than 400

If you'd like to play around with JSON expressions yourself, you can copy and paste the JSON data above into the JsonPath expression tester at http://jsonpath.curiousconcept.com.  One thing to keep in mind when working with the JsonPath expression tester: string values returned by JsonPath expressions in SoapUI are not enclosed in quotes, as they are with the JsonPath tester (the examples above show results as they appear in SoapUI).