Merge pull request #473 from magento-devdocs/db_mftf_linting

MFTF linting cleanup

Author: KevinBKozan

docs/best-practices.md

@@ -84,19 +84,19 @@ Use the _Foo.camelCase_ naming convention, which is similar to _Classes_ and _cl
 
 Use an upper case first letter for:
 
-- File names. 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">`.
+-  File names. 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"/>`.
+-  Data keys. Example: `<data key="firstName">`.
+-  Element names. Examples: `<element name="confirmDeleteButton"/>`.
 
 ## Page object
 
@@ -134,9 +134,9 @@ Define these three elements and reference them by name in the tests.
 1. 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.
 1. Use comments to keep tests readable and maintainable:
-   - Keep the inline `<!-- XML comments -->` and [`<comment>`] tags up to date.
+   -  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.
+   -  Explain in comments unclear or tricky test steps.
 1. Refer to [sections] instead of writing selectors.
 
 ## Test step merging order

docs/credentials.md

@@ -148,8 +148,8 @@ Credentials can be used in actions: [`fillField`][], [`magentoCLI`][], and [`cre
 
 Define the value as a reference to the corresponding key in the credentials file or vault such as `{{_CREDS.my_data_key}}`:
 
-- `_CREDS` is an environment constant pointing to the `.credentials` file
-- `my_data_key` is a key in the the `.credentials` file or vault that contains the value to be used in a test step
+-  `_CREDS` is an environment constant pointing to the `.credentials` file
+-  `my_data_key` is a key in the the `.credentials` file or vault that contains the value to be used in a test step
 
 For example, reference secret data in the [`fillField`][] action with the `userInput` attribute.
 

docs/data.md

@@ -17,8 +17,8 @@ userInput="{{SimpleSubCategory.name}}"
 
 In this example:
 
-* `SimpleSubCategory` is an entity name.
-* `name` is a `<data>` key of the entity. The corresponding value will be assigned to `userInput` as a result.
+*  `SimpleSubCategory` is an entity name.
+*  `name` is a `<data>` key of the entity. The corresponding value will be assigned to `userInput` as a result.
 
 ### Environmental data
 
@@ -28,8 +28,8 @@ userInput="{{_ENV.MAGENTO_ADMIN_USERNAME}}"
 
 In this example:
 
-* `_ENV` is a reference to the `dev/tests/acceptance/.env` file, where basic environment variables are set.
-* `MAGENTO_ADMIN_USERNAME` is a name of an environment variable.
+*  `_ENV` is a reference to the `dev/tests/acceptance/.env` file, where basic environment variables are set.
+*  `MAGENTO_ADMIN_USERNAME` is a name of an environment variable.
    The corresponding value will be assigned to `userInput` as a result.
 
 ### Sensitive data
@@ -40,10 +40,10 @@ userInput="{{_CREDS.my_secret_token}}"
 
 In this example:
 
-* `_CREDS` is a constant to reference to the `dev/tests/acceptance/.credentials` file, where sensitive data and secrets are stored for use in a test.
-* `MY_SECRET_TOKEN` is the name of a key in the credentials variable.
+*  `_CREDS` is a constant to reference to the `dev/tests/acceptance/.credentials` file, where sensitive data and secrets are stored for use in a test.
+*  `MY_SECRET_TOKEN` is the name of a key in the credentials variable.
   The corresponding value of the credential will be assigned to `userInput` as a result.
-* The decrypted values are only available in the `.credentials` file in which they are stored.
+*  The decrypted values are only available in the `.credentials` file in which they are stored.
 
 Learn more in [Credentials][].
 
@@ -59,8 +59,8 @@ userInput="$createCustomer.email$"
 
 In this example:
 
-* `createCustomer` is a step key of the corresponding test step that creates an entity.
-* `email` is a data key of the entity.
+*  `createCustomer` is a step key of the corresponding test step that creates an entity.
+*  `email` is a data key of the entity.
   The corresponding value will be assigned to `userInput` as a result.
 
 <div class="bs-callout bs-callout-info">
@@ -118,10 +118,10 @@ The format of `<data>` is:
 
 The following conventions apply to MFTF `<data>`:
 
-* A `<data>` file may contain multiple data entities.
-* Camel case is used for `<data>` elements. The name represents the `<data>` type. For example, a file with customer data is `CustomerData.xml`. A file for simple product would be `SimpleProductData.xml`.
-* Camel case is used for the entity name.
-* The file name must have the suffix `Data.xml`.
+*  A `<data>` file may contain multiple data entities.
+*  Camel case is used for `<data>` elements. The name represents the `<data>` type. For example, a file with customer data is `CustomerData.xml`. A file for simple product would be `SimpleProductData.xml`.
+*  Camel case is used for the entity name.
+*  The file name must have the suffix `Data.xml`.
 
 ## Example
 
@@ -152,16 +152,16 @@ All entities that have the same name will be merged during test generation. Both
 
 `_defaultCategory` sets three data fields:
 
-* `name` defines the category name as `simpleCategory` with a unique suffix. Example: `simpleCategory598742365`.
-* `name_lwr` defines the category name in lowercase format with a unique suffix. Example: `simplecategory697543215`.
-* `is_active` sets the enable category to `true`.
+*  `name` defines the category name as `simpleCategory` with a unique suffix. Example: `simpleCategory598742365`.
+*  `name_lwr` defines the category name in lowercase format with a unique suffix. Example: `simplecategory697543215`.
+*  `is_active` sets the enable category to `true`.
 
 `SimpleSubCategory` sets four data fields:
 
-* `name` that defines the category name with a unique suffix. Example: `SimpleSubCategory458712365`.
-* `name_lwr` that defines the category name in lowercase format with a unique suffix. Example: `simplesubcategory753698741`.
-* `is_active` sets the enable category to `true`.
-* `include_in_menu` that sets the include in the menu to `true`.
+*  `name` that defines the category name with a unique suffix. Example: `SimpleSubCategory458712365`.
+*  `name_lwr` that defines the category name in lowercase format with a unique suffix. Example: `simplesubcategory753698741`.
+*  `is_active` sets the enable category to `true`.
+*  `include_in_menu` that sets the include in the menu to `true`.
 
 The following is an example of a call in test:
 

docs/debugging.md

@@ -2,15 +2,15 @@
 
 Debugging within the Magento Functional Testing Framework is helpful in identifying test bugs by allowing you to pause execution so that you may:
 
-- Examine the page.
-- Check returned data and other variables being used during run-time.
+-  Examine the page.
+-  Check returned data and other variables being used during run-time.
 
 This is straightforward to do once you create a basic Debug Configuration.
 
 ## Prerequisites
 
-- [Xdebug][]
-- PHPUnit configured for use in [PHPStorm][]
+-  [Xdebug][]
+-  PHPUnit configured for use in [PHPStorm][]
 
 ## Creating Debug Configuration with PHPStorm
 
@@ -27,8 +27,8 @@ If you get a warning `Path to Codeception for local machine is not configured.`:
 
 The easiest method of tagging a test for debugging is the following:
 
-- In your Debug configuration, locate `Test Runner options:` and set `--group testDebug`.
-- When you want to debug a test you are working on, simply add `<group value="testDebug"/>` to the annotations. Be sure to remove this after done debugging.
+-  In your Debug configuration, locate `Test Runner options:` and set `--group testDebug`.
+-  When you want to debug a test you are working on, simply add `<group value="testDebug"/>` to the annotations. Be sure to remove this after done debugging.
 
 Your Debug Configuration should now be able to run your test and pause execution on any breakpoints you have set in the generated `.php` file under the `_generated` folder.
 

docs/extending.md

@@ -5,9 +5,9 @@ For example, only one or two parameters (for example, URL) might vary between te
 To avoid copy-pasting and to save some time the Magento Functional Testing Framework (MFTF) enables you to extend test components such as [test], [data], and [action group].
 You can create or update any component of the parent body in your new test/action group/entity.
 
-* A test starting with `<test name="SampleTest" extends="ParentTest">` creates a test `SampleTest` that takes body of existing test `ParentTest` and adds to it the body of `SampleTest`.
-* An action group starting with `<actionGroup name="SampleActionGroup" extends="ParentActionGroup">` creates an action group based on the `ParentActionGroup`, but with the changes specified in `SampleActionGroup`.
-* An entity starting with `<entity name="SampleEntity" extends="ParentEntity">` creates an entity `SampleEntity` that is equivalent to merging the `SampleEntity` with the `ParentEntity`.
+*  A test starting with `<test name="SampleTest" extends="ParentTest">` creates a test `SampleTest` that takes body of existing test `ParentTest` and adds to it the body of `SampleTest`.
+*  An action group starting with `<actionGroup name="SampleActionGroup" extends="ParentActionGroup">` creates an action group based on the `ParentActionGroup`, but with the changes specified in `SampleActionGroup`.
+*  An entity starting with `<entity name="SampleEntity" extends="ParentEntity">` creates an entity `SampleEntity` that is equivalent to merging the `SampleEntity` with the `ParentEntity`.
 
 Specify needed variations for a parent object and produce a copy of the original that incorporates the specified changes (the "delta").
 
@@ -71,8 +71,8 @@ __Use case__: Create two similar tests with different `url` (`"{{AdminCategoryPa
 
 __Use case__: Create two similar tests where the second test contains two additional steps:
 
-* `checkOption` before `click` (`stepKey="clickLogin"`)
-* `seeInCurrentUrl` after `click` in the `LogInAsAdminTest` test (in the `.../Backend/Test/LogInAsAdminTest.xml` file)
+*  `checkOption` before `click` (`stepKey="clickLogin"`)
+*  `seeInCurrentUrl` after `click` in the `LogInAsAdminTest` test (in the `.../Backend/Test/LogInAsAdminTest.xml` file)
 
 > Tests with "extends":
 
@@ -119,8 +119,8 @@ __Use case__: Create two similar tests where the second test contains two additi
 
 __Use case__: Create two similar tests where the second one contains two additional actions in the `before` hook:
 
-* `checkOption` before `click` (`stepKey="clickLogin"`)
-* `seeInCurrentUrl` after `click` in the `LogInAsAdminTest` test (in the `.../Backend/Test/LogInAsAdminTest.xml` file)
+*  `checkOption` before `click` (`stepKey="clickLogin"`)
+*  `seeInCurrentUrl` after `click` in the `LogInAsAdminTest` test (in the `.../Backend/Test/LogInAsAdminTest.xml` file)
 
 > Tests with "extends":
 
@@ -366,4 +366,4 @@ __Use case__: Create an entity named `DivPanelGreen`, which is similar to the `D
 [test]: ./test.md
 [data]: ./data.md
 [action group]: ./test/action-groups.md
-[actions]: ./test/actions.md
+[actions]: ./test/actions.md

docs/getting-started.md

@@ -10,10 +10,10 @@ The latest Magento 2.2 release supports MFTF 2.3.8.
 
 Make sure that you have the following software installed and configured on your development environment:
 
-- [PHP version supported by the Magento instance under test][php]
-- [Composer 1.3 or later][composer]
-- [Java 1.8 or later][java]
-- [Selenium Server Standalone 3.1 or later][selenium server] and [ChromeDriver 2.33 or later][chrome driver] or other webdriver in the same directory
+-  [PHP version supported by the Magento instance under test][php]
+-  [Composer 1.3 or later][composer]
+-  [Java 1.8 or later][java]
+-  [Selenium Server Standalone 3.1 or later][selenium server] and [ChromeDriver 2.33 or later][chrome driver] or other webdriver in the same directory
 
 <div class="bs-callout bs-callout-tip" markdown="1">
 [PhpStorm] supports [Codeception test execution][], which is helpful when debugging.
@@ -147,16 +147,16 @@ vim dev/tests/acceptance/.env
 
 Specify the following parameters, which are required to launch tests:
 
-- `MAGENTO_BASE_URL` must contain a domain name of the Magento instance that will be tested.
+-  `MAGENTO_BASE_URL` must contain a domain name of the Magento instance that will be tested.
   Example: `MAGENTO_BASE_URL=http://magento.test`
 
-- `MAGENTO_BACKEND_NAME` must contain the relative path for the Admin area.
+-  `MAGENTO_BACKEND_NAME` must contain the relative path for the Admin area.
   Example: `MAGENTO_BACKEND_NAME=admin`
 
-- `MAGENTO_ADMIN_USERNAME` must contain the username required for authorization in the Admin area.
+-  `MAGENTO_ADMIN_USERNAME` must contain the username required for authorization in the Admin area.
   Example: `MAGENTO_ADMIN_USERNAME=admin`
 
-- `MAGENTO_ADMIN_PASSWORD` must contain the user password required for authorization in the Admin area.
+-  `MAGENTO_ADMIN_PASSWORD` must contain the user password required for authorization in the Admin area.
   Example: `MAGENTO_ADMIN_PASSWORD=123123q`
 
 <div class="bs-callout bs-callout-info" markdown="1">
@@ -222,8 +222,8 @@ During testing, the MFTF generates test reports in CLI.
 You can generate visual representations of the report data using [Allure Framework][].
 To view the reports in GUI:
 
-- [Install Allure][]
-- Run the tool to serve the artifacts in `dev/tests/acceptance/tests/_output/allure-results/`:
+-  [Install Allure][]
+-  Run the tool to serve the artifacts in `dev/tests/acceptance/tests/_output/allure-results/`:
 
 ```bash
 allure serve dev/tests/acceptance/tests/_output/allure-results/

docs/img/catalogCategoryRepository-operations.png

@@ -5,11 +5,11 @@
 The Magento Functional Testing Framework (MFTF) aims to replace the [Functional Testing Framework] in future releases.
 MFTF improves:
 
-- **Traceability** for clear logging and reporting capabilities.
-- **Modularity** to run tests based on installed modules and extensions.
-- **Customizability** for existing tests.
-- **Readability** using clear and declarative XML test steps.
-- **Maintainability** based on simple test creation and overall structure.
+-  **Traceability** for clear logging and reporting capabilities.
+-  **Modularity** to run tests based on installed modules and extensions.
+-  **Customizability** for existing tests.
+-  **Readability** using clear and declarative XML test steps.
+-  **Maintainability** based on simple test creation and overall structure.
 
 Because MFTF tests are written in XML, you no longer need to learn PHP to write tests.
 
@@ -27,17 +27,17 @@ This MFTF guide is intended for Magento developers and software engineers, such
 
 The purpose of MFTF is to:
 
-- Facilitate functional testing and minimize the effort it takes to perform regression testing.
-- Make it easier to support the extension and customization of tests via XML merging.
+-  Facilitate functional testing and minimize the effort it takes to perform regression testing.
+-  Make it easier to support the extension and customization of tests via XML merging.
 
 ## Scope
 
 MFTF will enable you to:
 
-- Test user interactions with web applications in testing.
-- Write functional tests located in `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/`.
-- Cover basic functionality using out-of-the-box tests. You can test extended functionality using custom tests.
-- Automate regression testing.
+-  Test user interactions with web applications in testing.
+-  Write functional tests located in `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/`.
+-  Cover basic functionality using out-of-the-box tests. You can test extended functionality using custom tests.
+-  Automate regression testing.
 
 ## Use cases
 
@@ -49,8 +49,8 @@ As a software engineer, perform regression testing before release to ensure that
 
 There are two options to find out your MFTF version:
 
-- using the MFTF CLI
-- using the Composer CLI
+-  using the MFTF CLI
+-  using the Composer CLI
 
 ### MFTF CLI
 
@@ -91,18 +91,18 @@ codeception.dist.yml            // Codeception configuration (generated while ru
 
 ## MFTF output
 
-- Generated PHP Codeception tests
-- Codeception results and console logs
-- Screenshots and HTML failure report
-- Allure formatted XML results
-- Allure report dashboard of results
+-  Generated PHP Codeception tests
+-  Codeception results and console logs
+-  Screenshots and HTML failure report
+-  Allure formatted XML results
+-  Allure report dashboard of results
 
 ## MFTF tests
 
 The MFTF supports two different locations for storing the tests and test artifacts:
 
-- `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/` is the directory to create new tests.
-- `<magento_root>/vendor/<vendor_name>/<module_name>/Test/Mftf/` is the directory with the out of the box tests (fetched by the Composer).
+-  `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/` is the directory to create new tests.
+-  `<magento_root>/vendor/<vendor_name>/<module_name>/Test/Mftf/` is the directory with the out of the box tests (fetched by the Composer).
 
 All tests and test data from these locations are merged in the order indicated in the above list.
 
@@ -133,4 +133,4 @@ Follow the [MFTF project] and [contribute on Github].
 [Functional Testing Framework]: https://devdocs.magento.com/guides/v2.3/mtf/mtf_introduction.html
 [MFTF project]: https://github.com/magento/magento2-functional-testing-framework
 [Find your MFTF version]: #find-your-mftf-version
-[MFTF Test Migration]: https://github.com/magento/magento-functional-tests-migration
+[MFTF Test Migration]: https://github.com/magento/magento-functional-tests-migration

docs/img/issue.png

@@ -2,11 +2,11 @@
 
 The MFTF allows you to merge test components defined in XML files, such as:
 
-- [`<tests>`][]
-- [`<pages>`][]
-- [`<sections>`][]
-- [`<data>`][]
-- `<action groups>`
+-  [`<tests>`][]
+-  [`<pages>`][]
+-  [`<sections>`][]
+-  [`<data>`][]
+-  `<action groups>`
 
 You can create, delete, or update the component.
 It is useful for supporting rapid test creation for extensions and customizations.
@@ -18,11 +18,11 @@ Your update (XML node with changes) must have the same attribute `name` as its b
 
 For example:
 
-- All tests with `<test name="SampleTest>` will be merged into one.
-- All pages with `<page name="SamplePage>` will be merged into one.
-- All sections with `<section name="SampleAction">` will be merged into one.
-- All data entities with `<entity name="sampleData" type="sample">` will be merged into one.
-- All action groups with `<actionGroup name="selectNotLoggedInCustomerGroup">` will be merged into one.
+-  All tests with `<test name="SampleTest>` will be merged into one.
+-  All pages with `<page name="SamplePage>` will be merged into one.
+-  All sections with `<section name="SampleAction">` will be merged into one.
+-  All data entities with `<entity name="sampleData" type="sample">` will be merged into one.
+-  All action groups with `<actionGroup name="selectNotLoggedInCustomerGroup">` will be merged into one.
 
 Although a file name does not influence merging, we recommend using the same file names in merging updates.
 This makes it easier to search later on.