Page structure

The Functional Testing Framework 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 a Functional Testing Framework page:

XML Structure of a Functional Testing Framework page

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="urn:magento:mftf:Page/etc/PageObject.xsd">
   <page name="" url="" module="" area="">
      <section name=""/>
      <section name=""/>
   </page>
</pages>
Copied to your clipboard
<?xml version="1.0" encoding="UTF-8"?>

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:mftf:Page/etc/PageObject.xsd">
   <page name="" url="" module="" area="">
      <section name=""/>
      <section name=""/>
   </page>
</pages>

Principles

The following conventions apply to 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.
One <page> tag is allowed per page XML file.

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="urn:magento:mftf: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>
Copied to your clipboard
<?xml version="1.0" encoding="UTF-8"?>

<pages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:mftf: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 Catalog module and is called by the baseUrl + backendName + catalog/category/ URl.

The AdminCategoryPage declares four sections:

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"/>
Copied to your clipboard
<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="urn:magento:mftf:Page/etc/PageObject.xsd">
   <page name="StorefrontCategoryPage" url="/{{var1}}.html" module="Magento_Catalog" parameterized="true" area="storefront">
      <section name="StorefrontCategoryMainSection"/>
   </page>
</pages>
Copied to your clipboard
<?xml version="1.0" encoding="UTF-8"?>

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

<amOnPage url="{{StorefrontCategoryPage.url($createPreReqCategory.name$)}}" stepKey="navigateToCategoryPage"/>
Copied to your clipboard
<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 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.

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 only one <page> element.

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 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.
`deprecated`	string	optional	Used to warn about the future deprecation of the data entity. String will appear in Allure reports and console output at runtime.

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