Merge remote-tracking branch 'origin/develop' into MQE-1919

Author: jilu1

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.
 
@@ -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.
@@ -74,6 +82,8 @@ Example: _AdminNavbarSection.xml_.
 
 Format: {Type}_Data.xml_, where Type represents the entity type.
 
+<!-- {% endraw %} -->
+
 Example: _ProductData.xml_.
 
 ### Object names
@@ -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
 

docs/commands/mftf.md

@@ -463,18 +463,39 @@ The example parameters are taken from the `etc/config/.env.example` file.
 
 ### `static-checks`
 
-Runs all MFTF static-checks on the test codebase that MFTF is currently attached to.
+Runs all or specific MFTF static-checks on the test codebase that MFTF is currently attached to. 
+If no script name argument is specified, all existing static check scripts will run.
 
-#### Existing static checks
+#### Usage
 
-* Test Dependency: Checks that test dependencies do not violate Magento module's composer dependencies.
+```bash
+vendor/bin/mftf static-checks [<names>]...
+```
 
-#### Usage
+#### Examples
+
+To check what existing static check scripts are available
+
+```bash
+vendor/bin/mftf static-checks --help
+```
+
+To run all existing static check scripts 
 
 ```bash
 vendor/bin/mftf static-checks
 ```
 
+To run specific static check scripts
+
+```bash
+vendor/bin/mftf static-checks testDependencies
+```
+
+#### Existing static checks
+
+* Test Dependency: Checks that test dependencies do not violate Magento module's composer dependencies.
+
 ### `upgrade:tests`
 
 Applies all the MFTF major version upgrade scripts to test components in the given path (`test.xml`, `data.xml`, etc).

docs/extending.md

@@ -26,7 +26,7 @@ __Use case__: Create two similar tests with different `url` (`"{{AdminCategoryPa
 > Test with "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="AdminCategoryTest">
             <annotations>
                 ...
@@ -47,7 +47,7 @@ __Use case__: Create two similar tests with different `url` (`"{{AdminCategoryPa
 > Test without "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="AdminCategoryTest">
             <annotations>
                 ...
@@ -77,7 +77,7 @@ __Use case__: Create two similar tests where the second test contains two additi
 > Tests with "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="LogInAsAdminTest">
         <amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
         <fillField selector="{{AdminLoginFormSection.username}}" userInput="admin" stepKey="fillUsername"/>
@@ -95,7 +95,7 @@ __Use case__: Create two similar tests where the second test contains two additi
 > Tests without "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="LogInAsAdminTest">
         <amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
         <fillField selector="{{AdminLoginFormSection.username}}" userInput="admin" stepKey="fillUsername"/>
@@ -125,7 +125,7 @@ __Use case__: Create two similar tests where the second one contains two additio
 > Tests with "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="LogInAsAdminTest">
         <before>
             <amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
@@ -147,7 +147,7 @@ __Use case__: Create two similar tests where the second one contains two additio
 > Tests without "extends":
 
 ```xml
-<tests >
+<tests>
     <test name="LogInAsAdminTest">
         <before>
             <amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
@@ -295,7 +295,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
 > Entities with "extends":
 
 ```xml
-<entities >
+<entities>
     <entity name="DivPanel">
         <data key="divColor">Red</data>
         <data key="divSize">80px</data>
@@ -310,7 +310,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
 > Entities without "extends":
 
 ```xml
-<entities >
+<entities>
     <entity name="DivPanel">
         <data key="divColor">Red</data>
         <data key="divSize">80px</data>
@@ -331,7 +331,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
 > Entities with "extends":
 
 ```xml
-<entities >
+<entities>
     <entity name="DivPanel">
         <data key="divColor">Red</data>
         <data key="divSize">80px</data>
@@ -347,7 +347,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
 > Entities without "extends":
 
 ```xml
-<entities >
+<entities>
     <entity name="DivPanel">
         <data key="divColor">Red</data>
         <data key="divSize">80px</data>

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
+[created]: ../data.md#persist-data