Control Search

A list of attributes for control search.

General

Term - in the scope of Atata is the text that is used to find a control. It can be id, name, class, etc.

Term

The attribute that specifies the term(s) to use for the control search.

Example

In the both following examples some-input is the term that is used for the control search:

[FindById("some-input")]
public TextInput<_> FirstName { get; private set; }

[FindById]
[Term("some-input")]
public TextInput<_> FirstName { get; private set; }

Parameters

TermCase

termCase

The term case.

TermMatch

match

The match.

params string[]

values

The term values.

Properties

public string

Format { get; set; }

Gets or sets the format.

public bool

CutEnding { get; set; }

Gets or sets a value indicating whether the name should be cut considering the IgnoreNameEndings property value of [ControlDefinition] and [PageObjectDefinition] attributes. The default value is true.

Multiple Terms

It is also possible to set multiple terms for the control finding.

For example the same form can have the save button with the different text values: “Create” for the new entity and “Update” for the existing one.

<button>Create</button>

and

<button>Update</button>

It can be defined like the same button in the page object:

[Term("Create", "Update")]
public Button<_> Save { get; private set; }

The control can be found by any of the term values defined.

TermMatch

The enumeration that specifies the match approach for the term finding.

By default all find attributes use Equals value.

Example

<input type="text" id="ctl00$MainContent$FirstName">

[FindById(TermMatch.EndsWith, "FirstName")]
public TextInput<_> FirstName { get; private set; }

Values

Equals

Checks whether the text equals the specified term.

Contains

Checks whether the text contains the specified term.

StartsWith

Checks whether the text starts with the specified term.

EndsWith

Checks whether the text ends with the specified term.

TermCase

The enumeration that specifies the term case. Each of TermFindAttribute attributes specifies its default term case.

Example

The following example applies the finding by first_name id:

[FindById(TermCase.Snake)]
public TextInput<_> FirstName { get; private set; }

Values

None

Doesn’t apply the case.

Title

Uses title case (e.g. "Some of the Terms").

Capitalized

Uses title case with all words capitalized (e.g. "Some Of The Terms").

Sentence

Uses sentence case (e.g. "Some term").

MidSentence

Uses mid-sentence case where the first word is not capitalized (e.g. "some term").

Lower

Uses lower case (e.g. "some term").

LowerMerged

Uses lower case with words merging (e.g. "someterm").

Upper

Uses upper case (e.g. "SOME TERM").

UpperMerged

Uses upper case with words merging (e.g. "SOMETERM").

Camel

Uses camel case (e.g. "someTerm").

Pascal

Uses pascal case (e.g. "SomeTerm").

Kebab

Uses dash (‘-‘) and lower case (e.g. "some-term").

HyphenKebab

Uses hyphen (‘‐’) and lower case (e.g. "some‐term").

PascalKebab

Uses dash (‘-‘) and pascal case (e.g. "Some-Term").

PascalHyphenKebab

Uses hyphen (‘‐’) and pascal case (e.g. "Some‐Term").

Snake

Uses underscore (‘_’) and lower case (e.g. "some_term").

Visibility

The enumeration that specifies the visibility of the element/control.

By default all find attributes use Visible value.

Values

Visible

Finds only the visible elements.

Hidden

Finds only the hidden elements.

Any

Finds the elements with any visibility.

ScopeSource

The enumeration that specifies the source scope.

By default all find attributes use Parent value, meaning that every control is searched in the scope of the parent control.

Values

Parent

Uses the parent’s scope.

Grandparent

Uses the grandparent’s (the parent of the parent) scope.

PageObject

Uses the owner page object’s scope.

Page

Uses the page’s scope (<body> element).

FindAs

The enumeration that specifies the way FindAttribute should be used.

By default, FindAttribute uses Scope value, meaning to use the attribute as a scope element locator.

Other values set the attribute to be a layered one.

Values

Scope

Use the attribute as a scope element locator.

Parent

Use the attribute as a parent layer. It means that the scope element or next layer element is located as a child of this one in DOM.

Ancestor

