Understanding Object Identification

process > top-level window > controls > child elements

browser > web page > web page elements > child elements

All test objects and types are organized in the TestLeft library according to application technologies (web, WPF, Java, and others) and vendors (DevExpress, Telerik, and so on).

In your test code, you will require namespaces (for .NET code) or packages (for Java code) that contain test objects for your application type. For example, if you are testing a .NET Windows Forms application that uses DevExpress controls, use the following:

To access a specific object in a TestLeft test, use the Find method and provide a search pattern. A search pattern is a programmatic description of an object. It specifies unique properties and values for that object, such as the object type (button, edit, link, and so on), name assigned by the developers, and so on. The pattern class depends on your application type and object type (see the table below). The syntax looks as follows:

C#

Visual Basic .NET

Java

C#

Visual Basic .NET

Java

Example: Desktop application

Example: Desktop applicationExample: Desktop application

C#

Visual Basic .NET

Java

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.TestObjects;
...

// Run Notepad and get its process
IProcess notepad = Driver.Applications.Run("notepad");

// Find Notepad's edit area
ITextEdit edit = notepad.Find<ITopLevelWindow>(new WindowPattern()
{
   WndClass = "Notepad"
}).Find<ITextEdit>(new WindowPattern()
{
   WndClass = "Edit"
});

edit.SetText("Test");

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.TestObjects
...

' Run Notepad and get its process
Dim notepad As IProcess = Driver.Applications.Run("notepad")

' Find Notepad's edit area
Dim edit As ITextEdit = notepad.Find(Of ITopLevelWindow)(New WindowPattern() With {
   .WndClass = "Notepad"
}).Find(Of ITextEdit)(New WindowPattern() With {
   .WndClass = "Edit"
})

edit.SetText("Test")

Java

import com.smartbear.testleft.*;
import com.smartbear.testleft.testobjects.*;
...

// Run Notepad and get its process
TestProcess notepad = driver.getApplications().run("notepad");

// Find Notepad edit area
TextEdit edit = notepad.find(TopLevelWindow.class, new WindowPattern() {{
   WndClass = "Notepad";
}}).find(TextEdit.class, new WindowPattern() {{
   WndClass = "Edit";
}});

edit.setwText("Test");

Example: Web application

Example: Web applicationExample: Web application

C#

Visual Basic .NET

Java

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.TestObjects.Web;
...

// Start browser and open Google
IWebBrowser browser = Driver.Applications.RunBrowser(BrowserType.Chrome, "https://www.google.com");

// Get the page object
IWebPage page = browser.Find<IWebPage>(new WebPagePattern()
   {
      URL = "*google*"
   });

// Find an object on the web page
IWebElement searchbox = page.Find<IWebElement>(new WebElementPattern()
{
   ObjectType = "Textbox",
   idStr = "lst-ib"
}, 15);

searchbox.Keys("TestLeft[Enter]");

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.TestObjects.Web
...

' Start browser and open Google
Dim browser As IWebBrowser = Driver.Applications.RunBrowser(BrowserType.Chrome, "https://www.google.com")

' Get the page object
Dim page As IWebPage = browser.Find(Of IWebPage)(New WebPagePattern() With {
      .URL = "*google*"
   })

' Find an object on the web page
Dim searchbox As IWebElement = page.Find(Of IWebElement)(New WebElementPattern() With {
   .ObjectType = "TextBox",
   .idStr = "lst-ib"
}, 15)

searchbox.Keys("TestLeft[Enter]")

Java

import com.smartbear.testleft.*;
import com.smartbear.testleft.testobjects.*;
import com.smartbear.testleft.testobjects.web.*;
...

// Start browser and open Google
WebBrowser browser = driver.getApplications().runBrowser(BrowserType.Chrome, "https://www.google.com");

// Get the page object
WebPage page = browser.find(WebPage.class, new WebPagePattern() {{
  URL = "*google*";
}});

// Find an object on the web page
WebElement searchbox = page.find(WebElement.class, new WebElementPattern() {{
  ObjectType = "TextBox";
  idStr = "lst-ib";
}}, 15);

searchbox.keys("TestLeft[Enter]");

However, if you want to use an already running application or browser, you can also use the Find method to access a top-level object (process or browser).

Example: Desktop application

Example: Desktop applicationExample: Desktop application

