Skip to content

#501 Update MFTF documentation and Best Practices #548

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 4 commits into from
Jan 22, 2020
Merged

#501 Update MFTF documentation and Best Practices #548

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3f7df8b
Update ActionGroups documentation
lbajsarowicz Jan 12, 2020
2d67ec9
Update Best Practices
lbajsarowicz Jan 12, 2020
46eabbf
Added raw tags
dobooth Jan 14, 2020
4d91e49
Merge branch 'develop' into bugfix/501-documentation
jilu1 Jan 22, 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
29 changes: 20 additions & 9 deletions docs/best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ Check out our best practices below to ensure you are getting the absolute most o
## Action group

1. [Action group] names should be sufficiently descriptive to inform a test writer of what the action group does and when it should be used.
Add additional explanation in comments if needed.
Add additional explanation in annotations if needed.
2. Provide default values for the arguments that apply to your most common case scenarios.

## `actionGroups` vs `extends`

Use an action group to wraps a set of actions to reuse them multiple times.
Use an action group to wrap a set of actions to reuse them multiple times.

Use an [extension] when a test or action group needs to be repeated with the exception of a few steps.

Expand Down Expand Up @@ -58,12 +58,20 @@ The following pattern is used when merging with `extends`:

Name files according to the following patterns to make searching in future more easy:

<!-- {% raw %} -->

#### Test file name

Format: {_Admin_ or _Storefront_}{Functionality}_Test.xml_, where Functionality briefly describes the testing functionality.

Example: _StorefrontCreateCustomerTest.xml_.

#### Action Group file name

Format: {_Admin_ or _Storefront_}{Action Group Summary}ActionGroup.xml`, where Action Group Summary describes with a few words what we can expect from it.

Example: _AdminCreateStoreActionGroup.xml_

#### Section file name

Format: {_Admin_ or _Storefront_}{UI Description}_Section.xml_, where UI Description briefly describes the testing UI.
Expand All @@ -74,6 +82,8 @@ Example: _AdminNavbarSection.xml_.

Format: {Type}_Data.xml_, where Type represents the entity type.

<!-- {% endraw %} -->

Example: _ProductData.xml_.

### Object names
Expand All @@ -85,18 +95,19 @@ Use the _Foo.camelCase_ naming convention, which is similar to _Classes_ and _cl
Use an upper case first letter for:

- File names. Example: _StorefrontCreateCustomerTest.xml_
- Test name attributes. Example: `<test name="TestAllTheThingsTest">`.
- Data entity names. Example: `<entity name="OutOfStockProduct">`.
- Page name. Example: `<page name="AdminLoginPage">`.
- Section name. Example: `<section name="AdminCategorySidebarActionSection">`.
- Action group name. Example: `<actionGroup name="LoginToAdminActionGroup">`.
- Test name attributes. Example: `<test name="TestAllTheThingsTest">`
- Data entity names. Example: `<entity name="OutOfStockProduct">`
- Page name. Example: `<page name="AdminLoginPage">`
- Section name. Example: `<section name="AdminCategorySidebarActionSection">`
- Action group name. Example: `<actionGroup name="LoginToAdminActionGroup">`

#### Lower case

Use a lower case first letter for:

- Data keys. Example: `<data key="firstName">`.
- Element names. Examples: `<element name="confirmDeleteButton"/>`.
- Data keys. Example: `<data key="firstName">`
- Element names. Examples: `<element name="confirmDeleteButton"/>`
- Step keys. For example: `<click selector="..." stepKey="clickLogin"/>`

## Page object

Expand Down
111 changes: 61 additions & 50 deletions docs/test/action-groups.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,10 @@ The following diagram shows the structure of an MFTF action group:

The following conventions apply to MFTF action groups:

- All action groups are declared in XML files and stored in the `<module>/ActionGroup/` directory.
- Every file name ends with `ActionGroup`, such as `LoginToAdminActionGroup`.
- All action groups are declared in XML files and stored in the `<module>/Test/Mftf/ActionGroup/` directory.
- Every file name ends with `ActionGroup` suffix. For exampe `LoginAsAdminActionGroup.xml`.
- Action group name should be the same as file name without extension.
- Single file should contain only one `<actionGroup>` node

The XML format for the `actionGroups` declaration is:

Expand All @@ -34,32 +36,31 @@ The XML format for the `actionGroups` declaration is:

These examples build a declaration for a group of actions that grant authorization to the Admin area, and use the declaration in a test.

The _Backend/ActionGroup/LoginToAdminActionGroup.xml_ `<actionGroup>` relates to the functionality of the _Backend_ module.
In [test][], the name and identifier of the `<actionGroup>` is used as a reference in the `ref` parameter, such as `ref="LoginToAdminActionGroup"`.
The _Magento/Backend/Test/Mftf/ActionGroup/LoginAsAdminActionGroup.xml_ `<actionGroup>` relates to the functionality of the _Magento_Backend_ module.

In [test][], the name and identifier of the `<actionGroup>` is used as a reference in the `ref` parameter, such as `ref="LoginAsAdminActionGroup"`.

### Create an action group declaration

To create the `<actionGroup>` declaration:

1. Begin with a _Backend/ActionGroup/LoginToAdminActionGroup.xml_ template for the `<actionGroup>`:
1. Begin with a template for the `<actionGroup>`:

```xml
<?xml version="1.0" encoding="UTF-8"?>

<actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:mftf:Test/etc/actionGroupSchema.xsd">
<actionGroup name="LoginToAdminActionGroup">
...
<actionGroup name="{Action Group Name}">

</actionGroup>
</actionGroups>
```

<!-- {% raw %} -->

1. Add actions to the `actionGroup` arguments:

```xml
<actionGroup name="LoginToAdminActionGroup">
<actionGroup name="LoginAsAdminActionGroup">
<fillField stepKey="fillUsername" selector="#username" userInput="{{adminUser.username}}" />
<fillField stepKey="fillPassword" selector="#password" userInput="{{adminUser.password}}" />
<click stepKey="click" selector="#login" />
Expand All @@ -81,14 +82,20 @@ To create the `<actionGroup>` declaration:

<actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:mftf:Test/etc/actionGroupSchema.xsd">
<actionGroup name="LoginToAdminActionGroup">
<arguments>
<argument name="adminUser" defaultValue="_defaultAdmin"/>
</arguments>
<fillField stepKey="fillUsername" selector="#username" userInput="{{adminUser.username}}" />
<fillField stepKey="fillPassword" selector="#password" userInput="{{adminUser.password}}" />
<click stepKey="click" selector="#login" />
</actionGroup>
<actionGroup name="LoginAsAdmin">
<annotations>
<description>Login to Backend Admin using provided User Data. PLEASE NOTE: This Action Group does NOT validate that you are Logged In.</description>
</annotations>
<arguments>
<argument name="adminUser" type="entity" defaultValue="DefaultAdminUser"/>
</arguments>

<amOnPage url="{{AdminLoginPage.url}}" stepKey="navigateToAdmin"/>
<fillField selector="{{AdminLoginFormSection.username}}" userInput="{{adminUser.username}}" stepKey="fillUsername"/>
<fillField selector="{{AdminLoginFormSection.password}}" userInput="{{adminUser.password}}" stepKey="fillPassword"/>
<click selector="{{AdminLoginFormSection.signIn}}" stepKey="clickLogin"/>
<closeAdminNotification stepKey="closeAdminNotification"/>
</actionGroup>
</actionGroups>
```

Expand All @@ -97,23 +104,23 @@ To create the `<actionGroup>` declaration:
In this test example, we want to add the following set of actions:

```xml
<fillField stepKey="fillUsername" selector="#username" userInput="{{CustomAdminUser.username}}" />
<fillField stepKey="fillPassword" selector="#password" userInput="{{CustomAdminUser.password}}" />
<click stepKey="click" selector="#login" />
<fillField selector="{{AdminLoginFormSection.username}}" userInput="{{adminUser.username}}" stepKey="fillUsername"/>
<fillField selector="{{AdminLoginFormSection.password}}" userInput="{{adminUser.password}}" stepKey="fillPassword"/>
<click selector="{{AdminLoginFormSection.signIn}}" stepKey="clickLogin"/>
```

Instead of adding this set of actions, use the _LoginToAdminActionGroup_ `<actionGroup>` declaration in tests:
Instead of adding this set of actions, use the _LoginAsAdminActionGroup_ `<actionGroup>` declaration in tests:

1. Reference the `LoginToAdminActionGroup` action group:
1. Reference the `LoginAsAdminActionGroup` action group:

```xml
<actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup"/>
<actionGroup stepKey="loginToAdminPanel" ref="LoginAsAdminActionGroup"/>
```

1. Update the argument name/value pair to `adminUser` and `CustomAdminUser`:

```xml
<actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup">
<actionGroup stepKey="loginToAdminPanel" ref="LoginAsAdminActionGroup">
<argument name="adminUser" value="CustomAdminUser"/>
</actionGroup>
```
Expand Down Expand Up @@ -196,30 +203,34 @@ Starting with an action group such as:
```

