Locator functions

Define Locator::functions in elements

Codeception has a set of very useful Locator functions that may be used by elements inside a section.

Declare an element with a locatorFunction:

Copy
<element name="simpleLocator" type="button" locatorFunction="Locator::contains('label', 'Name')"/>
Copied to your clipboard
<element name="simpleLocator" type="button" locatorFunction="Locator::contains('label', 'Name')"/>

When using the locatorFunction, omit Locator:: for code simplicity:

Copy
<element name="simpleLocatorShorthand" type="button" locatorFunction="contains('label', 'Name')"/>
Copied to your clipboard
<element name="simpleLocatorShorthand" type="button" locatorFunction="contains('label', 'Name')"/>

An element's locatorFunction can also be parameterized the same way as parameterized selectors:

Copy
<element name="simpleLocatorTwoParam" type="button" locatorFunction="contains({{arg1}}, {{arg2}})" parameterized="true"/>
Copied to your clipboard
<element name="simpleLocatorTwoParam" type="button" locatorFunction="contains({{arg1}}, {{arg2}})" parameterized="true"/>

An element cannot, however, have both a selector and a locatorFunction.

Call Elements that use locatorFunction

Given the above element definitions, you call the elements in a test just like any other element. No special reference is required, as you are still just referring to an element inside a section:

Copy
<test name="LocatorFunctionTest">
   <click selector="{{LocatorFunctionSection.simpleLocator}}" stepKey="SimpleLocator"/>
   <click selector="{{LocatorFunctionSection.simpleLocatorTwoParam('string1', 'string2')}}" stepKey="TwoParamLiteral"/>
</test>
Copied to your clipboard
<test name="LocatorFunctionTest">
   <click selector="{{LocatorFunctionSection.simpleLocator}}" stepKey="SimpleLocator"/>
   <click selector="{{LocatorFunctionSection.simpleLocatorTwoParam('string1', 'string2')}}" stepKey="TwoParamLiteral"/>
</test>

Last updated 9/11/2023

Was this helpful?

Yes

No