Skip to main content

SeeTestAutomation- Reviewing VUGen Client Code

info

Please note that this tool is classified as a Legacy tool. We recommend transitioning to our updated solutions to maintain optimal performance and security in your workflows. For more information on this matter, please reach out to technical support .

You have learned how to export code auto-generated for VUGen client into HP Virtual User Generator. In this section we will mention a few points of interest in the code which was generated in the first section.

We will review the following example of such code

#include "ic_api.h"
 
/* Callback which is invoked whenever an ic_... command fails: */
static void exceptionCB(image_client* client) {
    if (client->latest_result.status == IC_INTERNAL_EXCEPTION) {
        lr_error_message ("Internal exception of type %s was raised: %s",
                          client->latest_result.details.internal_exception.cause_id,
                          client->latest_result.details.internal_exception.message);
    }
    /* Generates a report of this test case and releases the client so that other */
    /* clients can approach the agent in the near future: */
    ic_generate_report(client, IC_TRUE);
    lr_abort();
}
 
Action()
{
    image_client c = {IC_DONE, NULL, NULL};
    const char *text;
    ic_string_array s_arr;
    int n;
 
    lr_load_dll("C:\\Program Files (x86)\\Experitest\\SeeTest8.4\\clients\\dist\\vugen\\imageClient_C_API.dll");
    ic_init(&c, "localhost", 8889, &exceptionCB);
    ic_set_project_base_directory(&c, "C:\\Users\\USER\\workspace\\project1");
    ic_set_reporter(&c, "xml", "reports", "sa_vugen");
    ic_set_device(&c, "adb:Nexus5");
    ic_launch(&c, "com.experitest.ExperiBank/.LoginActivity", IC_TRUE, IC_FALSE);
    text = ic_get_text(&c, "TEXT");
    s_arr = ic_get_all_values(&c, "NATIVE", "xpath=//*[@text='Select']", "text");
    if(ic_is_element_found(&c, "TEXT", "company", 0) == IC_TRUE)
    {
         n = ic_get_element_count(&c, "NATIVE", "xpath=//*[@text='company']");
    }
 
    /* Generates a report of this test case. */
    ic_generate_report(&c, IC_FALSE);
    ic_release_client(&c);
    return 0;
}




Line 1 instructs to include header file ic_api.h, which defines VUGen client’s functions, complex data types with which they operate, and auxiliary structures. During installation of SeeTestAutomation, the file is copied into directory <HP_LoadRunner_installation_directory>/include . However, if it could not be done, you should include file ic_api.h as an extra file of your project. For that purpose, you can click RMB above  in the solution explorer and select the pop-up option "Add Files to Script...". The location of file ic_api.h is <SeeTestAutomation_installation_folder>/clients/dist/vugen/ic_api.h .

We proceed to function exceptionCB. This is a callback that is registered (in line 24) to be invoked when a step of the test fails. It expects to receive a pointer to the main structure of VUGen-client handler -- image_client. This structure’s most important field is latest_result, which holds the status of the recently executed step. This field is a structure which consists of two fields:

  1. status, which is enum: value IC_DONE is assigned into this field if a step has succeeded; other values (namely, IC_INTERNAL_EXCEPTION -- see line 5) in this field indicate that the latest step has failed. 
  2. details.internal_exception: contains details of the most recent failure (see lines 7-8).

Line 12 contains the first example of a VUGen-client API function, namely, ic_generate_report, which generates a report for the currently running test and releases the client (see more details later when we consider call ic_release_client). All these API functions, which, recall, are declared in ic_api.h, start with prefix ic_ and expect a pointer to a VUGen-client handler, i.e., a pointer to image_client as the first argument. In order to look the online guide up for the documentation of a particular command, one need to omit that prefix and other underscores from the name of the corresponding API function. For example, one should look up for command GenerateReport in order to read the documentation of function ic_generate_report. Those API functions operate, with the following data types:

  • int: for an integer value; line 33 contains a function which returns an integer value, while line 24 contains function which receives an integer argument. 
  • const char *: for a string value; line 29 contains a function which returns a string, while line 24 contains function which receives a string. 
  • ic_bool: for a Boolean value; this type is defined in ic_api.h, and its possible values are either IC_FALSE or IC_TRUE (see line 28 for an example); line 31 contains a function which returns a Boolean value.
  • ic_string_array: for an arrays of string values; this is a structure defined in ic_api.h; it consists of two fields:
    • int length: the length of the array;
    • char **array: the actual array of char * elements.Line 30 contains a function which returns a string array.

In addition, some functions return no value, i.e., are void functions.

Since the default implementation assumes that callback exceptionCB is invoked only when a failure has occurred, it aborts the test in line 13 using LoadRunner’s function lr_abort. However, you can override this behaviour.

Now we proceed to function Action. Its first line, namely line 18, declares a VUGen-client handler. The handler is initialized in line 24. You may not use the handler or assign its fields prior to its initialization. Function ic_init is thoroughly described here. Briefly, it expects to receive the host and the port of the executive agent which will be associated with the handled client. Its fourth argument allows to register a callback which will be activated once a test step fails. The callback is expected to be a void function having a single parameter, which is a pointer to structure image_client. In this example, we register callback exceptionCB. Registration of an exception callback is optional. Alternatively, you can pass NULL as the fourth argument of ic_init and then check whether your client’s field latest_result.status equals to IC_DONE after each step. You can also unregister the callback later in the test by nullifying field exception_callback of structure image_client or override the callback by assigning a pointer to a different void function to that field.

Now we jump to the final lines of Action. Line 37 generates a report for the currently running test. Unlike a similar call of function ic_generate_report in line 12, this call does not release the client owing to IC_FALSE passed as the second argument. This argument tells function ic_generate_report whether to release the client. In function Action, the client is rather released in line 38 using function ic_release_client. Regardless how you release the client, when it is being released, all the data buffers dynamically allocated and returned in API calls associated with this client’s handler are freed as well. This includes strings and string arrays returned as results of those calls.

The header file ic_api.h declares the API function of VUGen client. However, they either are implemented in or call some auxiliary routines which are implemented in a library file imageClient_C_API.dll . Line 23 tells LoadRunner where to search for this file. Although this line is optional, you are advised not to delete it especially if you have several versions of SeeTestAutomation installed or you were installing SeeTestAutomation without administrative privileges.

Lines 25-33 contain sample commands the test executes. Command ic_set_project_base_directory (line 25) sets the location of objects on which the test is about to operate. Command ic_set_reporter (line 26) configures the kind of report the test shall produce, its name and location. Usually this command precedes actually testing steps of a test (for instance, lines 27-33 in our example). Command ic_set_device (line 27) sets the device on which the test commands will run. Command ic_launch launches an application, an activity or an URL on the device which has been most recently set by commands ic_set_device or ic_wait_for_device. In line 28, SeeTestAutomation’s demo application ExperiBank is launched. Lines 34-35 contain an example of commands which return a string value and a string array, respectively. You should not free these results. They will be automatically freed when the associated client handler is released (line 38 on successful termination of the test or line 12 on failure). Should you need to store the results beyond the moment when the client is released, you can copy the content of the results to buffers allocated by you. Lines 31 and 33 show examples of commands which return Boolean and integer values, respectively.

The header file ic_api.h contains the most up-to-date list of all VUGen-client commands. You are advised to look through it. It is located under <SeeTestAutomation_installation_folder>/clients/dist/vugen/ic_api.h .

Last updated on