Applies to TestLeft 4.20, last modified on September 11, 2019

About

TestLeft has a number of options that affect test runs and the object hierarchy in tested applications. You access these options through the Driver object (see the code below).

The changes you make to the options are effective only during your current test run. When the Driver object is initiated during the next test run, the options will be restored to their default values.

Here is how you can get to the options from code:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  // Configure TestLeft options
  Driver.Options.General.UseCaseSensitiveParameters = true;
  …

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  ' Configure TestLeft options
  Driver.Options.General.UseCaseSensitiveParameters = True
  …

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
// …
   
public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Configure TestLeft options
  driver.getOptions().getGeneral().setUseCaseSensitiveParameters(true);

  // Simulate user actions
  // …
}

Option Classes

To work with options, you use the following classes:

  • .NET: Classes in the SmartBear.TestLeft.Options namespace.

  • Java: Classes in the com.smartbear.testleft.options package.

The options are organized into the following categories:

General

The General class describes options that affect the TestLeft behavior during test runs:

Option Description
AutoWaitTimeout When a test gets a reference to a process, or a window or control, it may take a while for the object to become available. Likewise, when a test simulates an action against a control, the change in the control’s state may occur with a delay.

The option specifies the number of milliseconds the test waits for an object to become available or to change its state before the test reports a timeout error message.

Default value is 10000.

DraggingDelay The number of milliseconds it takes for a test to simulate the mouse cursor passing 20 pixels.

Can take values in the range between 0 and 1000. The default value is 0.

PostImageonError Specifies whether the test will post a desktop screenshot to the test log when an error occurs (including errors you post with the TestLeft.Log.Error method).
UseCaseSensitiveParameters Specifies whether methods that simulate user actions (Click, ClickItem, and so on) will process their string parameters as case-sensitive.

The following example demonstrates how to set general options:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  // Configure general test run options
  Driver.Options.General.AutoWaitTimeout = 3000;
  Driver.Options.General.PostImageOnError = false;

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  ' Configure general test run options
  Driver.Options.General.AutoWaitTimeout = 3000
  Driver.Options.General.PostImageOnError = False

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
// …
   
public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Configure TestLeft options
  driver.getOptions().getGeneral().setAutoWaitTimeout(3000);
  driver.getOptions().getGeneral().setPostImageOnError(false);

  // Simulate user actions
  // …
}

Flex

The Flex class describes options that affect testing of Flash and Flex applications:

Option Description
InstallFlashInjectorAtTestStart Specifies whether TestLeft should install the FlashInjector module when the test run starts.

FlashInjector is a helper Flash movie shipped with TestLeft. It allows TestLeft to access internal objects, properties and methods of Flash and Flex applications. To learn more about preparing Flash and Flex applications for testing, see Preparing Flash and Flex Applications for Testing Under the Debug Version of Flash Player.

The following example demonstrates how to edit Flex options in tests:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  // Configure Flex testing options
  Driver.Options.Flex.InstallFlashInjectorAtTestStart = true;

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  ' Configure Flex testing options
  Driver.Options.Flex.InstallFlashInjectorAtTestStart = True

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
// …
   
public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Configure TestLeft options
  driver.getOptions().getFlex().setInstallFlashInjectorAtTestStart(true);

  // Simulate user actions
  // …
}

JavaFX

The JavaFX class describes a list of JavaFX classes that TestLeft will recognize and include in the object hierarchy of JavaFX applications.

Use the class’s methods to manage the list of JavaFX classes:

Method Description
AddJavaFXClass (.NET)
addJavaFXClass (Java)
Adds a class to the list of recognized JavaFX classes and specifies whether TestLeft should include the class’s descendants in the object hierarchy as well.
GetJavaFXClass (.NET)
getJavaFXClass (Java)
Returns the current list of JavaFX classes.
RemoveAllJavaFXClasses (.NET)
removeAllJavaFXClasses (Java)
Clears the list of JavaFX classes.
SetJavaFXClasses (.NET)
setJavaFXClasses (Java)
Replaces the current list of JavaFX classes in TestLeft with a new list of classes. For each class in the list, you specify the class name and whether TestLeft should include derived classes in the object hierarchy as well.