It can be reworked into more manageable pieces, as below. These smaller steps are easier to read, update, and reuse.

```xml
<actionGroup name="GoToCategoryGridAndAddNewCategory">
<seeInCurrentUrl url="{{AdminCategoryPage.url}}" stepKey="seeOnCategoryPage"/>
<click selector="{{AdminCategorySidebarActionSection.AddSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
<see selector="{{AdminHeaderSection.pageTitle}}" userInput="New Category" stepKey="seeCategoryPageTitle"/>
</actionGroup>

<actionGroup name="FillInBasicCategoryFields">
<arguments>
<argument name="categoryEntity" defaultValue="_defaultCategory"/>
</arguments>
<fillField selector="{{AdminCategoryBasicFieldSection.CategoryNameInput}}" userInput="{{categoryEntity.name}}" stepKey="enterCategoryName"/>
<click selector="{{AdminCategorySEOSection.SectionHeader}}" stepKey="openSEO"/>
<fillField selector="{{AdminCategorySEOSection.UrlKeyInput}}" userInput="{{categoryEntity.name_lwr}}" stepKey="enterURLKey"/>
</actionGroup>

<actionGroup name="SaveAndVerifyCategoryCreation">
<click selector="{{AdminCategoryMainActionsSection.SaveButton}}" stepKey="saveCategory"/>
<seeElement selector="{{AdminCategoryMessagesSection.SuccessMessage}}" stepKey="assertSuccess"/>
<seeInTitle userInput="{{categoryEntity.name}}" stepKey="seeNewCategoryPageTitle"/>
<seeElement selector="{{AdminCategorySidebarTreeSection.categoryInTree(categoryEntity.name)}}" stepKey="seeCategoryInTree"/>
</actionGroup>
```
* GoToCategoryGridAndAddNewCategory
```xml
<actionGroup name="GoToCategoryGridAndAddNewCategory">
<seeInCurrentUrl url="{{AdminCategoryPage.url}}" stepKey="seeOnCategoryPage"/>
<click selector="{{AdminCategorySidebarActionSection.AddSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
<see selector="{{AdminHeaderSection.pageTitle}}" userInput="New Category" stepKey="seeCategoryPageTitle"/>
</actionGroup>
```
* FillInBasicCategoryFields
```xml
<actionGroup name="FillInBasicCategoryFields">
<arguments>
<argument name="categoryEntity" defaultValue="_defaultCategory"/>
</arguments>
<fillField selector="{{AdminCategoryBasicFieldSection.CategoryNameInput}}" userInput="{{categoryEntity.name}}" stepKey="enterCategoryName"/>
<click selector="{{AdminCategorySEOSection.SectionHeader}}" stepKey="openSEO"/>
<fillField selector="{{AdminCategorySEOSection.UrlKeyInput}}" userInput="{{categoryEntity.name_lwr}}" stepKey="enterURLKey"/>
</actionGroup>
```
* SaveAndVerifyCategoryCreation
```xml
<actionGroup name="SaveAndVerifyCategoryCreation">
<click selector="{{AdminCategoryMainActionsSection.SaveButton}}" stepKey="saveCategory"/>
<seeElement selector="{{AdminCategoryMessagesSection.SuccessMessage}}" stepKey="assertSuccess"/>
<seeInTitle userInput="{{categoryEntity.name}}" stepKey="seeNewCategoryPageTitle"/>
<seeElement selector="{{AdminCategorySidebarTreeSection.categoryInTree(categoryEntity.name)}}" stepKey="seeCategoryInTree"/>
</actionGroup>
```

<!-- {% endraw %} -->

Expand Down Expand Up @@ -261,4 +272,4 @@ Attribute|Type|Use|Description
[actions]: ./actions.md
[test]: ../test.md
[`argument`]: #argument-tag
[created]: ../data.md#persist-data
[created]: ../data.md#persist-data