# Polling Functionality

[Pro Feature] Polling functionality in a test case allows one to repeat the test case request until the desired result is achieved. This functionality is useful in validating the API requests which are asynchronous in nature and for such kind of APIs, we need to repeatedly request the endpoint for checking the status of our previous operation.

# Characterstics of the Polling Test Case:

  1. Test Case will be marked as passed if the last iteration of the test case is passed otherwise it will be marked as failed.

  2. Test Case stops iterating

    1. If the test case iteration is passed. Simply set the appropriate assertions and Expected Body so that your test case requests will be repeated until all the assertions are passed and that mean your actual response matches the expected response defined in the Validation >> Expected Body tab.
    2. If the test case condition fails (if you have specified some condition in the Details tab of the test case.)
    3. If the global (at project level) polling timeout occurs. By default, the value will be 3 minutes.
    4. If the max number of iterations is reached. You may set it in the Loop Source field. By default, the value will be 100.
  3. Delay can be introduced before the API requests using Wait for Seconds field.

# How to configure a Polling Test Case:

To configure a polling test case, simply set the 'Polling' flag to true in your test case. That's it. Now the Test Case requests will be repeated as per the characterstics defiend above.

# How to configure the Polling Time out:

To configure the polling time out, simply open the Configuration Tab >> Miscellaneous section and then set the Polling Time out from the available list of configurations.

# Example Use Case:

Let's take one of the usage scenario from Microsoft Azure API Documentation.

Some requests like creating/deleting a resource cannot be carried out immediately. In such a situation, the server sends a 201 (Created) or 202 (Accepted) and provides a link to monitor the status of the request. It will keep on polling at regular intervals till the request reaches one of the terminal states Succeeded | Failed | Canceled.

To handle the above case, we will need to do the following:

  1. Extract the link to monitor the status of the request

    • To extract, simply use Variable Extractor tab to extract the desired information from the API response.
    • For more information, please read our guide on Extract Variables from API Response.
  2. Now, create a test case with the above extracted URL to monitor the status of the request.

    1. Set the Polling flag to true for this test case.
    2. To poll requests at regular intervals, simply set the Wait for seconds property to say 1. That means vREST NG will wait for 1 second before repeating the requests.
    3. To stop the request on terminal state:
      1. First define a global variable say resourceState and set the value as empty string.

      2. Now, in your polling test case, simply define the condition like this:

        '{{resourceState}}' !== 'Succeeded' && '{{resourceState}}' !== 'Failed' && '{{resourceState}}' !== 'Canceled'
        

        This will set the test cases requests to be repeated until the above condition is failed.

      3. Overwrite our resourceState variable by extracting the information from our polled API Test case using Variable Extractor tab.

    4. That's it.