Merge pull request #693 from ajithkumar-maragathavel/data-entity-improvements

Data entity document improvement

Author: dobooth

docs/data.md

@@ -7,6 +7,8 @@ The following diagram shows the XML structure of an MFTF data object:
 
 <!-- {% raw %} -->
 
+The MFTF `<data>` entities are stored in `<module_dir>/Test/Mftf/Data/`.
+
 ## Supply data to test by reference to a data entity
 
 Test steps requiring `<data>` input in an action, like filling a field with a string, may reference an attribute from a data entity:
@@ -20,6 +22,20 @@ In this example:
 *  `SimpleSubCategory` is an entity name.
 *  `name` is a `<data>` key of the entity. The corresponding value will be assigned to `userInput` as a result.
 
+The following is an example of the usage of `<data>` entity in the `Magento/Customer/Test/Mftf/Test/AdminCustomersAllCustomersNavigateMenuTest.xml` test:
+
+```xml
+<actionGroup ref="AdminNavigateMenuActionGroup" stepKey="navigateToAllCustomerPage">
+    <argument name="menuUiId" value="{{AdminMenuCustomers.dataUiId}}"/>
+    <argument name="submenuUiId" value="{{AdminMenuCustomersAllCustomers.dataUiId}}"/>
+</actionGroup>
+```
+
+In the above example:
+
+*  `AdminMenuCustomers` is an entity name.
+*  `dataUiId` is a `<data>` key of the entity.
+
 ### Environmental data
 
 ```xml
@@ -32,6 +48,12 @@ In this example:
 *  `MAGENTO_ADMIN_USERNAME` is a name of an environment variable.
    The corresponding value will be assigned to `userInput` as a result.
 
+The following is an example of the usage of `_ENV` in the `Magento/Braintree/Test/Mftf/ActionGroup/AdminDeleteRoleActionGroup.xml` action group:
+
+```xml
+<fillField stepKey="TypeCurrentPassword" selector="{{AdminDeleteRoleSection.current_pass}}" userInput="{{_ENV.MAGENTO_ADMIN_PASSWORD}}"/>
+```
+
 ### Sensitive data
 
 ```xml
@@ -47,6 +69,14 @@ In this example:
 
 Learn more in [Credentials][].
 
+The following is an example of the usage of `_CREDS` in the `Magento/Braintree/Test/Mftf/Data/BraintreeData.xml` data entity:
+
+```xml
+<entity name="MerchantId" type="merchant_id">
+    <data key="value">{{_CREDS.magento/braintree_enabled_fraud_merchant_id}}</data>
+</entity>
+```
+
 ## Persist a data entity as a prerequisite of a test {#persist-data}
 
 A test can specify an entity to be persisted (created in the database) so that the test actions could operate on the existing known data.
@@ -63,6 +93,14 @@ In this example:
 *  `email` is a data key of the entity.
   The corresponding value will be assigned to `userInput` as a result.
 
+The following is an example of the usage of the persistant data in `Magento/Customer/Test/Mftf/Test/AdminCreateCustomerWithCountryUSATest.xml` test:
+
+```xml
+<actionGroup ref="AdminFilterCustomerByEmail" stepKey="filterTheCustomerByEmail">
+    <argument name="email" value="$$createCustomer.email$$"/>
+</actionGroup>
+```
+
 <div class="bs-callout bs-callout-info">
 As of MFTF 2.3.6, you no longer need to differentiate between scopes (a test, a hook, or a suite) for persisted data when referencing it in tests.
 </div>
@@ -107,7 +145,7 @@ userInput="We'll email you an order confirmation with details and tracking info.
 
 ## Format
 
-The format of `<data>` is:
+The format of the `<data>` entity is:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -135,7 +173,7 @@ The following conventions apply to MFTF `<data>`:
 
 ## Example
 
-Example (`.../Catalog/Data/CategoryData.xml` file):
+Example (`Magento/Catalog/Test/Mftf/Data/CategoryData.xml` file):
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -205,7 +243,7 @@ You can also call data from the xml definition of a `data` tag directly:
 
 Attributes|Type|Use|Description
 ---|---|---|---
-`name`|string|optional|Name of the `<entity>`.
+`name`|string|optional|Name of the `<entity>`. Use camel case for entity names.
 `type`|string|optional|Node containing the exact name of `<entity>` type. Used later to find specific Persistence Layer Model class. `type` in `<data>` can be whatever the user wants; There are no constraints. It is important when persisting data, depending on the `type` given, as it will try to match a metadata definition with the operation being done. Example: A `myCustomer` entity with `type="customer"`, calling `<createData entity="myCustomer"/>`, will try to find a metadata entry with the following attributes: `<operation dataType="customer" type="create">`.
 `deprecated`|string|optional|Used to warn about the future deprecation of the data entity. String will appear in Allure reports and console output at runtime.
 
@@ -220,6 +258,12 @@ Attributes|Type|Use|Description
 `key`|string|optional|Key attribute of data/value pair.
 `unique`|enum: `"prefix"`, `"suffix"`|optional|Add suite or test wide unique sequence as "prefix" or "suffix" to the data value if specified.
 
+Example:
+
+```xml
+<data key="name" unique="suffix">simpleCategory</data>
+```
+
 ### var {#var-tag}
 
 `<var>` is an element that can be used to grab a key value from another entity. For example, when creating a customer with the `<createData>` action, the server responds with the auto-incremented ID of that customer. Use `<var>` to access that ID and use it in another data entity.
@@ -231,6 +275,12 @@ Attributes|Type|Use|Description
 `entityKey`|string|optional|Key attribute of the referenced entity from which to get a value.
 `unique`|--|--|*This attribute hasn't been implemented yet.*
 
+Example:
+
+```xml
+<var key="parent_id" entityType="category" entityKey="id" />
+```
+
 ### requiredEntity {#requiredentity-tag}
 
 `<requiredEntity>` is an element that specifies the parent/child relationship between complex types.