Calling DLL Functions From Tests - Overview

Applies to TestComplete 15.47, last modified on January 20, 2023

In TestComplete, you can call routines implemented in DLLs from tests. This way, you can enhance your tests by calling useful functions from third-party libraries.

Basic Concepts

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

Note: You can call functions from 64-bit DLLs only on 64-bit operating systems.

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.

General Procedure of Calling DLL Routines

  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):

  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.

Tutorial

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

Calling DLL Functions From Tests - Tutorial.

Known Limitations

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.

See Also

Calling DLL Functions From Tests - Tutorial
Specifics of Using 32- and 64-bit DLLs
Calling DLL Functions From Keyword Tests
Using Custom Data Structures in DLL Function Calls
Using String Parameters in DLL Function Calls

Highlight search results