Description

Use this method to launch one or several instances of the given tested application. The application is launched in the mode specified by its Run Mode property. For example, if the tested application’s Run Mode property is set to Debug, the method will launch one new application instance. If the Run Mode property is set to Profile, TestComplete will launch the application under AQtime.

Declaration

ProgObj.Run(Count, IgnoreRunning, Timeout)

ProgObj	An expression, variable or parameter that specifies a reference to one of the objects listed in the Applies To section
Count	[in]	Optional	Integer	Default value: -1
IgnoreRunning	[in]	Optional	Boolean	Default value: False
Timeout	[in]	Optional	Integer	Default value: -1
Result	A `Process` or `AQtime` object

Applies To

The method is applied to the following objects:

AIRTestedApp, ClickOnceTestedApp, JavaTestedApp and 2 more objects, JavaWebStartTestedApp, TestedApp « Collapse the list

Parameters

The method has the following parameters.

Note: The parameters of the ClickOnceTestedApp.Run method are ignored. They are reserved for future implementation.

Count

Specifies the number of application instances to be run. If Count is less than 0, the method will run as many instances as the Count property specifies. If Count is 0, no instances will be run.

Note:

The number of instances to be launched depends on the IgnoreRunning parameter. If this parameter is True, the Run method launches as many application instances as the Count parameter specifies.

If the IgnoreRunning parameter is False (default), the total number of running instances cannot exceed the value specified by the Count parameter. Suppose, the Count parameter holds seven meaning that TestComplete can run a maximum of seven instances of your tested application. Suppose also, that five instances are already running. In this case, TestComplete will only run two new instances of the tested application (2 + 5 = 7).

The Count parameter is ignored if the Debug or Profile run mode is selected. If Profile mode is selected, TestComplete launches the application under AQtime, so the Count value is meaningless. If Debug mode is active, TestComplete always launches one application instance.

IgnoreRunning

The method can start several instances of the tested application (see note in the Count parameter description). The IgnoreRunning parameter specifies whether the method will ignore or take into account the number of running instances when launching the tested application.

Timeout

Specifies the number of milliseconds that the method will wait until the specified number of application instances have started. If Timeout is -1 the waiting time is unlimited.

Result Value

For applications with the Simple or RunAs run mode, as well as for AIR, Java, Java Web Start and ClickOnce applications, this method returns the process object that corresponds to the application instance that was launched last.

If the tested application’s run mode property is Debug, the Run method returns the process object that corresponds to the launched application instance.

If the Run Mode property is Profile, this method returns the AQtime object that contains methods for operating with the AQtime version that is specified by the run parameters. In this case, to obtain the process corresponding to the tested application, use the Sys.Process or Sys.WaitProcess method.

Remarks

The application is not launched if its Launch property is set to False.
Sometimes the TestedApp.Run method may hang the application. To call the application process, this method uses the WaitForInputIdle method, which is part of Win32 API. When WaitForInputIdle hangs, TestComplete hangs as well. To avoid this behavior, use the following workaround: create a batch file (.bat) that will call your application and add this file to the list of tested applications instead of the application.
To run an application under a specific user account, you can either activate the RunAs mode and then call the Run method or use the TestedApp.RunAs method.

Note that running applications under a different account requires that the Secondary Logon service be running in Windows.
In order to launch a tested application in Profile or RunAs mode, TestComplete must be running with administrator permissions (see Using TestComplete With Administrator Privileges).

Note:

When launching an application, the operating system displays a dialog box asking for your permission to run it. Due to certain limitations, the closing of this dialog box cannot be automated. You should close it manually, or modify User Account Control settings so that Windows does not display the dialog. See Using TestComplete With Administrator Privileges.

To run an application and trace events and exceptions, you can activate the Debug run mode and use the Run method or use methods of the DbgServices object.
To run the tested application under AQtime, you can also use the AQtimeIntegration and AQtime objects. For more information, see Integration With AQtime.
To close an application under test, you can use the TestedApp.Close or TestedApp.Terminate methods. To close any process in the system, call Process.Close or Process.Terminate.

Example

The following code tries to run a tested application and then uses the Exists property of the returned object to check if the application process was launched successfully.

JavaScript, JScript

p = TestedApps.Items(0).Run();
if( ! p.Exists)
// Application was not launched
...

Python

p = TestedApps.Items[0].Run()
if not p.Exists:
  Log.Message("Application was not launched")
  # ...

VBScript

Set p = TestedApps.Items(0).Run
If Not p.Exists Then
' Application was not launched
End If
...

DelphiScript

p := TestedApps.Items[0].Run;
if not p.Exists then
// Application was not launched
...