Working With TestExecute via COM - Overview

Applies to TestExecute 14.91, last modified on July 1, 2021

TestExecute 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 TestExecute via COM from a Visual Basic application and a managed (C#) application.

TestExecute cannot work simultaneously with TestComplete or another TestExecute instance.

When you launch TestExecute via COM, TestExecute does not display its icon in the system notification area (tray).

Requirements

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

To learn how to configure the privilege level, see —

Configuring Manifests on Windows 8 and Windows 10

Adding a Reference to the TestComplete Library

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

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

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

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

  4. 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 <TestExecute>\Bin\TestExecute.exe file.

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

Note: TestExecute is created on the TestComplete platform. Both products use the same type libraries, so you should select the TestComplete Library item in the Add Reference or References dialog.

If you have both products installed on your computer, you may see more than one TestComplete Library (TypeLib Version: 14.xx) item in the dialog. To make sure that you use the TestExecute object library, add it directly by pressing Browse and selecting the <TestExecute>\Bin\TestExecute.exe file in the ensuing Open File dialog.

Connecting to TestExecute via COM

TestExecute has the following program identifiers:

  • 32-bit version:

    TestExecute.TestExecuteApplication

    TestExecute.TestExecuteApplication.14

  • 64-bit version:

    TestExecute.TestExecuteX64Application

    TestExecute.TestExecuteX64Application.14

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

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

C#

const string TCProgID = "TestExecute.TestExecuteApplication.14";

object TestExecuteObject = null;

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

Visual Basic .NET

Const TCProgID = "TestExecute.TestExecuteApplication.14"

Dim TestExecuteObject As TestExecute.TestExecuteApplication = Nothing

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

Visual Basic 6

Const TCProgID As String = "TestExecute.TestExecuteApplication.14"

Dim TestExecuteObject As TestExecuteApplication

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

We recommend that you use the TestExecute.TestExecuteApplication.Integration object to automate TestExecute. 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 TestExecute.TestExecuteApplication.Manager object to get deeper access to TestExecute’s 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 TestExecute, execution of a simple action may require several complex calls, etc.

Automating TestExecute by Using the Integration Object

The TestExecute.TestExecuteApplication.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 TestExecute, we recommend that you read the description of Integration’s methods and properties in the TestComplete documentation.

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

Example

We will create simple code that will —

  • Connect to TestExecute.
  • 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 TestExecute upon a button click
            TestFunc();
        }

        private void TestFunc()
        {
            const string TCProgID = "TestExecute.TestExecuteApplication.14";
            object TestExecuteObject = null;

            // Obtains access to TestExecute
            try
            {
                TestExecuteObject = Marshal.GetActiveObject(TEProgID);
            }
            catch
            {
                try
                {
                    TestExecuteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TEProgID));
                }
                catch
                {
                }
            }

            if (TestExecuteObject == 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 TestExecute.

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

            // Checks whether the project suite was opened
            // If the project suite cannot be opened, closes TestExecute
            if (!IntegrationObject.IsProjectSuiteOpened())
            {
                System.Windows.Forms.MessageBox.Show("Could not open the project suite.");
                // Closes TestExecute
                TestExecuteManager.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestExecuteManager);
                Marshal.ReleaseComObject(TestExecuteObject);
                return;
            }

            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 TestExecute
                TestExecuteManager.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestExecuteManager);
                Marshal.ReleaseComObject(TestExecuteObject);
            }
        }
    }
}

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 TestExecute upon a button click
            TestFunc();
        }

        private void TestFunc()
        {
            const string TCProgID = "TestExecute.TestExecuteApplication.14";
            dynamic TestExecuteObject = null;

            // Obtains access to TestExecute
            try
            {
                TestExecuteObject = Marshal.GetActiveObject(TEProgID);
            }
            catch
            {
                try
                {
                    TestExecuteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TEProgID));
                }
                catch
                {
                }
            }

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

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

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

            // Checks whether the project suite was opened
            // If the project suite cannot be opened, closes TestExecute
            if (!IntegrationObject.IsProjectSuiteOpened())
            {
                System.Windows.Forms.MessageBox.Show("Could not open the project suite.");
                // Closes TestExecute
                TestExecuteObject.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestExecuteObject);
                return;
            }
            
            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 TestExecute
                TestExecuteObject.Quit();
                // Releases COM objects
                Marshal.ReleaseComObject(IntegrationObject);
                Marshal.ReleaseComObject(TestExecuteObject);
            }
        }
    }
}

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 TestExecute upon a button click
        TestFunc()
    End Sub

    Private Sub TestFunc()
        Const TEProgID = "TestExecute.TestExecuteApplication.14"
        Dim TestExecuteObject As TestExecute.TestExecuteApplication = Nothing

        ' Obtains access to TestExecute
        Try
            TestExecuteObject = Marshal.GetActiveObject(TEProgID)
        Catch
            Try
                TestExecuteObject = Activator.CreateInstance(Type.GetTypeFromProgID(TEProgID))
            Catch
            End Try
        End Try

        If (TestExecuteObject Is Nothing) Then Exit Sub

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

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

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

        ' Checks whether the project suite was opened
        ' If the project suite cannot be opened, closes TestExecute
        If (Not IntegrationObject.IsProjectSuiteOpened) Then
            System.Windows.Forms.MessageBox.Show("Could not open the project suite.")
            ' Closes TestExecute
            TestExecuteObject.Quit()
            ' Releases COM objects
            Marshal.ReleaseComObject(IntegrationObject)
            Marshal.ReleaseComObject(TestExecuteObject)
            Exit Sub
        End If

        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 TestExecute
            TestExecuteObject.Quit()
            ' Releases COM objects
            Marshal.ReleaseComObject(IntegrationObject)
            Marshal.ReleaseComObject(TestExecuteObject)
        End Try
    End Sub

End Class

Visual Basic 6

Sub Test
  Dim TestExecuteApp As TestExecuteApplication, IntegrationObject As ItcIntegration, LastResult As ItcIntegrationResultDescription
  
  ' Creates the application object
  Set TestExecuteApp = CreateObject("TestExecute.TestExecuteApplication")
  
  ' Obtains the integration object
  Set IntegrationObject = TestExecuteApp.Integration
  
  ' Opens the project
  IntegrationObject.OpenProjectSuite "C:\Documents and Settings\All Users\Documents\TestExecute 14 Samples\Scripts\Test Log\TestLog.pjs"
  
  ' Checks whether the project suite was opened
  ' If the project suite cannot be opened, closes TestExecute
  If Not IntegrationObject.IsProjectSuiteOpened Then
    MsgBox "The project suite was not opened."
    ' Closes TestExecute
    TestExecuteApp.Quit
    Exit Sub
  End If
  
  ' 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
  
  ' 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 TestExecute
  TestExecuteApp.Quit
End Sub

Notes

  • In .NET code, you must release all COM object references after closing TestExecute. 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 TestExecute while a test is running (for example, if you call Quit right after calling RunProject), TestExecute 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 TestExecute project file. When you start testing your application using the RunProject method of the Integration object, TestExecute uses the settings stored in your TestExecute project. Therefore, we recommend to prepare your project in TestExecute before you run that project with TestExecute via COM.

Alternatives

  • Connected Applications interact with TestComplete and TestExecute via COM. Any Visual Basic, Visual C++, C++Builder, C# or Delphi application can be made a connected application by linking a single file. See TestComplete help for information on creating Connected Applications.

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

See Also

TestExecute Command Line
Calling Script Routines via COM

Highlight search results