The following example demonstrates how to work with a list of JavaFX classes:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  string myClassName = "javafx.scene.canvas.Canvas";

  // Get a list of JavaFX classes that TestLeft recognizes
  IList<SmartBear.TestLeft.Options.ClassFilterEntry> classList = Driver.Options.JavaFX.GetJavaFxClassesList();

  // If the class is not in the list, add the class
  if (classList != null && classList.All(p => p.ClassName != myClassName))
  {
    Driver.Options.JavaFX.AddJavaFxClass(myClassName, true);
  }

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

Dim myClassName = "javafx.scene.canvas.Canvas"

' Get a list of JavaFX classes that TestLeft recognizes
Dim classList As IList(Of SmartBear.TestLeft.Options.ClassFilterEntry) = Driver.Options.JavaFX.GetJavaFxClassesList

' If the class is not in the list, add the class
If classList IsNot Nothing And classList.All(Function(p) p.ClassName <> myClassName) Then
    Driver.Options.JavaFX.AddJavaFxClass(myClassName, True)
End If

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.options.OptionsManager.ClassFilterEntry;
import java.util.List;

// ...

public void Test() {
  LocalDriver driver = new LocalDriver();

  String myClassName = "javafx.scene.canvas.Canvas";

  // Get a list of JavaFX classes that TestLeft recognizes
  List<ClassFilterEntry> classList = driver.getOptions().getJavaFX().getJavaFxClassesList();

  if (classList != null) {
    // If the class is not in the list, add the class to the list
    if (! classList.stream().anyMatch(cls -> cls.getClassName().equals(myClassName))) {
      driver.getOptions().getJavaFX().addJavaFxClass(myClassName, true);
    } else {
        // Class is already in the list
        // ...
    }
  }

  // Simulate user actions
  // ...
}

MSAA, UIAutomation and TextRecognition

The MSAA, UIAutomation and TextRecognition classes describe a list of windows and controls that TestLeft will recognize by using Microsoft Active Accessibility (MSAA), UI Automation or by their text respectively.

Use class methods to manage the list of windows and controls that TestLeft will recognize by using the appropriate technology:

Method Description
AddWindow (.NET)
addWindow (Java)
Adds a class to the list of recognized windows and controls.
GetWindowList (.NET)
getWindowList (Java)
Returns the current list of recognized windows and controls.
RemoveAllWindows (.NET)
removeAllWindows (Java)
Clears the current list of recognized windows and controls.

The following example demonstrates how to work with a list of recognized controls in tests:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;


public void Test()
{

  string myClassName = "UIRibbonCommandBar";

  // Get a list of objects that TestLeft recognizes by using MSAA
  IList<string> classList = Driver.Options.MSAA.GetWindowList();

  // If the class name is not on the list, adds the class name
  if (! classList.Contains(myClassName))
  {
    Driver.Options.MSAA.AddWindow(myClassName);
  }

  // Simulate user actions
  …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options


Public Sub Test()

  Dim myClassName As String = "UIRibbonCommandBar"

  ' Gets a list of objects that TestLeft recognizes by using MSAA
  Dim classList As IList(Of String) = Driver.Options.MSAA.GetWindowList

  ' If the class name is not on the list, adds the class name
  If Not classList.Contains(myClassName) Then
    Driver.Options.MSAA.AddWindow(myClassName)
  End If

  ' Simulates user actions
  …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import java.util.List;
// …
public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  String myClassName = "UIRibbonCommandBar";

  // Get a list of objects that TestLeft recognizes by using MSAA
  List<String> classList = driver.getOptions().getMSAA().getWindowList();

  if (classList != null) {
    // If the class name is not on the list, add the class name
    if (! classList.stream().anyMatch(cls -> cls.equals(myClassName))) {
      driver.getOptions().getMSAA().addWindow(myClassName);
    } else {
      // Class name is already in the list
      // …
    }
  }   // Simulate user actions
  // …
}

To learn more about recognition technologies, see the following sections in TestComplete Help:

ObjectMapping

