Skip to content

Data entity document improvement #693

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 24, 2020
Merged

Data entity document improvement #693

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b39c15
Data entity document improvement
ajithkumar-maragathavel Apr 29, 2020
c0423df
Minor changes in the document
ajithkumar-maragathavel May 12, 2020
657aabb
Grammar and formatting
dobooth May 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 53 additions & 3 deletions docs/data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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>
Expand Down Expand Up @@ -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"?>
Expand Down Expand Up @@ -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"?>
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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.
Expand Down