API testing with DevWeb scripts

Your DevWeb scripts can be used for API performance testing. To shorten scripting time, you can use the DevWeb Offline Script Generator to convert Swagger API documentation into JavaScript functions, providing a format that is easy to read and maintain. The generated functions can be called from DevWeb scripts.

Note: This feature is provided as tech preview.

About API testing with DevWeb

Swagger is an open specification used to describe and document RESTful APIs.

To enable API testing with DevWeb scripts, you can convert the API calls in Swagger definition files (swagger.json format) into functions that can be called from DevWeb tests.

This functionality is supported with Swagger Specification 2.0.

Tip: Check out the video: API testing with DevWeb scripts.

Using Swagger mode to generate swaggerApi.js

The first stage for converting the Swagger files is to import the Swagger JSON file and to generate a JavaScript file, swaggerApi.js, containing auto-generated JavaScript functions. This is performed by the DevWeb Offline Generator working in Swagger mode. The generated swaggerApi.js file is added to the folder for the DevWeb script, and the imported JSON definitions are stored in the codeGen folder.

Note: Swagger mode also generates (or regenerates) a main.js file, but without the API function calls inside.

Each JavaScript function includes parameters, and represents an API call in the Swagger definition file. The function can connect with the server to execute the operation described by the API call.

Your swagger.json may be very large, with hundreds of operations, and you may not want to test them all. One option is to manually add the functions you want to test to your script, using the required parameters. Implementation is inside the swaggerApi.js, so that when the function is called, it generates an API call on the application, and returns a web request.

A quicker and easier method, rather than editing the script manually, is to generate the main.js for your script based on a HAR file containing the recorded API operations. This can be prerecorded, or created using the DevWeb Proxy Recorder.

Using Swagger mode with a prerecorded HAR file

While recording for the HAR file, you invoke the specific API operations in the Swagger UI that you want to test. When you generate your script from the HAR file while in Swagger mode in VuGen, the script is created containing the relevant function calls.

Using Swagger mode while recording with the Proxy Recorder

While in Swagger mode, you record the API functions from VuGen using the DevWeb Proxy Recorder. You record directly in the Swagger UI, and invoke the relevant operations. When the script is generated, it contains the relevant function calls.

Creating the function calls

The creation of each function call in the main.js is based on the Offline Script Generator finding a single, unique match between the HAR entry and the generated JavaScript function in the swaggerApi.js. If there is a match, it creates a function call for that function. If a match is not found, or there are multiple matches, it generates a regular DevWeb WebRequest send call.

Back to top

Example

A pet store application is described using the pet_swagger.json file. The JSON contains various different operations for the pet store.

pet_swagger.json file:

The JSON section below defines an API operation for adding a pet to the store, with operationID "addPet". It should be called via a POST request with an argument in its body. The parameter name is "body".

"/pet": {
            "post": {
                "tags": [
                    "pet"
                ],
                "summary": "Add a new pet to the store",
                "description": "",
                "operationId": "addPet",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json",
                    "application/xml"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "body",
                        "description": "Pet object that needs to be added to the store",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/Pet"
                        }
                    }
                ],
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    }
                },

swaggerApi.js file:

When the Offline Generator generates the swaggerApi.js file, it contains the corresponding generated function for addPet. It has a parameter named body, as used in the JSON file, and the parameter description from the JSON file.

The function creates a WebRequest to call the API, and returns the request. In the body, the function used the parameter.

main.js file:

The generated main.js file contains a call to the addPet function in the swaggerApi.js, using the value taken from the HAR file. The function uses the returned WebRequest and sends it. The return value of the send is a WebResponse, which is assigned to a variable.

Tip: The <DevWeb_data_path>\examples\ folder includes the following API testing example scripts:

  • APITestingPetStore
  • APITestingAdvantageOnlineShopping

Back to top

Parameters

  • Swagger describes several locations of function parameters: Path, Headers, Query, Form Data, and Body.

    The generated function accepts the parameters defined for the operation in the swagger file, and used in the function body, inside the generated WebRequest. For example, Path parameters are used in the WebRequest URL, Query parameters are used in the WebRequest query.

  • A parameter has a required property in its schema which can be equal to true or false. All parameters are generated, whether required or not. The Offline Generator ignores this property.
  • The functions getSchema and getHost (that return the Schema and Host parameters respectively) are used in the WebRequest URL.
  • If the swagger.json is missing the Host property, the generated getHost function returns an empty string, and the script will fail with an error. To avoid this, the main.js file includes an override option for getHost, to prompt you to add your host name:

Back to top

Correlations for API testing functions

The API functions calls may include correlation extractors and appliers, where relevant. When the record scan or rules scan are enabled and find correlation values, the values are added to the generated API function calls.

For more info on using correlations, see Correlation for DevWeb scripts.

Extractors

When generating API function calls, the relevant extractors (defined by the correlation record or rule scan) are automatically generated in the main.js file. For example:

Appliers for values exposed in the script

For the API function call parameters that are exposed, where you see the values in the main.js, the applier simply replaces the correlated value.

Example:

A function call has a parameter requiring a correlated value for an API key. This was extracted from an earlier web response:

let webRequest = swaggerApi.deletePet(`API_KEY_11122FFFFF`, "123");

After a record scan or rule scan, it becomes:

let webRequest = swaggerApi.deletePet(`${earlierResponse.extractors['api_key']}`, "123");

Appliers for attributes not exposed in the script

When generating API function calls, there are web request attributes that do not appear in the parameters, and are therefore not exposed in the main.js. For example, some headers or query strings.

If these attributes have values that need to be correlated, they are accessed directly by the record or record scan, and generated in the main.js like an assignment, using the request name. The appropriate applier is then applied to the appropriate field. For example:

Back to top

Generate files from Swagger definitions

The following steps describe how to generate the swaggerApi.js file, and the main.js file for the script, using Swagger mode.

To generate files from Swagger:

Prerequisite: A swagger.json file created with Swagger Specification 2.0

  1. Open your DevWeb script in VuGen, and select Record > Import API File.
  2. In the Import API File dialog box:

    • Enter the path to the swagger.json file in the API file field.
    • If you want to regenerate the swaggerApi.js, but do not want to overwrite the previously generated main.js, deselect the Generate main check box. For example, you may have manual edits in the main.js that you don't want to overwrite.

    Click Import.

  3. VuGen generates the swaggerApi.js file and adds it to the script . It can be viewed in Solution Explorer under the Extra Files folder.

  4. Click the Record button to define recording settings.
  5. In the Start Recording dialog box, make sure that the Generate with API analysis check box is selected. This sets script generation to Swagger mode.

  6. Select the appropriate Record option, and give the path to the HAR file or to the Swagger UI, as appropriate.
  7. Click Start Recording.
  8. If you selected to record with the Proxy Recorder, record the operations to test in the Swagger UI.
  9. The script is generated with the relevant API functions in the main.js file.

Note: If you regenerate the script, it is regenerated without the API functions.

Back to top

See also: