Backward incompatible changes

This page highlights backward incompatible changes between releases that have a major impact and require detailed explanation and special instructions to ensure third-party tests continue working with core tests.

Minimum supported PHP version changes

We changed the minimum PHP version requirement 7.4. Because of the PHP version requirement change, this version of the framework only supports Adobe Commerce and Magento Open Source 2.4 or later.

Folder structure changes

We removed support to read test modules from the deprecated path dev/tests/acceptance/tests/functional/Magento/FunctionalTest. If there are test modules in this path, they should be moved to dev/tests/acceptance/tests/functional/Magento.

XSD schema changes

Files under test modules ActionGroup, Page, Section, Test and Suite only support a single entity per file.
The file attribute from <module> has been removed from the suite schema. <module file=""/> is no longer supported in suites.
Metadata filename format changed to `Meta.xml`*.

Only nested assertion syntax will be supported. See the assertions page for details. Here is an example of the nested assertion syntax:

<assertEquals stepKey="assertAddressOrderPage">
   <actualResult type="const">$billingAddressOrderPage</actualResult>
   <expectedResult type="const">$shippingAddressOrderPage</expectedResult>
</assertEquals>
Copied to your clipboard
<assertEquals stepKey="assertAddressOrderPage">
   <actualResult type="const">$billingAddressOrderPage</actualResult>
   <expectedResult type="const">$shippingAddressOrderPage</expectedResult>
</assertEquals>

Upgrading tests to the new schema

The following table lists the upgrade scripts that are available to upgrade tests to the new schema.

Script name	Description
`splitMultipleEntitiesFiles`	Splits files that have multiple entities into multiple files with one entity per file.
`upgradeAssertionSchema`	Updates assert actions that uses the old assertion syntax into the new nested syntax.
`renameMetadataFiles`	Renames Metadata filenames to `*Meta.xml`.
`removeModuleFileInSuiteFiles`	Removes occurrences of `<module file=""/>` from all `<suite>`s.
`removeUnusedArguments`	Removes unused arguments from action groups.
`upgradeTestSchema`	Replaces relative schema paths to URN in test files.

To run the upgrade tests:

Run bin/mftf reset --hard to remove old generated configurations.
Run bin/mftf build:project to generate new configurations.
Run bin/mftf upgrade:tests. See command page for details.
Lastly, try to generate all tests. Tests should all be generated as a result of the upgrades. If not, the most likely issue will be a changed XML schema. Check error messaging and search your codebase for the attributes listed.

Commands

--debug option NONE removed for strict schema validation. Ensure there are no schema validation errors in test modules before running commands.

Actions

`executeInSelenium` and `performOn` removed

Action: Deprecated actions executeInSelenium and performOn are removed in favor of new action helper.

Reason: executeInSelenium and performOn allowed custom PHP code to be written inline inside of XML files which was difficult to maintain, troubleshoot, and modify.

Details:

The helper allows test writers to solve advanced requirements beyond what the framework offers out of the box. See custom-helpers for more information on usage.

Here is an example of using helper in place of executeSelenium to achieve same workflow.

Old usage:

<executeInSelenium function="function ($webdriver) use ($I) {
        $heading = $webdriver->findElement(\Facebook\WebDriver\WebDriverBy::xpath('//div[contains(@class, \'inline-wysiwyg\')]//h2'));
        $actions = new \Facebook\WebDriver\Interactions\WebDriverActions($webdriver);
        $actions->moveToElement($heading, {{TinyMCEPartialHeadingSelection.startX}}, {{TinyMCEPartialHeadingSelection.startY}})
         ->clickAndHold()
         ->moveToElement($heading, {{TinyMCEPartialHeadingSelection.endX}}, {{TinyMCEPartialHeadingSelection.endY}})
         ->release()
         ->perform();
        }" stepKey="selectHeadingTextInTinyMCE"/>
Copied to your clipboard
<executeInSelenium function="function ($webdriver) use ($I) {
        $heading = $webdriver->findElement(\Facebook\WebDriver\WebDriverBy::xpath('//div[contains(@class, \'inline-wysiwyg\')]//h2'));
        $actions = new \Facebook\WebDriver\Interactions\WebDriverActions($webdriver);
        $actions->moveToElement($heading, {{TinyMCEPartialHeadingSelection.startX}}, {{TinyMCEPartialHeadingSelection.startY}})
         ->clickAndHold()
         ->moveToElement($heading, {{TinyMCEPartialHeadingSelection.endX}}, {{TinyMCEPartialHeadingSelection.endY}})
         ->release()
         ->perform();
        }" stepKey="selectHeadingTextInTinyMCE"/>

New usage:

<helper class="\Magento\PageBuilder\Test\Mftf\Helper\SelectText" method="selectText" stepKey="selectHeadingTextInTinyMCE">
    <argument name="context">//div[contains(@class, 'inline-wysiwyg')]//h2</argument>
    <argument name="startX">{{TinyMCEPartialHeadingSelection.startX}}</argument>
    <argument name="startY">{{TinyMCEPartialHeadingSelection.startY}}</argument>
    <argument name="endX">{{TinyMCEPartialHeadingSelection.endX}}</argument>
    <argument name="endY">{{TinyMCEPartialHeadingSelection.endY}}</argument>
</helper>
Copied to your clipboard
<helper class="\Magento\PageBuilder\Test\Mftf\Helper\SelectText" method="selectText" stepKey="selectHeadingTextInTinyMCE">
    <argument name="context">//div[contains(@class, 'inline-wysiwyg')]//h2</argument>
    <argument name="startX">{{TinyMCEPartialHeadingSelection.startX}}</argument>
    <argument name="startY">{{TinyMCEPartialHeadingSelection.startY}}</argument>
    <argument name="endX">{{TinyMCEPartialHeadingSelection.endX}}</argument>
    <argument name="endY">{{TinyMCEPartialHeadingSelection.endY}}</argument>
</helper>

`pauseExecution` removed

Action: pauseExecution is removed in favor of pause.

Reason: [WebDriver]pauseExecution is removed in Codeception 3 in favor of I->pause().

Details:

See the actions page for details. Here is a usage example:

<pause stepKey="pauseExecutionKey"/>
Copied to your clipboard
<pause stepKey="pauseExecutionKey"/>

Removed assert actions

Action: Assert actions assertInternalType, assertNotInternalType and assertArraySubset are removed.

Reason: PHPUnit 9 has dropped support for these assertions.

Updated assert actions

Action: The delta attribute has been removed from assertEquals and assertNotEquals. Instead, new assert actions have been introduced:

assertEqualsWithDelta
assertNotEqualsWithDelta
assertEqualsCanonicalizing
assertNotEqualsCanonicalizing
assertEqualsIgnoringCase
assertNotEqualsIgnoringCase

Reason: PHPUnit 9 has dropped support for optional parameters for assertEquals and assertNotEquals and has introduced these new assertions.

Details:

Usage of assertEquals or assertNotEquals with a specified delta, should be replaced with appropriate assertion from the above list.

`assertContains` supports only iterable haystacks

Action: assertContains and assertNotContains now only supports iterable haystacks. These assert actions have been added to work with string haystacks:

assertStringContainsString
assertStringNotContainsString
assertStringContainsStringIgnoringCase
assertStringNotContainsStringIgnoringCase

Reason: With PHPUnit 9, assertContains and assertNotContains only allows iterable haystacks. New assertions have been introduced to support string haystacks.

Details:

Usages of assertContains and assertNotContains with string haystacks should be replaced with appropriate assertion from the above list.

Usage example for string haystacks:

<assertStringContainsString stepKey="assertDiscountOnPrice2">
  <actualResult type="const">$grabSimpleProdPrice2</actualResult>
  <expectedResult type="string">$110.70</expectedResult>
</assertStringContainsString>
Copied to your clipboard
<assertStringContainsString stepKey="assertDiscountOnPrice2">
  <actualResult type="const">$grabSimpleProdPrice2</actualResult>
  <expectedResult type="string">$110.70</expectedResult>
</assertStringContainsString>

`formatMoney` removed

Action: formatMoney has been removed in favor of formatCurrency.

Reason: PHP 7.4 has deprecated use of formatMoney.

Details: Format input to specified currency according to the locale specified.

Usage example:

<formatCurrency userInput="1234.56789000" locale="de_DE" currency="USD" stepKey="usdInDE"/>
Copied to your clipboard
<formatCurrency userInput="1234.56789000" locale="de_DE" currency="USD" stepKey="usdInDE"/>