Working With TestComplete via COM - Overview

Applies to TestComplete 14.40, last modified on April 22, 2021

TestComplete is a COM server and it can be controlled from other applications like any other COM server (for example, like Microsoft Word). This topic provides a step-by-step explanation of how you can control TestComplete via COM from a Visual Basic application and a managed (C#) application.

COM commands work only if one instance of TestComplete is running.

Requirements

If your computer is running under Windows 8 or a later operating system, your COM client application for TestComplete must have the same privilege level as TestComplete.

To learn how to configure the privilege level, see —

Configuring Manifests on Windows 8 and Later Operating Systems

Adding a Reference to the TestComplete Library

Add a reference to the TestComplete Library of an application from which you will automate TestComplete:

C#, Visual Basic .NET
  • Open your COM client application in Microsoft Visual Studio.

  • Select Project | Add Reference from the main menu of Visual Studio.

  • In the Add Reference dialog, switch to the COM tabbed page.

  • Select the TestComplete Library (TypeLib Version: 14.xx) in the list and press OK.

Visual Basic 6
  • Open your COM client application in Microsoft Visual Basic 6.

  • Select Project | References from Visual Basic's menu. This will open the References dialog.

  • Find TestComplete Library in the list of the available references.

    If the list does not contain TestComplete Library, click Browse and select the <TestComplete>\Bin\TestComplete.exe file.

  • Select the check box next to the TestComplete Library and press OK.

    Visual Basic 6 References: Selecting the TestComplete Library reference

Connecting to TestComplete via COM

TestComplete has the following program identifiers:

  • 32-bit version:

    TestComplete.TestCompleteApplication

    TestComplete.TestCompleteApplication.14

  • 64-bit version:

    TestComplete.TestCompleteX64Application

    TestComplete.TestCompleteX64Application.14

If you have several TestComplete versions installed, use a version-specific program identifier; otherwise use a version-independent program identifier.

To launch TestComplete or to connect to an already running TestComplete instance, use the following code:

C#

const string TCProgID = "TestComplete.TestCompleteApplication.14";

object TestCompleteObject = null;

try
{
    TestCompleteObject = Marshal.GetActiveObject(TCProgID);
}
catch
{
    try
    {
        TestCompleteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TCProgID));
    }
    catch
    {
    }
}

Visual Basic .NET

Const TCProgID = "TestComplete.TestCompleteApplication.14"

Dim TestCompleteObject As TestComplete.TestCompleteApplication = Nothing

Try
    TestCompleteObject = Marshal.GetActiveObject(TCProgID)
Catch
    Try
        TestCompleteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TCProgID))
    Catch
    End Try
End Try

Visual Basic 6

Const TCProgID As String = "TestComplete.TestCompleteApplication.14"

Dim TestCompleteObject As TestCompleteApplication

On Error Resume Next
TestCompleteObject = GetObject(, TCProgID)
If Err.Number <> 0 Then
    Err.Clear
    TestCompleteObject = CreateObject(TCProgID)
End If
On Error GoTo 0

We recommend that you use the TestComplete.TestCompleteApplication.Integration object to automate TestComplete. It provides access to higher-level functions specifically engineered to perform most typical user actions: open projects, run tests, stop test runs, and so on.

You can also use the TestComplete.TestCompleteApplication.Manager object to get deeper access to TestComplete internal objects and components. However, using this object is more complex, because calls to methods and properties of internal objects should match certain conditions adopted in TestComplete, execution of a simple action may require several complex calls, etc.

Automating TestComplete by Using the Integration Object

The TestComplete.TestCompleteApplication.Integration object includes all methods and properties needed to open a project, run a test, and so on.

Before reading how to use the Integration object to automate TestComplete, we recommend that you read the description of Integration’s methods and properties.

To learn how to use the Integration object to implement the common tasks, see Integration Object - Common Tasks.

Example

We will create simple code that will —

  • Connect to TestComplete.

  • Open a project.

  • Run a test.

  • Check results of the test.

C#

using System.Runtime.InteropServices;
using TestComplete;

...

