Specialized Type

The basic idea of specialized types is to provide the test generator (the API Sanity Checker tool) with enough information to generate correct invocation of the target interface in a typical use case and check basic constraints on the return value. The issue is that, for many interfaces, correct invocation requires preparing correct environment and correct parameter values. And this in turn may require calling other interfaces.

Specialized type (or "semantic type" of parameter) include information about various initialization means for various environments. Such information can be reused for multiple interfaces each time the same semantic types are used, which greatly speeds up the development. Correct values for simple types are created by generator completely automatically. When an interface has initialization means assigned for all of its parameters (and if necessary for initial environment), the generator can automatically compose a test for this interface.

Test development process consists in creating the complete collection of specialized types for the library. Testing of libraries with numerous interfaces by this methodology requires relatively small effort per test and thus is cheap enough. The efficiency is best revealed for interface sets with the number of interfaces starting from hundreds.

Table of Contents

C/C++ Language Extensions
Attributes of Specialized Type
Associating with Interfaces
Writing Specialized Types
Collections of Specialized Types
Using Test Data
Examples

C/C++ Language Extensions

Attributes of specialized type should be described on C/C++ language extended by the following instructions:

$(type) - instruction initializing an instance of data type.

void create_QAbstractProxyModel(QAbstractProxyModel* Obj) {

    Obj->setSourceModel( $(QAbstractItemModel*) );

}

$[interface] - instruction for interface call with properly initialized parameters.

xmlListPtr create_filled_list()
{

    xmlListPtr l=$[xmlListCreate];
    int num=100;
    xmlListPushBack(l,&num);
    return l;

}

$0 - an instance of the specialized type.

/*initialize "doc" property of the associated parameter*/
$0->doc = xmlParseMemory("<p/>",4);

$1, $2, ... - references to 1st, 2nd and other interface parameters.

/*initialize "next" field of the first parameter by the second parameter*/
$1->next=$2;

/*write first parameter to the second parameter*/
$2.write($1);

$obj - reference to the object that current method calls on (C++ only).

/*call setStyle() method on the object*/
$obj.setStyle(Qt::DotLine);

Attributes of Specialized Type

Specialized type has the following attributes: name - Name of the specialized type

data_type - Name of the associated real data type (QObject*, int, xmlChar ...) or the list of such types (one per line)

value - Value for initialization (true, 1.0, "string")

pre_condition/post_condition - Pre/Postcondition on associated function return value or parameter

$0!=NULL

init_code/final_code - Code that should be invoked before/after function call

/*call the start() method on the associated parameter*/
$0->start();

global_code - Declarations of auxiliary functions and global variables, header includes

#include <QWidgetAction>
QWidgetAction* create_QWidgetAction()
{

    QWidgetAction* Obj = new QWidgetAction($(QWidget*));
    Obj->setDefaultWidget($(QWidget*));
    return Obj;

}

libs - List of external shared objects used by this type. Corresponding external header files should be included in the global_code section

kind - Kind of the specialized type:

normal - This specialized type should be manually associated with the parameters or return values of suitable interfaces
common_param - This specialized type will be automatically associated with the parameters of all suitable interfaces
common_retval - This specialized type will be automatically associated with the return values of all suitable interfaces
env - This kind of specialized type was introduced for setting up correct environment for the interfaces. The code of this specialized type will be added once at the beginning or at the end of main() function in the test for manually associated interface
common_env - This kind of specialized type is the same as env, but will be automatically associated with all library interfaces

Associating with Interfaces

Specialized Types should be associated with the return values or parameters of some library interfaces. Base type of the specialized type should be the same as base type of return value or parameter. For example, specialized type with data_type=int* can be associated with any parameter that has int as the base type like int, int**, int&* and others (it is a family of data types - collection of types that have the same base type).

Writing Specialized Types

Specialized Type has XML-like structure (you can skip any section if it is not needed):

<spec_type>

   <kind>
      /* Kind of the specialized type.
         Select it from the following list:
           normal
           common_param
           common_retval
           env
           common_env */
   </kind>
 
   <data_type>
      /* Name of the corresponding real data type,
         one per line. You can specify several data
         types if kind is 'common_param' or
         'common_retval', one per line. This section
         is not used if kind is 'env' or
         'common_env' */
   </data_type>
   
   <value>
      /* Value for initialization (true, 1.0,
         "string", ...) */
   </value>
   
   <pre_condition>
      /* Precondition on associated function parameter.
          Example: $0!=NULL */
   </pre_condition>
   
   <post_condition>
      /* Postcondition on associated function return
         value or parameter.
          Example: $0!=NULL && $obj.style() == DotLine
       */
   </post_condition>
   
   <init_code>
      /* Code that should be invoked before function call.
          Example: $0->start(); */
   </init_code>
   
   <final_code>
      /* Code that should be invoked after function call.
          Example: $0->end(); */
   </final_code>
   
   <global_code>
      /* Declarations of auxiliary functions and global
         variables, header includes */
   </global_code>
   
   <decl_code>
        /* Code that will be pasted instead of parameter
           automatic declaration. Example: char \$0[16]; */
   </decl_code>
   
   <associating>
      <interfaces>
         /* List of interfaces (mangled/symbol names in
            C++) that will be associated with the
            specialized type, one per line */
      </interfaces>
       
      <except>
         /* List of interfaces (mangled/symbol names in
            C++) that will not be associated with the
            specialized type, one per line. This section
            is used if kind is 'common_env',
            'common_param' or 'common_return' */
      </except>
      
      <links>
         /* Associations with the return value,
            parameters or/and object, one per line:
              param1
              param2
               ...
              object
              retval */
      </links>
      
      <param_name>
         /* Associations with the parameters by name,
            one per line:
              param_name1
              param_name2
              param_name3
               ...
                     */
      </param_name>
   </associating>
   
   <associating>
       /* Other associations */
   </associating>
   
   <name>
       /* Name of the specialized type */
   </name>
   
   <libs>
       /* External shared objects, one per line.
          If spectype contains call of the functions from
          some external shared objects then these objects
          should be listed here. Corresponding external
          header files should be included in global_code */
   </libs>

</spec_type>

Collections of Specialized Types

You can unite several specialized types into collection(s):

<collection>
 
     <spec_type>
         /* Specialized Type №1 */
     </spec_type>
     
     <spec_type>
         /* Specialized Type №2 */
     </spec_type>
     
        ...
    
</collection>

<collection>
    /* Other Collection */
</collection>

The file containing collection(s) of specialized types can be provided to the API Sanity Checker tool by the -specialized-types (-st) option:

api-sanity-checker -specialized-types SPECTYPES.xml -gen -build -run

Using Test Data

Test data (special files needed by tests) should be created in some directory before generating tests. Path to that directory should be provided to API Sanity Checker tool by the -test-data (-td) option:

api-sanity-checker -test-data DIR -specialized-types SPECTYPES.xml -gen -build -run

For accessing test data files in the attributes of specialized types you should use TEST_DATA_PATH("file") construction. Test generator will copy specified file to the local "testdata/" directory and replace TEST_DATA_PATH("file") with the "testdata/file" in the generated code.

QSound* create_QSound()
{
    QSound* Obj=new QSound(TEST_DATA_PATH("SoundFile.wav"));
    Obj->setLoops(5);
    return Obj;
}

Examples

Setting up environment for all interfaces and correct initialization for parameters of type GObject* in the ATK library:

 <spec_type>
     <kind>
         common_env
     </kind>
 
     <init_code>
         g_type_init();
     </init_code>
 </spec_type>
 
 <spec_type>
     <kind>
         common_param
     </kind>
 
     <data_type>
         GObject*
     </data_type>
    
     <value>
         g_object_new (G_TYPE_OBJECT, NULL)
     </value>
    
     <global_code>
         #include <glib.h>
     </global_code>
 </spec_type>

