Relative paths in object descriptions

A relative path describes a UIA Pro test object in relation to its immediate parent rather than from the root window. This simplifies test maintenance when the parent's path changes.

In this topic:

About relative paths

The path property describes a UIA Pro object's position in the object hierarchy. Absolute paths represent the complete hierarchy starting from the root window. Relative paths describe an element in relation to its immediate parent.

By default, new test objects use absolute paths.

You can edit an object's path property to use a relative path in the Object Identification Center (OIC) or programmatically in the object description.

Relative paths are indicated by the tilde (~) character at the beginning of the path string.

Back to top

When to use relative paths

Use relative paths in the following scenarios:

• Parent hierarchy changes: When the application's structure above the parent object changes, tests using relative paths do not need to be updated.

• Reusable components: When you have reusable UI components that can appear in different locations within the application hierarchy.

• Simplified descriptions: When you want to make object descriptions more concise and easier to maintain.

Back to top

Rules for using relative paths

When working with relative paths, follow these rules:

• A test object with a relative path can be placed under a test object with an absolute path.

• Important: If a relative path is used for an object, all its descendants must also use relative paths.

Back to top

How to specify relative paths

You can specify relative paths in the Object Identification Center or programmatically in your test code.

To specify relative paths in the Object Identification Center:

1. Open the Object Identification Center.

2. Navigate to the test object you want to modify.

3. Locate the path property in the object's description.

4. Edit the path value to begin with the tilde (~) character, followed by the relative path elements.

5. Ensure all descendant objects also use relative paths.

To specify relative paths programmatically:

Specify relative paths directly in your test code when creating object descriptions.

Java Example

// Parent object with absolute path
Pane parentPane = Desktop.describe(Pane.class, new PaneDescription.Builder()
    .processName("MyApp")
    .name("Main Window")
    .path("Window;Pane;Pane")
    .frameworkId("Win32")
    .controlType("Pane").build());

// Child object with relative path (note the ~ prefix)
ListItem childListItem = parentPane.describe(ListItem.class, new ListItemDescription.Builder()
    .path("~List;ListItem")
    .frameworkId("Win32")
    .controlType("ListItem").build());

.NET Example

// Parent object with absolute path
var parentPane = Desktop.Describe<IPane>(new PaneDescription
{
    ProcessName = @"MyApp",
    Name = @"Main Window",
    Path = @"Window;Pane;Pane",
    FrameworkId = @"Win32",
    ControlType = @"Pane"
});

// Child object with relative path (note the ~ prefix)
var childListItem = parentPane.Describe<IListItem>(new ListItemDescription
{
    Path = @"~List;ListItem",
    FrameworkId = @"Win32",
    ControlType = @"ListItem"
});

JavaScript Example

// Parent object with absolute path
var parentPane = Desktop.$(UIAPro.Pane({
    processName: "MyApp",
    name: "Main Window",
    path: "Window;Pane;Pane",
    frameworkId: "Win32",
    controlType: "Pane"
}));

// Child object with relative path (note the ~ prefix)
var childListItem = parentPane.$(UIAPro.ListItem({
    path: "~List;ListItem",
    frameworkId: "Win32",
    controlType: "ListItem"
}));

Back to top

Benefits of relative paths

Using relative paths provides the following advantages:

• Improved maintainability: When the application's hierarchy changes above the parent object, child objects with relative paths do not need to be updated.

• Reduced test brittleness: Tests are less likely to break when the application structure evolves.

• Simpler object descriptions: Relative paths are typically shorter and easier to read than absolute paths.

• Reusability: Objects with relative paths can be more easily reused in different contexts within the application.

Back to top

Converting between absolute and relative paths

You can convert between absolute and relative paths as needed for your test scenarios.

To convert an absolute path to a relative path:

1. Identify the parent object in the hierarchy.

2. Determine the child's path elements that come after the parent's path.

3. Add the tilde (~) character at the beginning of these remaining path elements.

4. Update all descendants to also use relative paths.

To convert a relative path to an absolute path:

1. Identify the parent object's absolute path.

2. Remove the tilde (~) character from the child's relative path.

3. Prepend the parent's absolute path to the child's path elements, separated by semicolons.

Back to top

See also:

• UIA Pro best practices

• Tree navigation methods

• Use Traverse Mode for UIA Pro object identification