Skip to content

Commit 38cde07

Browse files
committed
Merge remote-tracking branch 'origin/develop' into MQE-1919
2 parents c0a885c + c069eca commit 38cde07

File tree

5 files changed

+189
-82
lines changed

5 files changed

+189
-82
lines changed

docs/best-practices.md

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,12 @@ Check out our best practices below to ensure you are getting the absolute most o
55
## Action group
66

77
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.
8+
Add additional explanation in annotations if needed.
99
2. Provide default values for the arguments that apply to your most common case scenarios.
1010

1111
## `actionGroups` vs `extends`
1212

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

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

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

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

61+
<!-- {% raw %} -->
62+
6163
#### Test file name
6264

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

6567
Example: _StorefrontCreateCustomerTest.xml_.
6668

69+
#### Action Group file name
70+
71+
Format: {_Admin_ or _Storefront_}{Action Group Summary}ActionGroup.xml`, where Action Group Summary describes with a few words what we can expect from it.
72+
73+
Example: _AdminCreateStoreActionGroup.xml_
74+
6775
#### Section file name
6876

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

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

85+
<!-- {% endraw %} -->
86+
7787
Example: _ProductData.xml_.
7888

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

8797
- 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">`.
98+
- Test name attributes. Example: `<test name="TestAllTheThingsTest">`
99+
- Data entity names. Example: `<entity name="OutOfStockProduct">`
100+
- Page name. Example: `<page name="AdminLoginPage">`
101+
- Section name. Example: `<section name="AdminCategorySidebarActionSection">`
102+
- Action group name. Example: `<actionGroup name="LoginToAdminActionGroup">`
93103

94104
#### Lower case
95105

96106
Use a lower case first letter for:
97107

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

101112
## Page object
102113

docs/commands/mftf.md

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -463,18 +463,39 @@ The example parameters are taken from the `etc/config/.env.example` file.
463463

464464
### `static-checks`
465465

466-
Runs all MFTF static-checks on the test codebase that MFTF is currently attached to.
466+
Runs all or specific MFTF static-checks on the test codebase that MFTF is currently attached to.
467+
If no script name argument is specified, all existing static check scripts will run.
467468

468-
#### Existing static checks
469+
#### Usage
469470

470-
* Test Dependency: Checks that test dependencies do not violate Magento module's composer dependencies.
471+
```bash
472+
vendor/bin/mftf static-checks [<names>]...
473+
```
471474

472-
#### Usage
475+
#### Examples
476+
477+
To check what existing static check scripts are available
478+
479+
```bash
480+
vendor/bin/mftf static-checks --help
481+
```
482+
483+
To run all existing static check scripts
473484

474485
```bash
475486
vendor/bin/mftf static-checks
476487
```
477488

489+
To run specific static check scripts
490+
491+
```bash
492+
vendor/bin/mftf static-checks testDependencies
493+
```
494+
495+
#### Existing static checks
496+
497+
* Test Dependency: Checks that test dependencies do not violate Magento module's composer dependencies.
498+
478499
### `upgrade:tests`
479500

480501
Applies all the MFTF major version upgrade scripts to test components in the given path (`test.xml`, `data.xml`, etc).