namespace MyApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void button1_Click(object sender, EventArgs e)
        {
            // Invokes TestComplete upon a button click
            TestFunc();
        }

        private void TestFunc()
        {
            const string TCProgID = "TestComplete.TestCompleteApplication.14";
            object TestCompleteObject = null;

            // Obtains access to TestComplete
            try
            {
                TestCompleteObject = Marshal.GetActiveObject(TCProgID);
            }
            catch
            {
                try
                {
                    TestCompleteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TCProgID));
                }
                catch
                {
                }
            }

            if (TestCompleteObject == null) return;

            // Obtains ITestCompleteCOMManager
            TestComplete.ITestCompleteCOMManager TestCompleteManager = (TestComplete.ITestCompleteCOMManager) TestCompleteObject;
            // Obtains Integration object
            TestComplete.ItcIntegration IntegrationObject = TestCompleteManager.Integration;

            // We have a reference to the integration object.
            // Now we can use its methods and properties to automate TestComplete.

            // Loads the project suite
            IntegrationObject.OpenProjectSuiteEx("C:\\Documents and Settings\\All Users\\Documents\\TestComplete 14 Samples\\Common\\Test Log\\TestLog.pjs");

            try
            {
                // Runs the test
                IntegrationObject.RunProject("TestLog_C#Script");

                // Waits until testing is over
                while (IntegrationObject.IsRunning())
                    Application.DoEvents();

                // Check the results
                switch (IntegrationObject.GetLastResultDescription().Status)
                {
                    case TestComplete.TC_LOG_STATUS.lsOk:
                        System.Windows.Forms.MessageBox.Show(this, "The test run finished successfully.");
                        break;
                    case TestComplete.TC_LOG_STATUS.lsWarning:
                        System.Windows.Forms.MessageBox.Show(this, "Warning messages were posted to the test log.");
                        break;
                    case TestComplete.TC_LOG_STATUS.lsError:
                        System.Windows.Forms.MessageBox.Show(this, "Error messages were posted to the test log.");
                        break;
                }
            }
            catch (System.Runtime.InteropServices.COMException ex)
            {
                System.Windows.Forms.MessageBox.Show("An exception occurred: " + ex.Message);
            }
            finally
            {
                // Closes TestComplete
                TestCompleteManager.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestCompleteManager);
                Marshal.ReleaseComObject(TestCompleteObject);
            }
        }
    }
}

C# (using late binding, .NET 4+)

using System.Runtime.InteropServices;

...

namespace MyApp
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void button1_Click(object sender, EventArgs e)
        {
            // Invokes TestComplete upon a button click
            TestFunc();
        }

        private void TestFunc()
        {
            const string TCProgID = "TestComplete.TestCompleteApplication.14";
            dynamic TestCompleteObject = null;

            // Obtains access to TestComplete
            try
            {
                TestCompleteObject = Marshal.GetActiveObject(TCProgID);
            }
            catch
            {
                try
                {
                    TestCompleteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TCProgID));
                }
                catch
                {
                }
            }

            if (TestCompleteObject == null) return;
            
            // Obtains Integration object during runtime
            dynamic IntegrationObject = TestCompleteObject.Integration;

            // We have a reference to the integration object.
            // Now we can use its methods and properties to automate TestComplete.

            // Loads the project suite
            IntegrationObject.OpenProjectSuiteEx("C:\\Documents and Settings\\All Users\\Documents\\TestComplete 14 Samples\\Common\\Test Log\\TestLog.pjs");

            try
            {
                // Runs the test
                IntegrationObject.RunProject("TestLog_C#Script");

                // Waits until testing is over
                while (IntegrationObject.IsRunning())
                    Application.DoEvents();

                // Check the results
                if (IntegrationObject.GetLastResultDescription().Status == 0)
                {
                    System.Windows.Forms.MessageBox.Show(this, "The test run finished successfully.");
                }
                if (IntegrationObject.GetLastResultDescription().Status == 1)
                {
                    System.Windows.Forms.MessageBox.Show(this, "Warning messages were posted to the test log.");
                }
                if (IntegrationObject.GetLastResultDescription().Status == 2)
                {
                    System.Windows.Forms.MessageBox.Show(this, "Error messages were posted to the test log.");
                }

            }
            catch (System.Runtime.InteropServices.COMException ex)
            {
                System.Windows.Forms.MessageBox.Show("An exception occurred: " + ex.Message);
            }
            finally
            {
                // Closes TestComplete
                TestCompleteObject.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestCompleteObject);
            }
        }
    }
}

Visual Basic .NET

Imports System.Runtime.InteropServices
Imports TestComplete

...