C#

Visual Basic .NET

Java

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.TestObjects;
...

// Get the process that corresponds to Notepad
IProcess notepad = Driver.Find<IProcess>(new ProcessPattern()
{
   ProcessName = "notepad"
});

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.TestObjects
...

' Get the process that corresponds to Notepad
Dim notepad As IProcess = Driver.Find(Of IProcess)(New ProcessPattern() With {
   .ProcessName = "notepad"
})

Java

import com.smartbear.testleft.*;
import com.smartbear.testleft.testobjects.*;
...

// Get the process that corresponds to Notepad
TestProcess notepad = driver.find(TestProcess.class, new ProcessPattern() {{
  ProcessName = "notepad";
}});

Example: Web application

Example: Web applicationExample: Web application

C#

Visual Basic .NET

Java

C#

using SmartBear.TestLeft;
using SmartBear.TestLeft.TestObjects.Web;
...

// Get the running instance of the Chrome browser
IWebBrowser browser = Driver.Find<IWebBrowser>(new WebBrowserPattern()
{
   ObjectIdentifier = "chrome"
});
// Navigate to the web page
browser.ToUrl("https://smartbear.com");

Visual Basic .NET

Imports SmartBear.TestLeft
Imports SmartBear.TestLeft.TestObjects.Web
...

' Get the running instance of the Chrome browser
Dim browser As IWebBrowser = Driver.Find(Of IWebBrowser)(New WebBrowserPattern() With {
   .ObjectIdentifier = "chrome"
})
' Navigate to the web page
browser.ToUrl("https://smartbear.com")

Java

import com.smartbear.testleft.*;
import com.smartbear.testleft.testobjects.*;
import com.smartbear.testleft.testobjects.web.*;
...

// Get the running instance of the Chrome browser
WebBrowser browser = driver.find(WebBrowser.class, new WebBrowserPattern() {{
  ObjectIdentifier = "chrome";
}});
// Navigate to the web page
browser.toUrl("https://smartbear.com");

To get all the objects that match a search pattern, use the FindAll method.

C#

Visual Basic .NET

Java

C#

Visual Basic .NET

Java

The method will return a sequence of objects that match the pattern. To learn more about the FindAll method, see Searching for Test Objects.

The Find and FindAll methods have an optional parameter for the search depth. The search depth is relative to the parent object as seen in the UI Spy (1 = immediate child objects, 2 = child objects + their child objects, and so on). This allows you to skip intermediate objects so that instead of —

— you can use —

TestLeft can automatically generate the code to search for objects:

1. If needed, click on the UI Spy panel and configure the code generation settings. You can select an object (the Driver object, a process or browser, a top-level window or web page) starting from which the generated code will search for the needed object.

2. Select an object in UI Spy and then click Copy Identification to generate code to the clipboard.

   

3. Paste the code to your test.

The generated code can be long, because it includes code for intermediate objects in the hierarchy. Always review and tweak the generated code:

• Remove intermediate objects that do not have unique properties, such as web Panels without IDs. Remember to add or increase the search depth in Find calls that precede the deleted snippets.

• Introduce variables to store objects you want to re-use.

• Add more identification properties to make search conditions unique.

• Add the search depth if needed.

Example

ExampleExample

Consider this identification code generated for a search box on a web page. This code includes an index value (ObjectGroupIndex) and intermediate Panels without IDs (highlighted in red):

C#

Visual Basic .NET

Java

C#

ITextEdit searchBox = Driver.Find<IWebBrowser>(new WebBrowserPattern()
{
   ObjectIdentifier = "chrome"
}).Find<IWebPage>(new WebPagePattern() {
   URL = "http://mysite.com/",
   ObjectGroupIndex = 0
}).Find<IWebElement>(new WebElementPattern()
{
   ObjectType = "Panel"
}).Find<IWebElement>(new WebElementPattern()
{
   ObjectType = "Panel"
}).Find<IWebElement>(new WebElementPattern()
{
   ObjectType = "TextBox",
   idStr = "searchBox"
});

Visual Basic .NET

