diff --git a/docs/best-practices.md b/docs/best-practices.md index a3e5f2629..0b95b1c41 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. @@ -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: + + #### 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. + + 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: ``. -- Data entity names. Example: ``. -- Page name. Example: ``. -- Section name. Example: `
`. -- Action group name. Example: ``. +- Test name attributes. Example: `` +- Data entity names. Example: `` +- Page name. Example: `` +- Section name. Example: `
` +- Action group name. Example: `` #### Lower case Use a lower case first letter for: -- Data keys. Example: ``. -- Element names. Examples: ``. +- Data keys. Example: `` +- Element names. Examples: `` +- Step keys. For example: `` ## Page object 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 `/ActionGroup/` directory. -- Every file name ends with `ActionGroup`, such as `LoginToAdminActionGroup`. +- All action groups are declared in XML files and stored in the `/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 `` 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_ `` relates to the functionality of the _Backend_ module. -In [test][], the name and identifier of the `` is used as a reference in the `ref` parameter, such as `ref="LoginToAdminActionGroup"`. +The _Magento/Backend/Test/Mftf/ActionGroup/LoginAsAdminActionGroup.xml_ `` relates to the functionality of the _Magento_Backend_ module. + +In [test][], the name and identifier of the `` is used as a reference in the `ref` parameter, such as `ref="LoginAsAdminActionGroup"`. ### Create an action group declaration To create the `` declaration: -1. Begin with a _Backend/ActionGroup/LoginToAdminActionGroup.xml_ template for the ``: +1. Begin with a template for the ``: ```xml - - ... + + ``` - - 1. Add actions to the `actionGroup` arguments: ```xml - + @@ -81,14 +82,20 @@ To create the `` declaration: - - - - - - - - + + + Login to Backend Admin using provided User Data. PLEASE NOTE: This Action Group does NOT validate that you are Logged In. + + + + + + + + + + + ``` @@ -97,23 +104,23 @@ To create the `` declaration: In this test example, we want to add the following set of actions: ```xml - - - + + + ``` -Instead of adding this set of actions, use the _LoginToAdminActionGroup_ `` declaration in tests: +Instead of adding this set of actions, use the _LoginAsAdminActionGroup_ `` declaration in tests: -1. Reference the `LoginToAdminActionGroup` action group: +1. Reference the `LoginAsAdminActionGroup` action group: ```xml - + ``` 1. Update the argument name/value pair to `adminUser` and `CustomAdminUser`: ```xml - + ``` @@ -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 - - - - - - - - - - - - - - - - - - - - - -``` +* GoToCategoryGridAndAddNewCategory + ```xml + + + + + + ``` +* FillInBasicCategoryFields + ```xml + + + + + + + + + ``` +* SaveAndVerifyCategoryCreation + ```xml + + + + + + + ``` @@ -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