Best practices
Check out our best practices below to ensure you are getting the absolute most out of the Functional Testing Framework.
Focus on reusability
Use existing Tests and resources
Adobe Commerce and Magento Open Source offers more than 3000 acceptance tests, 2500 Action groups, 750 Page declarations with more than 1500 Section definitions.
It is very probable that behaviour you want to test already exists as a Test or Action Group.
Instead of writing everything by yourself - use extends attribute to refer to existing element and customize it.
Reusable Resources
- Tests (reusable with
<test extends="...">argument) - Action Group (reusable with including
<actionGroup ref="...">, or extending<actionGroup extends="...">) - Pages (reusable with reference
{{PageDefinition.url}}) - Sections (reusable with reference
{{SectionDefinition.elementDefinition}}) - Data Entities (reusable with reference
<createData entity="...">"or extending<entity extends="...">)
Avoid using resources that are marked as Deprecated. Usually there is a replacement provided for a deprecated resource.
Extract repetitive Actions
Instead of writing a few of Tests that perform mostly the same actions, you should thing about Action group that is a container for repetitive Actions.
If each run needs different data, use <arguments> to inject necessary information.
We recommend to keep Action Groups having single responsibility, for example AdminLoginActionGroup, which expected outcome is being logged in as Administrator when Action group is executed.
Contribute
Although the Adobe Core team and Contributors join forces to cover most of the features with tests, it is impossible to have this done quickly. If you've covered Adobe Commerce or Magento Open Source Core features with functional tests—you are more than welcome to contribute.
Action group
- 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 annotations if needed.
- Provide default values for the arguments that apply to your most common case scenarios.
- One
<actionGroup>tag is allowed per action group XML file.
actionGroups vs extends
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.
When to use extends
Use extends in your new test or action group when at least one of the following conditions is applicable to your case:
- You want to keep the original test without any modifications.
- You want to create a new test that follows the same path as the original test.
- 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.
When to avoid extends
Do not use extends in the following conditions:
- You want to change the functionality of the test or action group and do not need to run the original version.
- You plan to merge the base test or action group.
The following pattern is used when merging with extends:
- The original test is merged.
- The extended test is created from the merged original test.
- The extended test is merged.
Annotation
- Use annotations in a test.
- Update your annotations correspondingly when updating tests.
Data entity
- 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. - 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"orunique="prefix"to append or prepend a unique value to the entity attribute. This ensures that tests using the entity can be repeated. - 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
Filenames
Name files according to the following patterns to make searching in future more easy:
Test filename
Format: {Admin or Storefront}{Functionality}Test.xml, where Functionality briefly describes the testing functionality.
Example: StorefrontCreateCustomerTest.xml.
Action Group filename
Format: {Admin or Storefront}{Action Group Summary}ActionGroup.xml`, where Action Group Summary is a short description of what the action group does.
Example: AdminCreateStoreActionGroup.xml
Section filename
Format: {Admin or Storefront}{UI Description}Section.xml, where UI Description briefly describes the testing UI.
Example: AdminNavbarSection.xml.
Data filename
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:
- Filenames. 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"/> - Step keys. For example:
<click selector="..." stepKey="clickLogin"/>
Page object
- One
<page>tag is allowed per page XML file. - Use parameterized selectors for constructing a selector when test-specific or runtime-generated information is needed. Do not use them for static elements.
GOOD:Copied to your clipboard<element name="relatedProductSectionText" type="text" selector=".fieldset-wrapper.admin__fieldset-section[data-index='{{productType}}']" parameterized="true"/>
Define these three elements and reference them by name in the tests.
Copied to your clipboard<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']"/>
Test
- 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. - 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.
- 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.
- Keep the inline
- Refer to sections instead of writing selectors.
- One
<test>tag is allowed per test XML file.
Test step merging order
When setting a merging order for a test step, do not depend on steps from Adobe Commerce or Magento Open Source 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 framework 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.
