Specifications functionality

This is a pro feature and in beta as of now and this feature has been introduced in vREST NG v1.8.0.

Specifications functionlity allows you to drive your entire API Testing through API specification files. It provides the following set of functions:

  1. You may generate API Test for a specific API Spec operation at any point in time.

  2. It allows you to validate the API response through dynamic schema id. e.g.

    #/{{$operation}}/responses/200
    

    Here $operation is a special variable and contains the information about operation associated with the test. So you may change the schema definitions and changes will be automatically reflected in your API tests.

  3. It provides the API Coverage Report that will give you insights like how many tests you have written for an API and for which APIs, you have not written any tests at all.

In this guide, we will look at how you may use the specifications function in vREST NG Application. We will cover the following points in detail.

  1. Defining your API Specification file
  2. Creating a test case from the API specification
  3. Validating API response through API Specification schema references
  4. API Coverage Report

Few points before using this feature,

  1. It is necessary that you define the operationId field for each operation in your API specification file. Also please don't update the operationId in your API specification file after that, otherwise you will need to update the operationId in your tests manually.
  2. If you have modular specification files in your project then combine those files in a single file before entering it in vREST NG Application. vREST NG doesn't maintain any cross references among specification files.

Now let's see the Specification feature in detail:

  1. Defining your API Specification file

    To define the API specification, simply visit the Configuration Tab >> Specifications section. And now click on New Specification button and provide the following information:

    1. Specification Type: You may provide either Swagger 2.0 or OpenAPI 3.0 type specifications. So select the appropriate value from the dropdown.
    2. Specification Name: Provide a suitable name for this specification.
    3. Specification Content: In the code editor, provide the API specification file content.

  2. Creating a test case from the API Specification

    Once you have defined the API specification file as shown in the previous step. Now let's try to create a test from the specification. To create a test, simply visit the Test cases tab and click on + icon in the toolbar to create your test.

    A dialog window will appear. In the dialog window, simply select the Generate option to from Specification. And now the system ask for Test Suite Name, Spec Name, Operation.

    Simply select the Spec Name from the list and then select the desired Operation for which you would like to generate the test. Further system will ask you the following test case type:

    1. Normal Test Case
    2. Data Driven Test Case

    Select Data driven test case if you would like to generate data driven API test, otherwise select normal test case option.

    Now click on Confirm button to generate the test. Now, let's look at some of the information generated in the API test.

    The following screenshot illustrates the generated API test. The Operation Id field binds the test case with the specific API specification operation.

    The following screenshot illustrates the request parameters generated from API specification:

    The following screenshot illustrates the validation logic generated from API specification:

    And the following screenshot illustrates the generated Expected Schema Tab content:

  3. Validating API response through API Specification schema references

    Now, let's see how you may validate your API response through the schema references defined in the API specification file. For that purpose, simply open the Validation >> Assertions tab. Now add a Text Body assertion that calls the Default Schema Validator. And in the Expected Value column, you may select the desired schema reference. You may even define this reference in the Expected Schema tab.

    Please note that if you define the value in the Expected Value column of the Assertions tab, then Expected Schema tab content will be ignored.

  4. API Coverage Report

    API coverage report will help you in identifying the APIs available, their associated tests. The coverage report can be accessed using the More options available in the left pane.

    The coverage report will look like this: