Calling DLL Functions From Tests - Overview

Basic Concepts

General Procedure of Calling DLL Routines

Tutorial

Known Limitations

You can call routines implemented in 32- and 64-bit libraries.

To access the needed DLL functions, you use the DLL object. The object has a number of methods for loading dynamic libraries and calling their routines.

When calling routines from a dynamic link library, TestComplete loads the library to a special helper process (tcHostingProcess.exe). We call it hosting process.

TestComplete loads DLLs to this hosting process (instead of the TestComplete main process) to stay stable. If a routine called from a dynamic library causes a critical error leading to a crash of the process that hosts the library, only the helper tcHostingProcess process is terminated, while the TestComplete main process stays alive. For more information about the hosting process, see Specifics of Using 32- and 64-bit DLLs.

By default, TestComplete stores the references to DLL objects you create in tests only during the current test run and deletes them after the test run is over. This way TestComplete isolates the results of calling DLL functions in different tests and prevents DLL access errors that can occur if one test affects the other tests.

To change this behavior and keep DLL object references between test runs, disable the DLL.Options.ClearSettingsBeforeEachRun option. TestComplete will keep the references until you close TestComplete or until you enable the option.

1. (Optional) If you are going to use only 32- or 64-bit libraries in your test, skip this step.

   If you need to use both 32- and 64-bit DLLs in the same test, define a program environment for libraries of the appropriate bitness (a 32-bit or 64-bit environment):

   • Call the DLL.DefineEnvironment or DLL.DefineEnvironmentByDLL method. The IDLLAccessProcess object that the method returns provides access to the created environment.

   • Perform the steps below for the created environment. That is, call the DefineDLL, DefineType, Load and New methods of the IDLLAccessProcess object, rather than of the DLL object. For more information, see Specifics of Using 32- and 64-bit DLLs.

2. Define the type of the DLL containing the routine to call from a test. You can do this by calling the DLL.DefineDLL (or IDLLAccessProcess.DefineDLL) method that returns a special object, IDefineDLL. Use the object to define DLL routines in the test.

3. Define types of custom OLE-incompatible parameters (for instance, data structures or arrays) to pass to the needed DLL function (if any). To do this, call the DLL.DefineType (or IDLLAccessProcess.DefineType) method. For more information, see Using Custom Data Structures in DLL Function Calls and Using Arrays in DLL Function Calls.

4. Define the DLL routine (its name, parameters and result type) to call from the test. To register the routine type in TestComplete, use the IDefineDLL.DefineProc method.

   Note:

   If the DLL was built with debug information, you do not need to define routine types manually. TestComplete will take information on routine types from the debug information.

5. Load the library into memory before calling its routines from tests. To do this, call the DLL.Load (or IDLLAccessProcess.Load) method that returns a pointer to the loaded library.

6. Create variables for the routine parameters that have custom OLE-incompatible data types or string parameters (if any) and initialize them. Call the DLL.New (or IDLLAccessProcess.New) method to create a custom data type variable, an array or a string. For more information, see Using Custom Data Structures in DLL Function Calls, Using Arrays in DLL Function Calls and Using String Parameters in DLL Function Calls.

7. Call the routine by using the library pointer returned by the Load method. To call the function from the test, use the syntax library_pointer.routine_name and pass the needed values to the routine in the same manner as you call other routines in your test.

For detailed step-by-step instructions on calling DLL routines from TestComplete, see:

Calling DLL Functions From Tests - Tutorial.

TestComplete support for calling routines implemented in dynamic link libraries has some known limitations. To learn about them, see the Calling DLL Functions From Tests - Known Limitations topic.