Assertions in Virtual Services

In ReadyAPI, virtual APIs (virtual services) validate incoming requests with assertions, that is, they use assertions to check the input data. This helps you verify that the client code calls the API in an expected way. Of course, the server code that implements an operation should check the input data and should return an error, if this data is invalid. However, in many cases, you can use an assertion as an additional quick check for this or that case.

You can apply assertions to individual operations or to the entire virtual service:

Operation assertions are applied to incoming requests of the appropriate operations. Service assertions work for any incoming request.

Note: Neither operation assertions, nor service assertions work for operations that have no virtual responses defined. If you simulate such an operation, the virtual service will report the 500 Internal Server Error code, but the assertion will not fail.

Note: If needed, you can create several assertions for a virtual service or an operation. ReadyAPI will execute them in their order on the Assertions list.

To create a service-level assertion:

1. Select your virtual service in the Navigator panel.

2. Switch to the editor on the right, and, in Assertions, click .

3. Select the assertion type and configure assertion properties in the subsequent dialogs:

   

   Click the image to enlarge it.

To create an operation assertion:

1. In the virtual service editor, switch to the Setup page and select the needed operation.

2. Switch to the editor on the right, and, in Assertions, click .

3. Select the assertion type and configure assertion properties in the subsequent dialogs:

   

   Click the image to enlarge it.

The Assertion Properties dialogs have special toolbar commands and options that simplify creating verification conditions. For instance, many property dialogs have a button for testing the assertion or for easier extracting of request data.

These commands and options need sample data for their work. To provide this data, you need to send a request to the virtual service:

1. Run your virtual service.

2. Simulate the needed request to your service. To do this, you can use your client code, browser, or you can send a request from functional tests or from the APIs node.

Select the needed assertions in the Add Assertion dialog. Some of the assertions are not present there, because they cannot be applied to incoming requests: some of them are not applicable to virtual APIs, the others cannot be used with incoming request data.

For information on available assertions and their properties, see Available Assertions.

Note: There is no assertion that checks URL parameters. To verify them, use the Script assertion.

Virtual services post information on assertions to the Transaction Log. To view assertion results:

1. In the service editor, switch to the Transaction Log page.

   The log marks failed operations with a red dot (see the image below).

2. Click a failed operation and look at the editor on the right.

   Here, in the Assertions section, you can see which assertions failed and the cause of the fail:

   

   Click the image to enlarge it.

• ReadyAPI executes assertions in their order on the Assertions list. To change an assertion position, select the assertion on the list and click or .

• To exclude an assertion from the check, right-click this assertion on the Assertions list and select Disable from the context menu. To turn on a disabled assertion, right-click it and choose Enable from the context menu.

• To copy an assertion quickly, right-click within the Assertion list and select Clone from the context menu.

• To verify URL parameters of a request, use the Script assertion. To get a parameter, you can parse the raw request data. See the example below.

  Example

  ExampleExample

  Groovy

  Groovy

  // Usage
  log.info('Parameter 0:' + getParameter(0))
  
  // ...
  
  // The function that returns the parameter by its index
  String getParameter(paramIndex)
  {
    // Get the request data
    def requestData = messageExchange.rawRequestData // An array like [80, 79, 83, 84 ...]
  
    // Convert request data to a string
    String s = ''
    for(i = 0; i < requestData.length; i++)
      s = s + (requestData[i] as char)
  
    // s now is a string like POST /path?param=value HTTP /1.1...
    // Let's extract the first line of the request from s
    def data = s.split(' ')
    String firstLine = data[1] // POST /path?param=value HTTP /1.1
  
    // Let's now extract information on parameters
    int idx = firstLine.indexOf('?')
    if (idx >= 0)
    {
      String paramStr = firstLine.substring(idx + 1)
      def params = paramStr.split('&') // An array that contains the param=value pairs
      return params[paramIndex]
    }
    else
      return null
  }

• Each assertion has a name and type name. By default, they coincide – you can see this on the Assertion list:

  

  If you use several assertions of the same type, you may want to assign different names to them. To do this, right-click an assertion on the list and select Rename from the context menu.