Public Class Form1

    Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
        ' Invokes TestComplete upon a button click
        TestFunc()
    End Sub

    Private Sub TestFunc()
        Const TCProgID = "TestComplete.TestCompleteApplication.14"
        Dim TestCompleteObject As TestComplete.TestCompleteApplication = Nothing

        ' Obtains access to TestComplete
        Try
            TestCompleteObject = Marshal.GetActiveObject(TCProgID)
        Catch
            Try
                TestCompleteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TCProgID))
            Catch
            End Try
        End Try

        If (TestCompleteObject Is Nothing) Then Exit Sub

        ' Obtains Integration object
        Dim IntegrationObject As TestComplete.ItcIntegration = TestCompleteObject.Integration

        ' We have a reference to the integration object.
        ' Now we can use its methods and properties to automate TestComplete.

        ' Loads the project suite
        IntegrationObject.OpenProjectSuiteEx("C:\Documents and Settings\All Users\Documents\TestComplete 14 Samples\Common\Test Log\TestLog.pjs")

        Try
            ' Runs the test
            IntegrationObject.RunProject("TestLog_VBScript")
            ' Waits until testing is over
            While IntegrationObject.IsRunning
                Application.DoEvents()
            End While

            ' Check the results
            Select Case IntegrationObject.GetLastResultDescription.Status
                Case TestComplete.TC_LOG_STATUS.lsOk
                    System.Windows.Forms.MessageBox.Show(Me, "The test run finished successfully.")
                Case TestComplete.TC_LOG_STATUS.lsWarning
                    System.Windows.Forms.MessageBox.Show(Me, "Warning messages were posted to the test log.")
                Case TestComplete.TC_LOG_STATUS.lsError
                    System.Windows.Forms.MessageBox.Show(Me, "Error messages were posted to the test log.")
            End Select

        Catch ex As System.Runtime.InteropServices.COMException
            System.Windows.Forms.MessageBox.Show("An exception occurred: " + ex.Message)
        Finally
            ' Closes TestComplete
            TestCompleteObject.Quit()
            ' Releases COM objects
            Marshal.ReleaseComObject(IntegrationObject)
            Marshal.ReleaseComObject(TestCompleteObject)
        End Try
    End Sub

End Class

Visual Basic 6

Sub Test
  Dim TestCompleteApp As TestCompleteApplication, IntegrationObject As ItcIntegration, LastResult As ItcIntegrationResultDescription

  ' Creates the application object
  Set TestCompleteApp = CreateObject("TestComplete.TestCompleteApplication")

  ' Obtains the integration object
  Set IntegrationObject = TestCompleteApp.Integration

  ' Opens the project
  IntegrationObject.OpenProjectSuiteEx "C:\Documents and Settings\All Users\Documents\TestComplete 14 Samples\Common\Test Log\TestLog.pjs"

  ' Needed to process errors
  Err.Clear
  On Error GoTo Err_Label

  ' Starts the project run
  IntegrationObject.RunProject "TestLog_VBScript"

  ' Waits until the test is over
  While IntegrationObject.IsRunning
    DoEvents
  Wend

  ' Exports the results
  IntegrationObject.ExportResults("C:\Logs\Test_Results.mht", true)

  ' Checks the results
  Set LastResult = IntegrationObject.GetLastResultDescription
  Select Case LastResult.Status
    Case 0: MsgBox "The test run finished successfully."
    Case 1: MsgBox "Warning messages were posted to the test log."
    Case 2: MsgBox "Error messages were posted to the test log."
  End Select

Err_Label:
  ' Process errors
  If Err.Number <> 0 Then
    MsgBox "Cannot start the test. Reason: " + Err.Description, vbCritical, "Error"
  End If

  ' Closes TestComplete
  TestCompleteApp.Quit
End Sub

Notes

  • When you launch TestComplete via COM, it remains hidden. If you perform any actions that change the project while TestComplete is hidden, you will not see any messages and warnings, which TestComplete would show if it were visible. TestComplete will follow the default processing of these messages and warnings, and it may perform some undesired actions, for instance, it can save changes to the project that you may not want to save.

    To avoid possible issues, make TestComplete visible. To do this, assign True to the Visible property of the TestComplete COM object.

  • In .NET code, you must release all COM object references after closing TestComplete. To do this, call Marshal.ReleaseCOMObject for each variable that stores a COM object reference.

  • The methods you use to run tests (for example, Integration.RunProject), return immediately after the test run starts. If you close TestComplete while a test is running (for example, if you call Quit right after calling RunProject), TestComplete will show a message asking whether you want to close the application and terminate the test run. To avoid this message, you can use a loop that waits until the test run is over.

  • Test items to be run and various settings are stored in your TestComplete project file. When you start testing your application using the Integration.RunProject method, TestComplete uses the settings stored in your TestComplete project. Therefore, we recommend to prepare your project in TestComplete before you run that project with TestComplete via COM.

Alternatives

Run TestComplete and pass the needed command-line arguments to it. See TestComplete Command Line for more information.

See Also

Calling Script Routines via COM
TestComplete Command Line

Highlight search results