Action groups

This topic was updated due to the 2.1.0 MFTF release.

In the MFTF, you can re-use a group of actions, such as logging in as an administrator or a customer, declared in an XML file when you need to perform the same sequence of actions multiple times.

The following diagram shows the structure of an MFTF action group:

image/svg+xml actionTypeTags argument 0..∞ arguments 0..∞ actionGroup 1..∞ actionGroups

Principles

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.xml.
  • The file name and the <actionGroup> name are the same.

The XML format for the actionGroups declaration is:

<?xml version="1.0" encoding="UTF-8"?>

<actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../../vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Test/etc/testSchema.xsd">
    <actionGroup name="">
        <arguments>
            <argument name=""/>
            <argument name="" defaultValue=""/>
            <argument name="" defaultValue="" type=""/>
        </arguments>
    </actionGroup>
</actionGroups>

Example

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".

Create an action group declaration

To create the <actionGroup> declaration:

  1. Begin with a Backend/ActionGroup/LoginToAdminActionGroup.xml template for the <actionGroup>:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="../../../../../../vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Test/etc/testSchema.xsd">
        <actionGroup name="LoginToAdminActionGroup">
    ...
        </actionGroup>
    </actionGroups>
    
  2. Add actions to the actionGroup arguments:

    <actionGroup name="LoginToAdminActionGroup">
        <fillField stepKey="fillUsername" selector="#username" userInput="{{adminUser.username}}" />
        <fillField stepKey="fillPassword" selector="#password" userInput="{{adminUser.password}}" />
        <click stepKey="click" selector="#login" />
    </actionGroup>
    
  3. The userInput variable must contain a data value for test. Add a default data value for the variable to use in the most common cases. For this example, the default value is _defaultAdmin.

    <argument name="adminUser" defaultValue="_defaultAdmin"/>
    
  4. The following example shows the complete declaration:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <actionGroups xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="../../../../../../vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Test/etc/testSchema.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>
    </actionGroups>
    

Use the declaration in a test

In this test example, we want to add the following set of actions:

<fillField stepKey="fillUsername" selector="#username" userInput="{{CustomAdminUser.username}}" />
<fillField stepKey="fillPassword" selector="#password" userInput="{{CustomAdminUser.password}}" />
<click stepKey="click" selector="#login" />

Instead of adding this set of actions, use the LoginToAdminActionGroup <actionGroup> declaration in tests:

  1. Reference the LoginToAdminActionGroup action group:

    <actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup"/>
    
  2. Update the argument name/value pair to adminUser and CustomAdminUser:

    <actionGroup stepKey="loginToAdminPanel" ref="LoginToAdminActionGroup">
        <argument name="adminUser" value="CustomAdminUser"/>
    </actionGroup>
    

Data type usage

By default, an argument expects an entire entity when the type value is not defined. There are cases when you use a string instead of a whole entity.

For example, the following defines the replacement argument relevantString using a primitive data type:

<actionGroup name="fillExample">
    <arguments>
        <argument name="relevantString" defaultValue="defaultString" type="string"/>
    </arguments>
    <fillField stepKey="fillField1" selector="#input" userInput="{{relevantString}}"/>
    <click stepKey="clickSave" selector="#save"/>
    <see stepKey="seeItWorked" selector="#outputArea" userInput="{{relevantString}}"/>
    <click stepKey="clickParameterizedSelector" selector="{{SomeSection.parameterizedElement(relevantString)}}"/>
</actionGroup>

The string argument type provides a method to pass a single piece of data to the <actionGroup>during a test instead of passing an entire entity.

To explicitly define the argument value:

<actionGroup stepKey="fillWithStringLiteral" ref="fillExample">
    <argument name="relevantString" value="overrideString"/>
</actionGroup>

To define the argument value using persisted data references:

<actionGroup stepKey="fillWithStringLiteral" ref="fillExample">
    <argument name="relevantString" value="$persistedData.field1$"/>
</actionGroup>

To define the argument value based on data entity resolution:

Create an argument of type="entity". The argument value points to an entity and string pair created in a previous stepKey="persistedData" test step. The field1 data contains the required string. Even with the myCustomEntity data entity, MFTF interprets the myCustomEntity.field1 value as a string.

<actionGroup stepKey="fillWithXmlData" ref="fillExample">
    <argument name="relevantString" value="myCustomEntity.field1"/>
</actionGroup>

Elements reference

actionGroups

The <actionGroups> element is a root element that contains XML configuration attributes.

Attribute Value Description
xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" Tells the XML parser to validate this document against a schema.
xsi:noNamespaceSchemaLocation "../../../../../../vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Test/etc/testSchema.xsd" Relative path to the corresponding schema.

It may contain one or more <actionGroup>.

actionGroup

Attribute Type Use Description
name string required Identifier of the action group.

It may contain <arguments>.

arguments

The <arguments> element is a wrapper for an array of <argument> elements.

argument

Attribute Type Use Description
name string required Identifier of an argument in the scope of the corresponding action group.
defaultValue string optional Provides a default data value.
type Possible values: string, entity (default). optional Defines the argument data type; Defaults to entity.