Merge pull request #2 from magento-pangolin/MQE-336

MQE-336: [Generator] Add support for Codeception "Locator" selectors

Author: dshevtsov

_data/toc/magento-functional-testing-framework-guide.yml

@@ -27,6 +27,9 @@ pages:
       - label: Parameterized selectors
         url: magento-functional-testing-framework/section/parameterized-selectors.html
 
+      - label: Locator Functions
+        url: magento-functional-testing-framework/section/locator-functions.html
+
   - label: CLI Commands
     versions: ["2.3"]
     children:

guides/v2.3/magento-functional-testing-framework/section.md

@@ -106,7 +106,8 @@ Attributes|Type|Use|Description
 ---|---|---|---
 name|string|required|Element name
 type|string|required|The type of the element. Possible values: `text`, `textarea`, `input`, `button`, `checkbox`, `radio`, `checkboxset`, `radioset`, `date`, `file`, `select`, `multiselect`, `wysiwyg`, `iframe`.
-selector|string|required|[XPath] or [CSS] selector of the element.
+selector|string|optional|[XPath] or [CSS] selector of the element.
+locatorFunction|string|optional|[Locator Function] declaration to be used in lieu of a selector.
 timeout|string|optional|Default: `-`. Optional timeout value in seconds to wait for the operation on the element.
 parameterized|boolean|optional|Include and set to `true` if the `selector` for this element has parameters that need to be replaced for proper use.
 remove|boolean|optional|Default: `false`. Set to `true` to remove this element during parsing.
@@ -119,7 +120,8 @@ remove|boolean|optional|Default: `false`. Set to `true` to remove this element d
 [page]: page.html
 [CSS]: https://www.w3schools.com/cssref/css_selectors.asp
 [XPath]: https://www.w3schools.com/xml/xpath_nodes.asp
+[Locator Function]: section/locator-functions.html
 [cest]: cest.html
 [test]: cest.html#test
 [createData]: cest/actions.html#createdata
-[before]: cest.html#before
+[before]: cest.html#before

guides/v2.3/magento-functional-testing-framework/section/locator-functions.md

@@ -0,0 +1,53 @@
+---
+layout: default
+group: mftf
+title: Use Codeception's Locator Functions in the Magento Functional Testing Framework
+version: 2.3
+github_link: magento-functional-testing-framework/section/structure/locator-functions.md
+---
+
+{%raw%}
+
+## Defining Locator::functions in Elements
+
+Codeception has a set of very useful [Locator Functions] that may be used by elements inside a [section].
+
+Declaration of an element with a `locatorFunction` can be done as follows:
+```xml
+<element name="simpleLocator" type="button" locatorFunction="Locator::contains('label', 'Name')"/>
+```
+When using the `locatorFunction`, you can also omit `Locator::` for code simplicity.
+```xml
+<element name="simpleLocatorShorthand" type="button" locatorFunction="contains('label', 'Name')"/>
+```
+An element's `locatorFunction` can also be parameterized the same way as [parameterized-selectors].
+```xml
+<element name="simpleLocatorTwoParam" type="button" locatorFunction="contains({{arg1}}, {{arg2}})" parameterized="true"/>
+```
+Lastly, an element **cannot** have both a `selector` and a `locatorFunction`.
+
+## Calling Elements that use locatorFunction
+
+Given the above element definitions, we 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`. 
+
+```xml
+<test name="LocatorFuctionTest">
+    <click mergeKey="SimpleLocator" selector="{{LocatorFunctionSection.simpleLocator}}"/>
+    <click mergeKey="TwoParamLiteral" selector="{{LocatorFunctionSection.simpleLocatorTwoParam('string1', 'string2')}}"/>    
+</test>
+```
+
+{%endraw%}
+
+
+<!-- LINK DEFINITIONS -->
+
+<!-- Internal -->
+
+[section]: ../section.html
+[parameterized-selectors]: parameterized-selectors.html
+
+<!-- External -->
+[Locator Functions]: http://codeception.com/docs/reference/Locator