TestLeft engine recognizes controls in tested applications based on the controls’ class name. It analyzes the class name and casts the control to an object of the appropriate type. It is object mapping.

TestLeft supports the following controls:

Borland Controls

Developer Express Controls

Flex Controls

Infragistics Controls

JavaFX Controls

Microsoft Controls

Qt Controls

Rogue Wave Controls

Swing Controls

Syncfusion Controls

Telerik Controls

TMS Software

Win32 Controls and Windows

WPF Controls

Xceed Controls

For each supported control type, TestLeft provides a list of classes associated with that type.

To learn more about recognizing objects by their classes, see the Object Mapping section in TestComplete Help (the online version is available at Object Mapping).

The ObjectMapping class provides access to the list of supported controls and associated classes. To access them,you use the name of the appropriate control and the name of the technology, to which the control belongs, as it is specified on the ObjectMappingSettings.MappedObject list.

You can add your custom control’s class to a needed list to command TestLeft to recognize your custom control as an appropriate supported control.

The following example demonstrates how to map objects in tests:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  string className = "MyRibbonClass";

  // Get the Microsoft Controls category
  ObjectMappingSettings.MappedObject microsoftControl = Driver.Options.ObjectMapping["Microsoft Controls"];
  // Get the MFC category
  ObjectMappingSettings.MappedObject mfcControls = microsoftControl["MFC"];
  // Get the list of classes mapped to the MFCRibbonBar control
  ObjectMappingSettings.MappedObject mfcRibbon = mfcControls["MFCRibbonBar"];

  // Map a custom class to the MFCRibbonBar control
  mfcRibbon.AddClassName(className);

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  Dim className As String = "MyRibbonClass"

  ' Get the Microsoft Controls category
  Dim microsoftControl As ObjectMappingSettings.MappedObject = Driver.Options.ObjectMapping.Item("Microsoft Controls")
  ' Get the MFC category
  Dim mfcControls As ObjectMappingSettings.MappedObject = microsoftControl.Item("MFC")
  ' Get the list of classes mapped to the MFCRibbonBar control
  Dim mfcRibbon As ObjectMappingSettings.MappedObject = mfcControls.Item("MFCRibbonBar")

  ' Map a custom class to the MFCRibbonBar control
  mfcRibbon.AddClassName(className)

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.options.ObjectMappingSettings;
// …

public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  String className = "MyRibbonClass";

  // Get the Microsoft Controls category
  ObjectMappingSettings.MappedObject microsoftControl = driver.getOptions().getObjectMapping().get("Microsoft Controls");
  // Get the MFC category
  ObjectMappingSettings.MappedObject mfcControls = microsoftControl.get("MFC");
  // Get the list of classes mapped to the MFCRibbonBar control
  ObjectMappingSettings.MappedObject mfcRibbon = mfcControls.get("MFCRibbonBar");
  // Map a custom class to the MFCRibbonBar control
  mfcRibbon.addClassName(className);

  // Simulate user actions
  // …
}

ProcessFilter

TestLeft can access internal objects, methods, and properties of applications under test. Applications, to whose internals TestLeft has access, are called Open applications.

The ProcessFilter class specifies which processes TestLeft should recognize as open and which it should ignore. Filtering out unnecessary applications can increase your test performance.

Option Description
FilteringMode Specifies which applications TestLeft should recognize or ignore. Possible values:
  • IgnoreProcessesFromList - TestLeft will recognize all running applications except for the applications on the list.

  • UseAll - TestLeft will recognize all running applications.

  • UseOnlyProccesesFromList - TestLeft will recognize only applications on the list.

Use the ProcessFilterSettings.FilterMode enumeration to specify whether TestLeft should recognize or ignore the specified processes. Use the AddProcess method to add your application to the list of processes that TestLeft should recognize or ignore.

