Page structure in the Magento Functional Testing Framework

This topic was updated due to the 2.0.2 MFTF release.

Overview

The MFTF employs a modified concept of PageObjects. You define the contents of a page, for reference in a test, at both a page and section level. The majority of elements are defined on a section reference. The section here is a reusable section of a page. The pageObject itself then serves to list the URL of the page and the sections which it contains. In this way, you reuse sections and maintain a reusable single source of truth to define the elements exercisable on a page. Avoiding hardcoded location selectors from tests increases the maintainability and readability of tests, and test execution output/logging.

Two types of pages are available:

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

The following diagram demonstrates XML structure of a page in the MFTF:

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

Format

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../../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

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

Examples

The following examples demonstrate explicit page and parameterized page with explanations.

Explicit page

Catalog/Page/AdminCategoryPage.xml is provided as an example:

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../../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>

The example above demonstrates Catalog/Page/AdminCategoryPage.xml that declares a page with name AdminCategoryPage. It will be merged with other AdminCategoryPage pages from other modules.

A corresponding web page is:

  • generated by Magento Catalog module
  • called by URl baseUrl + backendName + catalog/category/

The AdminCategoryPage declares four sections:

  • AdminCategorySidebarActionSection that is located in Catalog/Section/AdminCategorySidebarActionSection.xml
  • AdminCategorySidebarTreeSection that is located in Catalog/Section/AdminCategorySidebarTreeSection.xml
  • AdminCategoryBasicFieldSection that is located in Catalog/Section/AdminCategoryBasicFieldSection.xml
  • AdminCategorySEOSection that is located in Catalog/Section/AdminCategorySEOSection.xml

Example of a call in test:

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

Parameterized page

Catalog/Page/StorefrontCategoryPage.xml is provided as an example::

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

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../../../../../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 page with name StorefrontCategoryPage. It will be merged with other StorefrontCategoryPage pages from other modules.

Example of a call in test:

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

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

A corresponding web page is:

  • generated by Magento Catalog module
  • called by URl baseUrl+/$$createPreReqCategory.name$$.html. It means, that {{var1}} is substituted by name of previously created category in the createPreReqCategory action. Learn more in <createData>.

The StorefrontCategoryPage page declares one section:

  • StorefrontCategoryMainSection that is located in Catalog/Section/StorefrontCategoryMainSection.xml

Reference

pages

Root element that points to the corresponding XML Schema location. It contains one ore more <page> elements.

page

Contains 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 The name of the module to which the page belongs. For 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 this page to only be used with amOnUrl as the url provided must be a full URL instead of the URL for a Magento page (ex. http://myFullUrl.com/).
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 Default value: "false". Set to "true" to remove this element during parsing.

It may contain several <section> elements.

section

Contains sequence of UI elements.

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