Control Search

Atata Framework contains the list of attributes for the finding of the controls.

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).

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.

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.

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; }

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; }
}

FindSettings

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

Examples

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

[assembly: FindSettings(FindTermBy.Label, Strategy = typeof(CustomFindByLabelStrategy))]

Or set another scope source for a custom control:

[FindSettings(FindTermBy.Label, ScopeSource = ScopeSource.PageObject)]
public class LoginControl<TOwner> : Control<TOwner>
    where TOwner : PageObject<TOwner>
{
    [FindByLabel]
    public TextInput<_> UserName { get; private set; }

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

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.

Examples

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

[assembly: TermFindSettings(FindTermBy.Name, Case = TermCase.LowerMerged)]

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

using Atata;
using _ = SampleApp.SamplePage;

namespace SampleApp
{
    [TermFindSettings(FindTermBy.Label, Match = TermMatch.Contains, Case = TermCase.Sentence, Format = "{0}:")]
    public class SamplePage : Page<_>
    {
        public TextInput<_> FirstName { get; private set; }

        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.

ControlFinding

Specifies the default finding strategy of a control. Can be applied to the control class and assembly.

Examples

For example, it is possible to set the default finding of the Input control as by name, and for inputs whose parent is TableRow by column header:

[assembly: ControlFinding(FindTermBy.Name, ControlType = typeof(Input<,>))]
[assembly: ControlFinding(FindTermBy.ColumnHeader, ControlType = typeof(Input<,>), ParentComponentType = typeof(TableRow<>))]

Or set the finding by the label for a custom control:

[ControlFinding(FindTermBy.Label)]
public class CustomControl<TOwner> : Control<TOwner>
    where TOwner : PageObject<TOwner>
{
}

Properties

public Type

ControlType { get; set; }

Gets or sets the type of the control (e.g.: typeof(Link<>), typeof(EditableField<,>)).

public Type

ParentComponentType { get; set; }

Gets or sets the type of the parent component.