The following example demonstrates how to work with a list of processes that TestLeft recognizes:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  string appName = "MyApp";

  // Configure TestLeft to recognize only processes on the list
  Driver.Options.ProcessFilter.FilteringMode = ProcessFilterSettings.FilterMode.UseOnlyProcessesFromList;

  // Add a tested application to the list
  Driver.Options.ProcessFilter.AddProcess(appName);

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  Dim appName As String = "MyApp"

  ' Configure TestLeft to recognize only processes on the list
  Driver.Options.ProcessFilter.FilteringMode = ProcessFilterSettings.FilterMode.UseOnlyProcessesFromList

  ' Add a tested application to the list
  Driver.Options.ProcessFilter.AddProcess(appName)

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.options.ProcessFilterSettings;
// ...

public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  String appName = "MyApp";

  // Configures TestLeft to recognize only processes on the list
   driver.getOptions().getProcessFilter().setFilteringMode(ProcessFilterSettings.FilterMode.UseOnlyProcessesFromList);

  // Adds a tested application to the list
  driver.getOptions().getProcessFilter().addProcess(appName);

  // Simulate user actions
  // ...
}

WebTesting

The WebTesting class describes options that affect user actions that tests simulate against web browsers and web controls.

Option Description
PageLoadTimeout The number of milliseconds the test waits for a web page to be loaded. Default: 60000.

The following example demonstrates how to work with options that affect web testing:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …


public void Test()
{

  // Configure web testing options
  Driver.Options.WebTesting.PageLoadTimeout = 30000;

  // Simulate user actions
  IWebBrowser browser = Driver.Applications.RunBrowser(BrowserType.IExplorer, PlatformType.Any, "https://smartbear.com/");
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  ' Configure web testing options
  Driver.Options.WebTesting.PageLoadTimeout = 30000

  ' Simulate user actions
  Dim browser As IWebBrowser = Driver.Applications.RunBrowser(BrowserType.IExplorer, PlatformType.Any, "https://smartbear.com/")
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.testobjects.web.WebBrowser;
import com.smartbear.testleft.BrowserType;
import com.smartbear.testleft.PlatformType;
// ...

public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Configures web testing options
  driver.getOptions().getWebTesting().setPageLoadTimeout(30000);

  // Simulate user actions
  WebBrowser browser = driver.getApplications().runBrowser(BrowserType.IExplorer, PlatformType.any, "https://smartbear.com/");
  // ...
}

WPF

The WPF class describes the options that control which objects are included in the object hierarchy in UI Spy.

These options affect the object identification code that TestLeft generates for WPF applications. Make sure you use the same options both when creating and when running tests; otherwise, the object identification code will become invalid.
Option Description
SimplifiedObjectTree Specifies how TestLeft UI Spy shows the hierarchy of WPF applications.

If false (the default value), UI Spy shows the actual hierarchy of objects in tested WPF applications, including intermediate container objects.

If true, UI Spy omits content layout containers (such as panels, borders, decorators and others) in the object hierarchy.

To specify how TestLeft UI Spy should manage template-generated elements in composite WPF controls, use the following methods of the WPF class:

Method Description
GetCompositeControls (.NET)
getCompositeControls(Java)
Returns a list of composite WPF controls whose template-generated elements UI Spy will expose.
SetCompositeControls (.NET)
setCompositeControls (Java)
Replaces the current list of composite WPF controls, whose template-generated elements UI Spy will expose, with a new list.
GetCompositeItemsControls (.NET)
getCompositeItemsControls (Java)
Returns a list of WPF controls whose composite items UI Spy will expose.
SetCompositeItemsControls (.NET)
setCompositeItemsControls (Java)
Replaces the current list of WPF controls, whose composite items UI Spy will expose, with a new list.

The following example demonstrates how to work with WPF options:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;