docs/extending.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ __Use case__: Create two similar tests with different `url` (`"{{AdminCategoryPa
2626
> Test with "extends":
2727
2828
```xml
29-
<tests >
29+
<tests>
3030
<test name="AdminCategoryTest">
3131
<annotations>
3232
...
@@ -47,7 +47,7 @@ __Use case__: Create two similar tests with different `url` (`"{{AdminCategoryPa
4747
> Test without "extends":
4848
4949
```xml
50-
<tests >
50+
<tests>
5151
<test name="AdminCategoryTest">
5252
<annotations>
5353
...
@@ -77,7 +77,7 @@ __Use case__: Create two similar tests where the second test contains two additi
7777
> Tests with "extends":
7878
7979
```xml
80-
<tests >
80+
<tests>
8181
<test name="LogInAsAdminTest">
8282
<amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
8383
<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
9595
> Tests without "extends":
9696
9797
```xml
98-
<tests >
98+
<tests>
9999
<test name="LogInAsAdminTest">
100100
<amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
101101
<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
125125
> Tests with "extends":
126126
127127
```xml
128-
<tests >
128+
<tests>
129129
<test name="LogInAsAdminTest">
130130
<before>
131131
<amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
@@ -147,7 +147,7 @@ __Use case__: Create two similar tests where the second one contains two additio
147147
> Tests without "extends":
148148
149149
```xml
150-
<tests >
150+
<tests>
151151
<test name="LogInAsAdminTest">
152152
<before>
153153
<amOnPage url="{{AdminLoginPage}}" stepKey="navigateToAdmin"/>
@@ -295,7 +295,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
295295
> Entities with "extends":
296296
297297
```xml
298-
<entities >
298+
<entities>
299299
<entity name="DivPanel">
300300
<data key="divColor">Red</data>
301301
<data key="divSize">80px</data>
@@ -310,7 +310,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
310310
> Entities without "extends":
311311
312312
```xml
313-
<entities >
313+
<entities>
314314
<entity name="DivPanel">
315315
<data key="divColor">Red</data>
316316
<data key="divSize">80px</data>
@@ -331,7 +331,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
331331
> Entities with "extends":
332332
333333
```xml
334-
<entities >
334+
<entities>
335335
<entity name="DivPanel">
336336
<data key="divColor">Red</data>
337337
<data key="divSize">80px</data>
@@ -347,7 +347,7 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
347347
> Entities without "extends":
348348
349349
```xml
350-
<entities >
350+
<entities>
351351
<entity name="DivPanel">
352352
<data key="divColor">Red</data>
353353
<data key="divSize">80px</data>

docs/test/action-groups.md

Lines changed: 61 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,10 @@ The following diagram shows the structure of an MFTF action group:
1010

1111
The following conventions apply to MFTF action groups:
1212

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

1618
The XML format for the `actionGroups` declaration is:
1719

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

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

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

4043
### Create an action group declaration
4144

4245
To create the `<actionGroup>` declaration:
4346

44-
1. Begin with a _Backend/ActionGroup/LoginToAdminActionGroup.xml_ template for the `<actionGroup>`:
47+
1. Begin with a template for the `<actionGroup>`:
4548

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

4952
<actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5053
xsi:noNamespaceSchemaLocation="urn:magento:mftf:Test/etc/actionGroupSchema.xsd">
51-
<actionGroup name="LoginToAdminActionGroup">
52-
...
54+
<actionGroup name="{Action Group Name}">
55+
5356
</actionGroup>
5457
</actionGroups>
5558
```
5659

57-
<!-- {% raw %} -->
58-
5960
1. Add actions to the `actionGroup` arguments:
6061

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

8283
<actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
8384
xsi:noNamespaceSchemaLocation="urn:magento:mftf:Test/etc/actionGroupSchema.xsd">
84-
<actionGroup name="LoginToAdminActionGroup">
85-
<arguments>
86-
<argument name="adminUser" defaultValue="_defaultAdmin"/>
87-
</arguments>
88-
<fillField stepKey="fillUsername" selector="#username" userInput="{{adminUser.username}}" />
89-
<fillField stepKey="fillPassword" selector="#password" userInput="{{adminUser.password}}" />
90-
<click stepKey="click" selector="#login" />
91-
</actionGroup>
85+
<actionGroup name="LoginAsAdmin">
86+
<annotations>
87+
<description>Login to Backend Admin using provided User Data. PLEASE NOTE: This Action Group does NOT validate that you are Logged In.</description>
88+
</annotations>
89+
<arguments>
90+
<argument name="adminUser" type="entity" defaultValue="DefaultAdminUser"/>
91+
</arguments>
92+
93+
<amOnPage url="{{AdminLoginPage.url}}" stepKey="navigateToAdmin"/>
94+
<fillField selector="{{AdminLoginFormSection.username}}" userInput="{{adminUser.username}}" stepKey="fillUsername"/>
95+
<fillField selector="{{AdminLoginFormSection.password}}" userInput="{{adminUser.password}}" stepKey="fillPassword"/>
96+
<click selector="{{AdminLoginFormSection.signIn}}" stepKey="clickLogin"/>
97+
<closeAdminNotification stepKey="closeAdminNotification"/>
98+
</actionGroup>
9299
</actionGroups>
93100
```
94101

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

99106
```xml
100-
<fillField stepKey="fillUsername" selector="#username" userInput="{{CustomAdminUser.username}}" />
101-
<fillField stepKey="fillPassword" selector="#password" userInput="{{CustomAdminUser.password}}" />
102-
<click stepKey="click" selector="#login" />
107+
<fillField selector="{{AdminLoginFormSection.username}}" userInput="{{adminUser.username}}" stepKey="fillUsername"/>
108+
<fillField selector="{{AdminLoginFormSection.password}}" userInput="{{adminUser.password}}" stepKey="fillPassword"/>
109+
<click selector="{{AdminLoginFormSection.signIn}}" stepKey="clickLogin"/>
103110
```
104111

105-
Instead of adding this set of actions, use the _LoginToAdminActionGroup_ `<actionGroup>` declaration in tests:
112+
Instead of adding this set of actions, use the _LoginAsAdminActionGroup_ `<actionGroup>` declaration in tests:
106113

107-
1. Reference the `LoginToAdminActionGroup` action group:
114+
1. Reference the `LoginAsAdminActionGroup` action group:
108115

109116
```xml
110-
<actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup"/>
117+
<actionGroup stepKey="loginToAdminPanel" ref="LoginAsAdminActionGroup"/>
111118
```
112119

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

115122
```xml
116-
<actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup">
123+
<actionGroup stepKey="loginToAdminPanel" ref="LoginAsAdminActionGroup">
117124
<argument name="adminUser" value="CustomAdminUser"/>
118125
</actionGroup>
119126
```
@@ -196,30 +203,34 @@ Starting with an action group such as:
196203
```
197204

198205
It can be reworked into more manageable pieces, as below. These smaller steps are easier to read, update, and reuse.
199-
200-
```xml
201-
<actionGroup name="GoToCategoryGridAndAddNewCategory">
202-
<seeInCurrentUrl url="{{AdminCategoryPage.url}}" stepKey="seeOnCategoryPage"/>
203-
<click selector="{{AdminCategorySidebarActionSection.AddSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
204-
<see selector="{{AdminHeaderSection.pageTitle}}" userInput="New Category" stepKey="seeCategoryPageTitle"/>
205-
</actionGroup>
206-
207-
<actionGroup name="FillInBasicCategoryFields">
208-
<arguments>
209-
<argument name="categoryEntity" defaultValue="_defaultCategory"/>
210-
</arguments>
211-
<fillField selector="{{AdminCategoryBasicFieldSection.CategoryNameInput}}" userInput="{{categoryEntity.name}}" stepKey="enterCategoryName"/>
212-
<click selector="{{AdminCategorySEOSection.SectionHeader}}" stepKey="openSEO"/>
213-
<fillField selector="{{AdminCategorySEOSection.UrlKeyInput}}" userInput="{{categoryEntity.name_lwr}}" stepKey="enterURLKey"/>
214-
</actionGroup>
215-
216-
<actionGroup name="SaveAndVerifyCategoryCreation">
217-
<click selector="{{AdminCategoryMainActionsSection.SaveButton}}" stepKey="saveCategory"/>
218-
<seeElement selector="{{AdminCategoryMessagesSection.SuccessMessage}}" stepKey="assertSuccess"/>
219-
<seeInTitle userInput="{{categoryEntity.name}}" stepKey="seeNewCategoryPageTitle"/>
220-
<seeElement selector="{{AdminCategorySidebarTreeSection.categoryInTree(categoryEntity.name)}}" stepKey="seeCategoryInTree"/>
221-
</actionGroup>
222-
```
206+
* GoToCategoryGridAndAddNewCategory
207+
```xml
208+
<actionGroup name="GoToCategoryGridAndAddNewCategory">
209+
<seeInCurrentUrl url="{{AdminCategoryPage.url}}" stepKey="seeOnCategoryPage"/>
210+
<click selector="{{AdminCategorySidebarActionSection.AddSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
211+
<see selector="{{AdminHeaderSection.pageTitle}}" userInput="New Category" stepKey="seeCategoryPageTitle"/>
212+
</actionGroup>
213+
```
214+
* FillInBasicCategoryFields
215+
```xml
216+
<actionGroup name="FillInBasicCategoryFields">
217+
<arguments>
218+
<argument name="categoryEntity" defaultValue="_defaultCategory"/>
219+
</arguments>
220+
<fillField selector="{{AdminCategoryBasicFieldSection.CategoryNameInput}}" userInput="{{categoryEntity.name}}" stepKey="enterCategoryName"/>
221+
<click selector="{{AdminCategorySEOSection.SectionHeader}}" stepKey="openSEO"/>
222+
<fillField selector="{{AdminCategorySEOSection.UrlKeyInput}}" userInput="{{categoryEntity.name_lwr}}" stepKey="enterURLKey"/>
223+
</actionGroup>
224+
```
225+
* SaveAndVerifyCategoryCreation
226+
```xml
227+
<actionGroup name="SaveAndVerifyCategoryCreation">
228+
<click selector="{{AdminCategoryMainActionsSection.SaveButton}}" stepKey="saveCategory"/>
229+
<seeElement selector="{{AdminCategoryMessagesSection.SuccessMessage}}" stepKey="assertSuccess"/>
230+
<seeInTitle userInput="{{categoryEntity.name}}" stepKey="seeNewCategoryPageTitle"/>
231+
<seeElement selector="{{AdminCategorySidebarTreeSection.categoryInTree(categoryEntity.name)}}" stepKey="seeCategoryInTree"/>
232+
</actionGroup>
233+
```
223234

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

@@ -261,4 +272,4 @@ Attribute|Type|Use|Description
261272
[actions]: ./actions.md
262273
[test]: ../test.md
263274
[`argument`]: #argument-tag
264-
[created]: ../data.md#persist-data
275+
[created]: ../data.md#persist-data

0 commit comments

Comments
 (0)