Use the attribute as an ancestor layer. It means that the scope element or next layer element is located as a descendant of this one in DOM.

ShadowHost

Use the attribute as a shadow host layer. It means that the scope element or next layer element is located inside the shadow root of this one in DOM.

Sibling

Use the attribute as a sibling layer. It means that the scope element or next layer element is located as a sibling of this one in DOM.

Base Attributes

FindAttribute

Represents the base attribute class for the finding attributes.

Properties

public int

Index { get; set; }

Gets or sets the index of the control. The default value is -1, meaning that the index is not used.

public Visibility

Visibility { get; set; }

Gets or sets the visibility. The default value is Visibility.Visible.

public ScopeSource

ScopeSource { get; set; }

Gets or sets the scope source. The default value is ScopeSource.Parent.

public string

OuterXPath { get; set; }

Gets or sets the outer XPath. The default value is null, meaning that the control is searchable as descendant (using “.//” XPath) in scope source.

public Type

Strategy { get; set; }

Gets or sets the strategy type for the control search. Strategy type should implement IComponentScopeLocateStrategy. The default value is null, meaning that the default strategy of the specific FindAttribute should be used.

public double

Timeout { get; set; }

Gets or sets the element find timeout in seconds. The default value is taken from AtataContext.ElementFindTimeout property of AtataContext.Current.

public double

RetryInterval { get; set; }

Gets or sets the element find retry interval in seconds. The default value is taken from AtataContext.ElementFindRetryInterval property of AtataContext.Current.

public FindAs

As { get; set; }

Gets or sets the way this FindAttribute should be used. The default value is FindAs.Scope. Each control can have 1 FindAttribute with FindAs.Scope value and many other FindAttributes with another FindAs values, which are used as layers. When several layer attributes are used, then Layer property can be used to specify an order of each attribute.

public int

Layer { get; set; }

Gets or sets the layer order of find attribute. It is useful to specify the order of the layer when several layers are used. This property is used only paired with As property set to any value except FindAs.Scope. The default value is 0.

TermFindAttribute

Represents the base attribute class for the finding attributes that use terms.

Inherited from FindAttribute.

Parameters

TermCase

termCase

The term case.

TermMatch

match

The match.

params string[]

values

The term values.

Properties

public string

Format { get; set; }

Gets or sets the format.

public bool

CutEnding { get; set; }

Gets or sets a value indicating whether the name should be cut considering the IgnoreNameEndings property value of [ControlDefinition] and [PageObjectDefinition] attributes. The default value is true.

protected abstract TermCase

DefaultCase { get; }

Gets the default term case. It is protected abstract property that should be overridden to specify the most suitable value.

protected virtual TermMatch

DefaultMatch { get; }

Gets the default match. The default value is Equals. It is protected virtual property that can be overridden.

Find Attributes

FindById

Specifies that a control should be found by id attribute. Finds the descendant or self control in the scope of the element having the specified id. Uses Kebab as the default term case.

Inherited from TermFindAttribute.

<input type="text" id="first-name">

[FindById]
public TextInput<_> FirstName { get; private set; }

Also can be found inside the element having the specified id:

<div id="first-name-wrapper">
    <input type="text">
</div>

[FindById("first-name-wrapper")]
public TextInput<_> FirstName { get; private set; }

In this case the first occurrence of the input in the element with id="first-name-wrapper" will be found.

FindByName

Specifies that a control should be found by name attribute. Finds the descendant or self control in the scope of the element having the specified name. Uses Kebab as the default term case.

Inherited from TermFindAttribute.

<input type="text" name="First-Name">

[FindByName(TermCase.PascalKebab)]
public TextInput<_> FirstName { get; private set; }

FindByClass

Specifies that a control should be found by class attribute. Finds the descendant or self control in the scope of the element having the specified class. Uses Kebab as the default term case.

Inherited from TermFindAttribute.

<div class="first-name-section some-other-class">
    <input type="text">
</div>

[FindByClass("first-name-section")]
public TextInput<_> FirstName { get; private set; }

FindByXPath

Specifies that a control should be found by XPath. Finds the descendant or self control in the scope of the element found by the specified XPath.

Inherited from FindAttribute.

<div id="container">
    <span>
        <input type="text">
    </span>
</div>

[FindByXPath("div[@id='container']/span/input[1]")]
public TextInput<_> FirstName { get; private set; }

Also can be found using inner XPath or the attribute condition:

<div id="container">
    <a href="prev">
        <span class="left-arrow"></span>
    </a>
    <a href="next">
        <span class="right-arrow"></span>
    </a>
</div>

[FindByXPath("@href='prev'")]
public Link<_> Previous { get; private set; }

[FindByXPath("[span[@class='right-arrow']]")]
public Link<_> Next { get; private set; }

FindByCss

Specifies that a control should be found by CSS selector. Finds the descendant or self control in the scope of the element found by the specified CSS selector.

Inherited from FindAttribute.

<div class="first-name-section">
    <input type="text">
</div>

[FindByCss("div.first-name-section")]
public TextInput<_> FirstName { get; private set; }

FindByLabel

Specifies that a control should be found by the label element. Finds the <label> element by the specified term(s), then finds the bound control (for example, by label’s for attribute referencing the element of the control by id). Uses Title as the default term case.

Inherited from TermFindAttribute.

<div class="form-group">
    <label for="exampleInputPassword1">Password</label>
    <input type="password" class="form-control" id="exampleInputPassword1">
</div>

[FindByLabel]
public PasswordInput<_> Password { get; private set; }

The example first finds the label element by the content text “Password” (taken from the name of the property), then gets for attribute value and finds the control by “exampleInputPassword1” id.

FindByFieldSet

Specifies that a control should be found by the parent fieldset element. Finds the descendant control in the scope of the <fieldset> element that has the <legend> element matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<fieldset>
    <legend>Gender</legend>
    <input type="radio">Male
    <br>
    <input type="radio">Female
</fieldset>

[FindByFieldSet]
public RadioButtonList<Gender, _> Gender { get; private set; }

public enum Gender
{
    Male,
    Female
}

FindByDescriptionTerm

Specifies that a control should be found by the description list term element. Finds the descendant control of the <dd> element in the scope of the <dl> element that has the <dt> element matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<dl>
    <dt>Office</dt>
    <dd>London</dd>
</dl>

[FindByDescriptionTerm]
public Text<_> Office { get; private set; }

FindByContent

Specifies that a control should be found by the content text. Finds the control having the specified content. Uses Title as the default term case.

Inherited from TermFindAttribute.

<button>Save</button>

[FindByContent]
public Button<_> Save { get; private set; }

FindByChildContent

Specifies that a control should be found by the child content text. Finds the control having the child with the specified content. Uses Title as the default term case.

Inherited from TermFindAttribute.

<a href="/products">
    <span class="icon-products"></span>
    <span class="item-name">Products</span>
    <span class="item-count">15</span>
</a>

[FindByChildContent(ChildIndex = 1)]
public Link<_> Products { get; private set; }

Properties

public int

ChildIndex { get; set; }

Gets or sets the index of the child element. The default value is 0.

FindByAttribute

Specifies that a control should be found by the specified attribute. Finds the control that has the specified attribute matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<input type="text" data-value="FirstName">

[FindByAttribute("data-value", TermCase.None)]
public TextInput<_> FirstName { get; private set; }

FindByValue

Specifies that a control should be found by the value attribute. Finds the control that has the value attribute matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<input type="button" value="Add Product">

[FindByValue]
public Button<_> AddProduct { get; private set; }

FindByContentOrValue

Specifies that a control should be found by the content text or value attribute. Finds the control that has the content or value attribute matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<input type="button" value="Save">
<button>Cancel</button>

[FindByContentOrValue]
public Button<_> Save { get; private set; }

[FindByContentOrValue]
public Button<_> Cancel { get; private set; }

FindByPlaceholder

Specifies that a control should be found by the placeholder attribute. Finds the control that has the placeholder attribute matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<input type="text" placeholder="First Name">

[FindByPlaceholder]
public TextInput<_> FirstName { get; private set; }

FindByTitle

Specifies that a control should be found by the title attribute. Finds the control that has the title attribute matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<button title="Add Product">
    <img src="/icon-add.png" width="32" height="32">
</button>

[FindByTitle]
public Button<_> AddProduct { get; private set; }

FindByTestId

Specifies that a control should be found by the DOM test identifier attribute, data-testid by default. Finds the control that has the test identifier attribute matching the specified term(s). Uses TermCase.Kebab as the default term case.

Inherited from TermFindAttribute.

<button data-testid="add-product">
    <img src="/icon-add.png" width="32" height="32">
</button>

[FindByTestId]
public Button<_> AddProduct { get; private set; }

Configuration

The DOM test identifier attribute can be configuured through UseDomTestIdAttributeName and UseDomTestIdAttributeDefaultCase methods of AtataContextBuilder.

AtataContext.GlobalConfiguration
    .UseDomTestIdAttributeName("data-autoid")
    .UseDomTestIdAttributeDefaultCase(TermCase.PascalKebab);

FindByAriaLabel

Specifies that a control should be found by the aria-label attribute. Finds the control that has the aria-label attribute matching the specified term(s). Uses TermCase.Sentence as the default term case.

Inherited from TermFindAttribute.

<button aria-label="Close">
    ...
</button>

[FindByAriaLabel]
public Button<_> Close { get; private set; }

FindByAriaLabelledBy

Specifies that a control should be found by the aria-labelledby attribute. Finds the control that has the aria-labelledby attribute matching the specified term(s). Uses TermCase.Kebab as the default term case.

Inherited from TermFindAttribute.

<button aria-labelledby="color">Red</button>
<span id="color">Yellow</span>

[FindByAriaLabelledBy]
public Button<_> Color { get; private set; }

FindByRelativeElementContent

Specifies that a control should be found by the content text of the relative element using its XPath. Uses TermCase.Title as the default term case.

Inherited from TermFindAttribute.

<input type="text" />
<label>User Name</label>

[FindByRelativeElementContent("following-sibling::*[1]", "User Name")]
public TextInput<_> UserName { get; private set; }

FindByPrecedingSiblingContent

Specifies that a control should be found by the content text of the preceding sibling. Uses TermCase.Title as the default term case.

Inherited from TermFindAttribute.

<span>User Name</span>
<input type="text" />

[FindByPrecedingSiblingContent("User Name")]
public TextInput<_> UserName { get; private set; }

FindFirst

Indicates that a control should use the first occurring element matching the control’s definition.

Inherited from FindAttribute.

<input type="password">

[FindFirst]
public PasswordInput<_> Password { get; private set; }

FindLast

Indicates that a control should use the last occurring element matching the control’s definition.

Inherited from FindAttribute.

<button>Button 1</button>
<button>Button 2</button>
<button>Button 3</button>

[FindLast]
public Button<_> Button3 { get; private set; }

FindByIndex

Specifies that a control should use the nth occurring element matching the control’s definition.

Inherited from FindAttribute.

<label>
    <input type="radio" name="gender" value="Male" />Male
</label>
<label>
    <input type="radio" name="gender" value="Female" />Female
</label>

[FindByIndex(0)]
public RadioButton<_> MaleGender { get; private set; }

[FindByIndex(1)]
public RadioButton<_> FemaleGender { get; private set; }

FindByColumnHeader

Specifies that a control should be found within the table column (<td>) that has the header (<th>) matching the specified term(s). Uses Title as the default term case.

Inherited from TermFindAttribute.

<table>
    <thead>
        <tr>
            <th>Name</th>
            <th>Price ($)</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Some Item</td>
            <td>50</td>
        </tr>
    </tbody>
</table>

public Table<ProductTableRow, _> Products { get; private set; }

public class ProductTableRow : TableRow<_>
{
    [FindByColumnHeader]
    public Text<_> Name { get; private set; }

    [FindByColumnHeader("Price ($)")]
    public Number<_> Price { get; private set; }
}

FindByColumnIndex

Specifies that a control should be found within the table column (<td>) that has the nth index.

Inherited from FindAttribute.

<table>
    <tbody>
        <tr>
            <td>Some Item</td>
            <td>50</td>
        </tr>
    </tbody>
</table>

public Table<ProductTableRow, _> Products { get; private set; }

public class ProductTableRow : TableRow<_>
{
    [FindByColumnIndex(0)]
    public Text<_> Name { get; private set; }

    [FindByColumnIndex(1)]
    public Number<_> Price { get; private set; }
}

Settings Attributes

FindSettings

Defines the settings to apply for the specified finding strategy of a control.

Example: Apply Within Assembly

For example, it is possible to replace the default strategy of control search with the custom one.

The following example sets CustomFindByLabelStrategy as a search strategy of FindByLabelAttribute for all controls in scope of assembly:

[assembly: FindSettings(TargetAttributeType = typeof(FindByLabelAttribute), Strategy = typeof(CustomFindByLabelStrategy))]

Example: Apply Within Class

It is possible to set settings for all child controls of page object or control.

An example sets ScopeSource.PageObject as scope source for all child controls of LoginControl<TOwner>: UserName and Password.

[FindSettings(TargetAnyType = true, TargetAttributeType = typeof(FindByLabelAttribute), ScopeSource = ScopeSource.PageObject)]
public class LoginControl<TOwner> : Control<TOwner>
    where TOwner : PageObject<TOwner>
{
    [FindByLabel]
    public TextInput<TOwner> UserName { get; private set; }

    [FindByLabel]
    public PasswordInput<TOwner> Password { get; private set; }
}

[FindSettings] properties:

  • TargetAnyType = true - says that this FindSettingsAttribute can apply to children of any type.
  • TargetAttributeType = typeof(FindByLabelAttribute) - specifies that it applies to attributes of FindByLabelAttribute type.

Properties

public int

Index { get; set; }

Gets or sets the index of the control. The default value is -1, meaning that the index is not used.

public Visibility

Visibility { get; set; }

Gets or sets the visibility. The default value is Visibility.Visible.

public ScopeSource

ScopeSource { get; set; }

Gets or sets the scope source. The default value is ScopeSource.Parent.

public string

OuterXPath { get; set; }

Gets or sets the outer XPath. The default value is null, meaning that the control is searchable as descendant (using ".//" XPath) in scope source.

public Type

Strategy { get; set; }

Gets or sets the strategy type for the control search. Strategy type should implement IComponentScopeLocateStrategy. The default value is null, meaning that the default strategy of the specific FindAttribute should be used.

TermFindSettings

Defines the term settings to apply for the specified finding strategy of a control.

Inherited from FindSettingsAttribute.

Example: Apply Within Assembly

For example, if all name attributes in the site are formatted lowercase without the separator (e.g. “firstname”), you can apply the following attribute in assembly/project containing page objects:

[assembly: TermFindSettings(TargetAttributeType = typeof(FindByNameAttribute), Case = TermCase.LowerMerged)]

Example: Apply Within Class

Or define it at the UIComponent level (page object or parent control). For example, for the specific page:

using Atata;

namespace SampleApp.UITests
{
    using _ = SamplePage;

    [TermFindSettings(TargetAnyType = true, TargetAttributeType = typeof(FindByLabelAttribute), Match = TermMatch.Contains, Case = TermCase.Sentence, Format = "{0}:")]
    public class SamplePage : Page<_>
    {
        [FindByLabel]
        public TextInput<_> FirstName { get; private set; }

        [FindByLabel]
        public TextInput<_> LastName { get; private set; }
    }
}

The above example will find FirstName control by the label containing text “First name:” and LastName by “Last name:”.

Properties

public TermCase

Case { get; set; }

Gets or sets the term case.

public TermMatch

Match { get; set; }

Gets or sets the match.

public string

Format { get; set; }

Gets or sets the format.

public bool

CutEnding { get; set; }

Gets or sets a value indicating whether the name should be cut considering the IgnoreNameEndings property value of [ControlDefinition] and [PageObjectDefinition] attributes. The default value is true.