[TestMethod]
public void Test()
{
  // Enable the simplified object hierarchy
  Driver.Options.WPF.SimplifiedObjectTree = true;

  // Add a control to the list of complex controls
  // TestLeft will expose the template-generated elements of the control
  Driver.Options.WPF.SetCompositeControls(
  new List<WPFSettings.CompositeControlDescription>
  {
        new WPFSettings.CompositeControlDescription()
        {
                ClassName = "System.Windows.Controls.ListBox" }
  });

  // Simulate user actions
  …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options


<TestMethod()>
Public Sub Test()
  ' Enable the simplified object hierarchy
  Driver.Options.WPF.SimplifiedObjectTree = True

  ' Add a control to the list of complex controls
  ' TestLeft will expose the template-generated elements of the control
  Driver.Options.WPF.SetCompositeControls(
  New List(Of WPFSettings.CompositeControlDescription) From {
    New WPFSettings.CompositeControlDescription() With {
      .ClassName = "System.Windows.Controls.ListBox"
    }
  })

  ' Simulates user actions
  …

End Sub

Java

import java.util.ArrayList;
import java.util.List;
import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.options.OptionsManager;

public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Enable the simplified object hierarchy
  driver.getOptions().getWPF().setSimplifiedObjectTree(true);

  // Add a control to the list of complex controls
  // TestLeft will expose the template-generated elements of the control
  List<OptionsManager.WPFSettings.CompositeControlDescription> list = new ArrayList<OptionsManager.WPFSettings.CompositeControlDescription>();
  OptionsManager.WPFSettings.CompositeControlDescription item = new OptionsManager.WPFSettings.CompositeControlDescription();
  item.setClassName("System.Windows.Controls.ListBox");
  list.add(item);

  // Simulate user actions
  // …

}

To learn more about recognizing WPF controls, see Identifying WPF Objects.

Debug

The Debug class includes options that assist in debugging your tests during code execution.

Option Description
RuntimeChecks Specifies what types of object verifications to perform at runtime. Possible values:
  • None - Default. Do not perform any verifications.

  • TypeCast - Verify if the result of the Find, FindAll, TryFind or Cast method can be cast to the desired type. Throws an exception if casting to an unsupported interface.

  • AmbiguousMatches - Verify if the search pattern of the Find and TryFind methods returns multiple objects. Throws an exception if several objects match the specified search pattern.

  • All - Perform all available verifications.

The following example demonstrates how to work with debugging test options:

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.Options;
// …

public void Test()
{

  // Perform additional checks during code execution
  Driver.Options.Debug.RuntimeChecks = Options.RuntimeChecks.All;

  // Simulate user actions
  // …

}

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.Options
' …

Public Sub Test()

  ' Perform additional checks during code execution
  Driver.Options.Debug.RuntimeChecks = Options.RuntimeChecks.All

  ' Simulate user actions
  ' …

End Sub

Java

import com.smartbear.testleft.LocalDriver;
import com.smartbear.testleft.options.RuntimeChecks;
// …

public void Test() throws Throwable {
  LocalDriver driver = new LocalDriver();

  // Perform additional checks during code execution
  driver.getOptions().getDebug().setRuntimeChecks(RuntimeChecks.All);

  // Simulate user actions
  // …
}

Managing Options at Design Time

Some TestLeft options (like, MSAA or WPF) affect the object hierarchy that the UI Spy shows. You may want to configure those options at design time when writing object identification code for your tests.

Currently, there is no direct way to configure TestLeft options at design time, but you can use the following workaround:

  1. Create a dummy test that will set the needed TestLeft options. For example, the following code enables the simplified object hiearchy in WPF applications:

    C#

    [TestMethod]
    public void Test()
    {
      // Enables the simplified object hiearchy
      Driver.Options.WPF.SimplifiedObjectTree = true;
    }

    Visual Basic .NET

    <TestMethod()>
    Public Sub Test()
      ' Enables the simplified object hiearchy
      Driver.Options.WPF.SimplifiedObjectTree = True
    End Sub

    Java

    @Test
    public void Test()
    {
      LocalDriver driver = new LocalDriver();

      // Enables the simplified object hiearchy
      driver.getOptions().getWPF().setSimplifiedObjectTree(true);

      // ...
    }

  2. Run the test.

  3. Changes in options will be effective throughout the test run.

  4. After the test run is over, open UI Spy and examine the object tree (refresh the object tree, if needed).

  5. UI Spy will apply the new setting.

Changes in options will remain effective until you start another test.

Make sure the options you use during the test run are the same you use when writing test code. Otherwise, the object identification code will become invalid and your tests will fail.

See Also

TestLeft Reference

Highlight search results