Page structure

This topic was updated due to the 2.2.0 MFTF release.

The MFTF uses a modified concept of [PageObjects], which models the testing areas of your page as objects within the code. This reduces occurrences of duplicated code and enables you to fix things quickly, in one place, when things change. You define the contents of a page, for reference in a <test>, at both the <page> and <section> level.

The pageObject lists the URL of the page and the sections that it contains. You can reuse sections to define the elements on a page that are exercisable, while also ensuring a single source of truth to help maintain consistency.

Avoid hard-coded location selectors from tests to increase the maintainability and readability of the tests, as well as improve the test execution output and logging.

Two types of pages are available:

  • Page with url declared as a constant string or [explicit page] - In a test it is called in a format like {{NameOfPage.url}}, where NameOfPage is a value of name in the corresponding page declaration *.xml file.
  • Page with url declared as a string with one or more variables or [parameterized page] - In a test it is called using a format like {{NameOfPage.url(var1, var2, ...)}}, where var1, var2 etc. are parameters that will be substituted in the url of the corresponding <page> declaration.

The following diagram shows the XML structure of an MFTF page:

image/svg+xml section 0..∞ page 1..∞ pages

Format

The format of <page> is:

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../../dev/tests/acceptance/vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Page/etc/PageObject.xsd">
    <page name="" url="" module="" area="">
        <section name=""/>
        <section name=""/>
    </page>
</pages>

Principles

The following conventions apply to MFTF pages:

  • <page> name is the same as the file name.
  • <page> name must be alphanumeric.
  • *Page.xml is stored in the Page directory of a module.
  • The name format is {Admin|Storefront}{PageDescription}Page.xml.

The .url attribute is required when using the page for actions that require the URL argument.

Page examples

These examples demonstrate explicit and parameterized pages and include informative explanations.

Explicit page

Example (Catalog/Page/AdminCategoryPage.xml file):

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../..dev/tests/acceptance/vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Page/etc/PageObject.xsd">
    <page name="AdminCategoryPage" url="catalog/category/" module="Magento_Catalog" area="admin">
        <section name="AdminCategorySidebarActionSection"/>
        <section name="AdminCategorySidebarTreeSection"/>
        <section name="AdminCategoryBasicFieldSection"/>
        <section name="AdminCategorySEOSection"/>
    </page>
</pages>

In this example, the Catalog/Page/AdminCategoryPage.xml file declares a page with the name AdminCategoryPage. It will be merged with the other AdminCategoryPage pages from other modules.

The corresponding web page is generated by the Magento Catalog module and is called by the baseUrl + backendName + catalog/category/ URl.

The AdminCategoryPage declares four [sections][section]:

  • AdminCategorySidebarActionSection - located in the Catalog/Section/AdminCategorySidebarActionSection.xml file
  • AdminCategorySidebarTreeSection - located in the Catalog/Section/AdminCategorySidebarTreeSection.xml file
  • AdminCategoryBasicFieldSection - located in the Catalog/Section/AdminCategoryBasicFieldSection.xml file
  • AdminCategorySEOSection - located in the Catalog/Section/AdminCategorySEOSection.xml file

The following is an example of a call in test:

<amOnPage url="{{AdminCategoryPage.url}}" stepKey="navigateToAdminCategory"/>

Parameterized page

Example (Catalog/Page/StorefrontCategoryPage.xml file):

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../..dev/tests/acceptance/vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Page/etc/PageObject.xsd">
    <page name="StorefrontCategoryPage" url="/{{var1}}.html" module="Magento_Catalog" parameterized="true" area="storefront">
        <section name="StorefrontCategoryMainSection"/>
    </page>
</pages>

This example shows the page with the name StorefrontCategoryPage. It will be merged with the other StorefrontCategoryPage pages from other modules.

The following is an example of a call in test:

<amOnPage url="{{StorefrontCategoryPage.url($$createPreReqCategory.name$$)}}" stepKey="navigateToCategoryPage"/>

The StorefrontCategoryPage page is declared as parameterized, where the url contains a {{var1}} parameter.

The corresponding web page is generated by the Magento Catalog module and is called by the baseUrl+/$$createPreReqCategory.name$$.html URl.

{{var1}} is substituted with the name of the previously created category in the createPreReqCategory action.

See also <createData>.


The StorefrontCategoryPage page declares only the StorefrontCategoryMainSection [section], which is located in the Catalog/Section/StorefrontCategoryMainSection.xml file.

Elements reference

There are several XML elements that are used in <page> in the MFTF.

pages

<pages> are elements that point to the corresponding XML Schema location. It contains one or more <page> elements.

page

<page> contains a sequence of UI sections in a page.

Attributes Type Use Description
name string required Unique page name identifier.
url string required URL path (excluding the base URL) for the page. Use parameterized notation ({{var1}}) for replaceable parameters, such as the edit page for a persisted entity that is based on an ID or a name.
module string required Name of the module to which the page belongs. The name must be prefixed with a vendor name. It corresponds to the parent directory where the module with tests is stored. Example: "Magento_Catalog".
area string required The area where this page lives. Three possible values: admin prepends BACKEND_NAME to url, storefront does not prepend anything to url, external flags the page for use with amOnUrl. The url provided must be a full URL, such as http://myFullUrl.com/, instead of the URL for a Magento page.
parameterized boolean optional Include and set to "true" if the url for this page has parameters that need to be replaced for proper use.
remove boolean optional The default value is "false". Set to "true" to remove this element during parsing.

<page> may contain several <section> elements.

section

<section> contains the sequence of UI elements. A section is a reusable piece or part of a page.

Attributes Type Use Description
name string required Unique section name identifier.
remove boolean optional The default value is "false". Set to "true" to remove this element during parsing.

[explicit page: #explicit-page [PageObjects]: https://github.com/SeleniumHQ/selenium/wiki/PageObjects [parameterized page]: #parameterized-page [section]: section.html