Best practices

This topic was updated due to the 2.2.0 MFTF release.

Check out our best practices below to ensure you’re getting the absolute most out of the Magento Functional Testing Framework.

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.
  2. Provide default values for the arguments that apply to your most common case scenarios.


  1. Use annotations in a test.
  2. Update your annotations correspondingly when updating tests.

Data entity

  1. Keep your testing instance clean. Remove data after the test if the test required creating any data. Use a corresponding <deleteData> test step in your <after> block when using a <createData> action in a <before> block.
  2. Make specific data entries under test to be unique. Enable data uniqueness where data values are required to be unique in a database by test design. Use unique=”suffix” or unique=”prefix” to append or prepend a unique value to the entity attribute. This ensures that tests using the entity can be repeated.
  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. Create a new data entity for your test if you are not sure.

Naming conventions

File names

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.

Section file name

Format: {Admin or Storefront}{UI Description}Section.xml, where UI Description briefly describes the testing UI.

Example: AdminNavbarSection.xml.

Data file name

Format: {Type}Data.xml, where Type represents the entity type.

Example: ProductData.xml.

Object names

Use the Foo.camelCase naming convention, which is similar to Classes and classProperties in PHP.

Upper case

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

Lower case

Use a lower case first letter for:

  • Data keys. Example: <data key="firstName">.
  • Element names. Examples: <element name="confirmDeleteButton"/>.

Page object

Use parameterized selectors for constructing a selector when test specific or runtime generated information is needed. Do not use them for static elements.


<element name="relatedProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='']" parameterized="true"/>


Define these three elements and reference them by name in the tests.

<element name="relatedProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='related']"/>
<element name="upSellProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='upsell']"/>
<element name="crossSellProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='crosssell']"/>


  1. Use actions such as <waitForElementVisible>, <waitForLoadingMaskToDisappear>, and <waitForElement> to wait the exact time required for the test step. 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.
  2. Keep your tests short and granular for target testing, easier reviews, and easier merge conflict resolution. It also helps you to identify the cause of test failure.
  3. Use comments to keep tests readable and maintainable:
    • Keep the inline <!-- XML comments --> and <comment> tags up to date. It helps to inform the reader of what you are testing and to yield a more descriptive Allure report.
    • Explain in comments unclear or tricky test steps.
  4. Refer to sections instead of writing selectors.

Test step merging order

When setting a merging order for a test step, do not depend on steps from Magento modules that could be disabled by an application.

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. Since the configurable product module could be disabled, this approach is more reliable than setting the test step before creating a configurable product.