From 3f7df8b25609c811c2823895d38d63ee051a2950 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Bajsarowicz?= <lukasz.bajsarowicz@gmail.com>
Date: Sun, 12 Jan 2020 01:22:33 +0100
Subject: [PATCH 1/3] Update ActionGroups documentation

---
 docs/test/action-groups.md | 111 ++++++++++++++++++++-----------------
 1 file changed, 61 insertions(+), 50 deletions(-)

diff --git a/docs/test/action-groups.md b/docs/test/action-groups.md
index 0743481f6..5fdfbb522 100644
--- a/docs/test/action-groups.md
+++ b/docs/test/action-groups.md
@@ -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:
 
@@ -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" />
@@ -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>
     ```
 
@@ -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>
     ```
@@ -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 %} -->
 
@@ -261,4 +272,4 @@ Attribute|Type|Use|Description
 [actions]: ./actions.md
 [test]: ../test.md
 [`argument`]: #argument-tag
-[created]: ../data.md#persist-data
\ No newline at end of file
+[created]: ../data.md#persist-data

From 2d67ec9961abf24e720e34a4a9e6ff5d612761fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=81ukasz=20Bajsarowicz?= <lukasz.bajsarowicz@gmail.com>
Date: Sun, 12 Jan 2020 01:33:48 +0100
Subject: [PATCH 2/3] Update Best Practices

---
 docs/best-practices.md | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/docs/best-practices.md b/docs/best-practices.md
index a3e5f2629..95677e78a 100644
--- a/docs/best-practices.md
+++ b/docs/best-practices.md
@@ -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.
 
@@ -64,6 +64,12 @@ Format: {_Admin_ or _Storefront_}{Functionality}_Test.xml_, where 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.
@@ -97,6 +103,7 @@ Use a lower case first letter for:
 
 -  Data keys. Example: `<data key="firstName">`.
 -  Element names. Examples: `<element name="confirmDeleteButton"/>`.
+-  Step keys. For example: `<click selector="..." stepKey="clickLogin"/>`
 
 ## Page object
 

From 46eabbf80dc84fe37981ba8487ac53a6bfae76ec Mon Sep 17 00:00:00 2001
From: Donald Booth <dobooth@adobe.com>
Date: Tue, 14 Jan 2020 10:21:46 -0600
Subject: [PATCH 3/3] Added raw tags

---
 docs/best-practices.md | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/docs/best-practices.md b/docs/best-practices.md
index 95677e78a..0b95b1c41 100644
--- a/docs/best-practices.md
+++ b/docs/best-practices.md
@@ -58,6 +58,8 @@ 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.
@@ -80,6 +82,8 @@ Example: _AdminNavbarSection.xml_.
 
 Format: {Type}_Data.xml_, where Type represents the entity type.
 
+<!-- {% endraw %} -->
+
 Example: _ProductData.xml_.
 
 ### Object names
@@ -91,18 +95,18 @@ 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