Dim searchBox As ITextEdit = Driver.Find(Of IWebBrowser)(New WebBrowserPattern() With{
   .ObjectIdentifier = "chrome"
}).Find(Of IWebPage)(New WebPagePattern() With {
   .URL = "http://mysite.com/",
   .ObjectGroupIndex = 0
}).Find(Of IWebElement)(New WebElementPattern() With {
   .ObjectType = "Panel"
}).Find(Of IWebElement)(New WebElementPattern() With {
   .ObjectType = "Panel"
}).Find(Of IWebElement)(New WebElementPattern() With {
   .ObjectType = "TextBox",
   .idStr = "searchBox"
})

Java

TextEdit searchBox = driver.find(WebBrowser.class, new WebBrowserPattern() {{
  ObjectIdentifier = "chrome";
}}).find(WebPage.class, new WebPagePattern() {{
  URL = "http://mysite.com/";
  ObjectGroupIndex = 0;
}}).find(WebElement.class, new WebElementPattern() {{
  ObjectType = "Panel";
}}).find(WebElement.class, new WebElementPattern() {{
  ObjectType = "Panel";
}}).find(WebElement.class, new WebElementPattern() {{
  ObjectType = "TextBox";
  idStr = "searchBox";
}});

To simplify the code, we can remove intermediate panels and add the search depth instead. We can also introduce a variable to store the web page object, so we can refer to it later in the test.

C#

Visual Basic .NET

Java

C#

IWebPage page = Driver.Find<IWebBrowser>(new WebBrowserPattern()
{
   ObjectIdentifier = "chrome"
}).Find<IWebPage>(new WebPagePattern() {
   URL = "http://mysite.com/"
});

ITextEdit searchBox = page.Find<IWebElement>(new WebElementPattern()
{
   ObjectType = "TextBox",
   idStr = "searchBox"
}, 3); // search depth

Visual Basic .NET

Dim page As IWebPage = Driver.Find(Of IWebBrowser)(New WebBrowserPattern() With{
   .ObjectIdentifier = "chrome"
}).Find(Of IWebPage)(New WebPagePattern() With {
   .URL = "http://mysite.com/"
})

Dim searchBox As ITextEdit = page.Find(Of IWebElement)(New WebElementPattern() With {
   .ObjectType = "TextBox",
   .idStr = "searchBox"
}, 3) ' search depth

Java

WebPage page = driver.find(WebBrowser.class, new WebBrowserPattern() {{
  ObjectIdentifier = "chrome";
}}).find(WebPage.class, new WebPagePattern() {{
  URL = "http://mysite.com/";
}});

TextEdit searchBox = page.find(WebElement.class, new WebElementPattern() {{
  ObjectType = "TextBox";
  idStr = "searchBox";
}}, 3);  // search depth

Search pattern initializers include only a few common properties, but you can add custom properties by using the Add method:

This syntax is equivalent to:

This way you can search by —

• any properties listed in the UI Spy
• nested properties like parentNode.tagName
• the CustomObjectType property that the test engine adds to web elements implemented with the Web Components specifications
• custom HTML attributes like ng-* attributes in AngularJS

You can use wildcards in string property values in search patterns to mask dynamic parts of the value.

Wildcard search is enabled by default, so there is no additional configuration involved.

You can use regular expressions in string property values in the search patterns. TestLeft regular expressions are strings in the "regexp:expression" format, for example, regexp:gr[ae]y. For the supported tokens, see Regular Expression Syntax.

Regular expressions in search patterns are always case-sensitive.

TestLeft searches for a partial match unless the regular expression contains the ^ (the beginning of a line) or $ (the end of a line) anchors. For example, regexp:hello is the same as regexp:.*hello.* and matches any string containing hello, but regexp:^hello$ matches the exact hello string.

In web applications, you can use FindChildByXPath and QuerySelector to find objects by XPath 1.0 expressions and CSS selectors.

The search pattern class depends on the application technology (web, WinForms, WPF, and so on) and object type. Some pattern classes are shared among all objects of a technology. For example, WPFPattern applies to all WPF controls – text boxes, buttons, and so on.

• .NET
• Java

There could be situations when several objects match the specified search criteria. Use the IDriver.Options.Debug.RuntimeChecks property to detect whether ambiguous object recognition has occurred. To learn more, see Troubleshoot Ambiguous Matches.

It may be convenient to separate the object identification code and the code that simulates user actions in your tests. You can do this by implementing object models (classes that describe the object hierarchy in a tested application). To learn more, see Mapping Test Objects.