|
| 1 | +# Best practices |
| 2 | + |
| 3 | +Check out our best practices below to ensure you are getting the absolute most out of the Magento Functional Testing Framework. |
| 4 | + |
| 5 | +## Action group |
| 6 | + |
| 7 | +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. |
| 8 | + Add additional explanation in comments if needed. |
| 9 | +2. Provide default values for the arguments that apply to your most common case scenarios. |
| 10 | + |
| 11 | +## `actionGroups` vs `extends` |
| 12 | + |
| 13 | +Use an action group to wraps a set of actions to reuse them multiple times. |
| 14 | + |
| 15 | +Use an [extension] when a test or action group needs to be repeated with the exception of a few steps. |
| 16 | + |
| 17 | +### When to use `extends` |
| 18 | + |
| 19 | +Use `extends` in your new test or action group when at least one of the following conditions is applicable to your case: |
| 20 | + |
| 21 | +1. You want to keep the original test without any modifications. |
| 22 | +2. You want to create a new test that follows the same path as the original test. |
| 23 | +3. You want a new action group that behaves similarly to the existing action group, but you do not want to change the functionality of the original action group. |
| 24 | + |
| 25 | +### When to avoid `extends` |
| 26 | + |
| 27 | +Do not use `extends` in the following conditions: |
| 28 | + |
| 29 | +1. You want to change the functionality of the test or action group and do not need to run the original version. |
| 30 | +2. You plan to merge the base test or action group. |
| 31 | + |
| 32 | +The following pattern is used when merging with `extends`: |
| 33 | + |
| 34 | +1. The original test is merged. |
| 35 | +2. The extended test is created from the merged original test. |
| 36 | +3. The extended test is merged. |
| 37 | + |
| 38 | +## Annotation |
| 39 | + |
| 40 | +1. Use [annotations] in a test. |
| 41 | +2. Update your annotations correspondingly when updating tests. |
| 42 | + |
| 43 | +## Data entity |
| 44 | + |
| 45 | +1. Keep your testing instance clean. |
| 46 | + Remove data after the test if the test required creating any data. |
| 47 | + Use a corresponding [`<deleteData>`] test step in your [`<after>`] block when using a [`<createData>`] action in a [`<before>`] block. |
| 48 | +2. Make specific data entries under test to be unique. |
| 49 | + Enable data uniqueness where data values are required to be unique in a database by test design. |
| 50 | + Use `unique=”suffix”` or `unique=”prefix”` to append or prepend a unique value to the [entity] attribute. |
| 51 | + This ensures that tests using the entity can be repeated. |
| 52 | +3. Do not modify existing data entity fields or merge additional data fields without complete understanding and verifying the usage of existing data in tests. |
| 53 | + Create a new data entity for your test if you are not sure. |
| 54 | + |
| 55 | +## Naming conventions |
| 56 | + |
| 57 | +### File names |
| 58 | + |
| 59 | +Name files according to the following patterns to make searching in future more easy: |
| 60 | + |
| 61 | +#### Test file name |
| 62 | + |
| 63 | +Format: {_Admin_ or _Storefront_}{Functionality}_Test.xml_, where Functionality briefly describes the testing functionality. |
| 64 | + |
| 65 | +Example: _StorefrontCreateCustomerTest.xml_. |
| 66 | + |
| 67 | +#### Section file name |
| 68 | + |
| 69 | +Format: {_Admin_ or _Storefront_}{UI Description}_Section.xml_, where UI Description briefly describes the testing UI. |
| 70 | + |
| 71 | +Example: _AdminNavbarSection.xml_. |
| 72 | + |
| 73 | +#### Data file name |
| 74 | + |
| 75 | +Format: {Type}_Data.xml_, where Type represents the entity type. |
| 76 | + |
| 77 | +Example: _ProductData.xml_. |
| 78 | + |
| 79 | +### Object names |
| 80 | + |
| 81 | +Use the _Foo.camelCase_ naming convention, which is similar to _Classes_ and _classProperties_ in PHP. |
| 82 | + |
| 83 | +#### Upper case |
| 84 | + |
| 85 | +Use an upper case first letter for: |
| 86 | + |
| 87 | +- File names. Example: _StorefrontCreateCustomerTest.xml_ |
| 88 | +- Test name attributes. Example: `<test name="TestAllTheThingsTest">`. |
| 89 | +- Data entity names. Example: `<entity name="OutOfStockProduct">`. |
| 90 | +- Page name. Example: `<page name="AdminLoginPage">`. |
| 91 | +- Section name. Example: `<section name="AdminCategorySidebarActionSection">`. |
| 92 | +- Action group name. Example: `<actionGroup name="LoginToAdminActionGroup">`. |
| 93 | + |
| 94 | +#### Lower case |
| 95 | + |
| 96 | +Use a lower case first letter for: |
| 97 | + |
| 98 | +- Data keys. Example: `<data key="firstName">`. |
| 99 | +- Element names. Examples: `<element name="confirmDeleteButton"/>`. |
| 100 | + |
| 101 | +## Page object |
| 102 | + |
| 103 | +Use [parameterized selectors] for constructing a selector when test specific or runtime generated information is needed. |
| 104 | +Do not use them for static elements. |
| 105 | + |
| 106 | +<span class="color:red"> |
| 107 | +BAD: |
| 108 | +</span> |
| 109 | + |
| 110 | +<!-- {% raw %} --> |
| 111 | + |
| 112 | +``` xml |
| 113 | +<element name="relatedProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='{{productType}}']" parameterized="true"/> |
| 114 | +``` |
| 115 | + |
| 116 | +<!-- {% endraw %} --> |
| 117 | + |
| 118 | +<span class="color:green"> |
| 119 | +GOOD: |
| 120 | +</span> |
| 121 | + |
| 122 | +Define these three elements and reference them by name in the tests. |
| 123 | + |
| 124 | +``` xml |
| 125 | +<element name="relatedProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='related']"/> |
| 126 | +<element name="upSellProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='upsell']"/> |
| 127 | +<element name="crossSellProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='crosssell']"/> |
| 128 | +``` |
| 129 | + |
| 130 | +## Test |
| 131 | + |
| 132 | +1. Use actions such as [`<waitForElementVisible>`], [`<waitForLoadingMaskToDisappear>`], and [`<waitForElement>`] to wait the exact time required for the test step. |
| 133 | + Try to avoid using the [`<wait>`] action, because it forces the test to wait for the time you specify. You may not need to wait so long to proceed. |
| 134 | +1. Keep your tests short and granular for target testing, easier reviews, and easier merge conflict resolution. |
| 135 | + It also helps you to identify the cause of test failure. |
| 136 | +1. Use comments to keep tests readable and maintainable: |
| 137 | + - Keep the inline `<!-- XML comments -->` and [`<comment>`] tags up to date. |
| 138 | + It helps to inform the reader of what you are testing and to yield a more descriptive Allure report. |
| 139 | + - Explain in comments unclear or tricky test steps. |
| 140 | +1. Refer to [sections] instead of writing selectors. |
| 141 | + |
| 142 | +## Test step merging order |
| 143 | + |
| 144 | +When setting a [merging] order for a test step, do not depend on steps from Magento modules that could be disabled by an application. |
| 145 | + |
| 146 | +For example, when you write a test step to create a gift card product, set your test step **after** simple product creation and let the MFTF handle the merge order. |
| 147 | +Since the configurable product module could be disabled, this approach is more reliable than setting the test step **before** creating a configurable product. |
| 148 | + |
| 149 | +<!-- Link definitions --> |
| 150 | + |
| 151 | +[`<after>`]: test/actions.html#before-and-after |
| 152 | +[`<before>`]: test/actions.html#before-and-after |
| 153 | +[`<comment>`]: test/actions.html#comment |
| 154 | +[`<createData>`]: test/actions.html#createdata |
| 155 | +[`<deleteData>`]: test/actions.html#deletedata |
| 156 | +[`<wait>`]: test/actions.html#wait |
| 157 | +[`<waitForElement>`]: test/actions.html#waitforelement |
| 158 | +[`<waitForElementVisible>`]: test/actions.html#waitforelementvisible |
| 159 | +[`<waitForLoadingMaskToDisappear>`]: test/actions.html#waitforloadingmasktodisappear |
| 160 | +[Action group]: test/action-groups.html |
| 161 | +[annotations]: test/annotations.html |
| 162 | +[entity]: data.html |
| 163 | +[extension]: extending.html |
| 164 | +[merging]: merging.html |
| 165 | +[parameterized selectors]: section/parameterized-selectors.html |
| 166 | +[sections]: section.html |
0 commit comments