Correct initialization for all parameters of type xmlListPtr in the libxml2 library:

 <spec_type>
     <kind>
         common_param
     </kind>
 
     <data_type>
         xmlListPtr
     </data_type>
    
     <value>
         create_filled_list()
     </value>
    
     <constraint>
         $0!=NULL
     </constraint>
    
     <global_code>
         xmlListPtr create_filled_list()
         {
             xmlListPtr l = $[xmlListCreate];
             int num = 100;
             xmlListPushBack(l, &num);
             return l;
         }
     </global_code>
 </spec_type>

Correct initialization for the 1st parameter of interface xmlListAppend(xmlListPtr l, void* data) from libxml2 library:

 <spec_type>
     <kind>
         normal
     </kind>
     
     <data_type>
         xmlListPtr
     </data_type>
     
     <value>
         create_filled_list()
     </value>
 
     <global_code>
         xmlListPtr create_filled_list()
         {
             xmlListPtr l = $[xmlListCreate];
             int num = 100;
             xmlListPushBack(l, &num);
             return l;
         }
     </global_code>
     
     <associating>
         <interfaces>
             xmlListAppend
         </interfaces>
       
         <links>
             param1
         </links>
     </associating>
 </spec_type>

Setting up environment for all interfaces from the libQt5Core library:

 <spec_type>
     <kind>
         common_env
     </kind>
 
     <global_code>
         #include<QApplication>
         #include<QTimer>
     </global_code>
 
     <init_code>
         #ifdef Q_WS_X11
           bool useGUI = getenv( "DISPLAY" ) != 0;
         #else
           bool useGUI = TRUE;
         #endif
         QApplication* app = new QApplication(argc, argv,
                                              useGUI);
     </init_code>
 
     <final_code>
         QTimer::singleShot(100, app, SLOT(quit()));
         app->exec();
     </final_code>
 </spec_type>

Setting up environment for all interfaces from the Gtk+ library:

 <spec_type>
     <kind>
         common_env
     </kind>
 
     <init_code>
         gtk_init(&argc, &argv);
     </init_code>
 
     <final_code>
        gtk_timeout_add(100, &main_loop_quit, NULL);
        gtk_main();
     </final_code>
 
     <global_code>
         #include <gtk.h>
         gboolean main_loop_quit(gpointer data)
         {
             gtk_main_quit();
             return FALSE;
         }
     </global_code>
 
     <associating>
         <except>
             gtk_init
             gtk_init_check
             gtk_parse_args
             gdk_init
             gdk_init_check
             gdk_parse_args
             gtk_test_init
         </except>
     </associating>
 </spec_type>

Using test data for initializing all parameters of type xmlTextReaderPtr in the libxml2 library:

 <spec_type>
     <kind>
         common_param
     </kind>
     
     <data_type>
         xmlTextReaderPtr
     </data_type>
     
     <value>
         create_reader()
     </value>
 
     <global_code>
         xmlTextReaderPtr create_reader(int n)
         {
             xmlTextReaderPtr reader = xmlReaderForFile(TEST_DATA_PATH("file.xml"), NULL, 0);
             int i;
             for(i=0; i<n; i+=1)
             {
                 xmlTextReaderRead(reader);
             }
             return reader;
         }
     </global_code>
 </spec_type>

Checking the return value of interface xmlLinkGetData(xmlLinkPtr lk) from the libxml2 library:

 <spec_type>
     <kind>
         normal
     </kind>
 
     <data_type>
         void*
     </data_type>
 
     <constraint>
         $0!=NULL
     </constraint>
     
     <associating>
         <interfaces>
             xmlLinkGetData
         </interfaces>
       
         <links>
             retval
         </links>
     </associating>
 </spec_type>