MQE-2219: Part 6 Docs Annual Review (#767)

* MQE-2219: Part 6 Docs Annual Review

* MQE-2219: Part 6 Docs Annual Review

* MQE-2219: Part 6 Docs Annual Review

Author: soumyau

docs/section.md

@@ -58,26 +58,26 @@ Example (`.../Catalog/Section/AdminCategorySidebarActionSection.xml` file):
 <?xml version="1.0" encoding="utf-8"?>
 
 <sections xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-      xsi:noNamespaceSchemaLocation="urn:magento:mftf:Page/etc/SectionObject.xsd">
-   <section name="AdminCategorySidebarActionSection">
-      <element name="addRootCategoryButton" type="button" selector="#add_root_category_button" timeout="30"/>
-      <element name="addSubcategoryButton" type="button" selector="#add_subcategory_button" timeout="30"/>
-   </section>
+        xsi:noNamespaceSchemaLocation="urn:magento:mftf:Page/etc/SectionObject.xsd">
+    <section name="AdminCategorySidebarActionSection">
+        <element name="AddRootCategoryButton" type="button" selector="#add_root_category_button" timeout="30"/>
+        <element name="AddSubcategoryButton" type="button" selector="#add_subcategory_button" timeout="30"/>
+    </section>
 </sections>
 ```
 
 This example uses a `AdminCategorySidebarActionSection` section. All sections with same name will be merged during test generation.
 
 The `AdminCategorySidebarActionSection` section declares two buttons:
 
--  `addRootCategoryButton` - button with a `#add_root_category_button` locator on the parent web page
--  `addSubcategoryButton` - button with a `#add_subcategory_button` locator on the parent web page
+-  `AddRootCategoryButton` - button with a `#add_root_category_button` locator on the parent web page
+-  `AddSubcategoryButton` - button with a `#add_subcategory_button` locator on the parent web page
 
 The following is an example of a call in test:
 
 ```xml
 <!-- Click on the button with locator "#add_subcategory_button" on the web page-->
-<click selector="{{AdminCategorySidebarActionSection.addSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
+<click selector="{{AdminCategorySidebarActionSection.AddSubcategoryButton}}" stepKey="clickOnAddSubCategory"/>
 ```
 
 ## Elements reference
@@ -116,21 +116,21 @@ The most usual use case is a test step with a button click action.
 
 The section element code declaration containing the timeout attribute:
 
-> StorefrontSigninSection.xml
+> StorefrontCustomerSignInPopupFormSection.xml
 
 ```xml
 ...
-<element name="signIn" type="button" selector="#signIn" timeout="30"/>
+<element name="signIn" type="button" selector="#send2" timeout="30"/>
 ...
 ```
 
 The test step that covers the use case:
 
-> StorefrontSigninTest.xml
+> CaptchaWithDisabledGuestCheckoutTest.xml
 
 ```xml
 ...
-<click selector="{{StorefrontSigninSection.signIn}}" ../>
+<click selector="{{StorefrontCustomerSignInPopupFormSection.signIn}}" stepKey="clickSignIn"/>
 ...
 ```
 

docs/section/locator-functions.md

@@ -31,7 +31,7 @@ An element cannot, however, have both a `selector` and a `locatorFunction`.
 Given the above element definitions, you call the elements in a test just like any other element. No special reference is required, as you are still just referring to an `element` inside a `section`:
 
 ```xml
-<test name="LocatorFuctionTest">
+<test name="LocatorFunctionTest">
    <click selector="{{LocatorFunctionSection.simpleLocator}}" stepKey="SimpleLocator"/>
    <click selector="{{LocatorFunctionSection.simpleLocatorTwoParam('string1', 'string2')}}" stepKey="TwoParamLiteral"/>
 </test>

docs/suite.md

@@ -6,8 +6,8 @@ You can form suites using separate tests, groups, and modules.
 
 Each suite must be defined in the `<VendorName>/<ModuleName>/Test/Mftf/Suite` directory.
 
-The tests for each suite are generated in a separate directory under `<magento 2 root>/dev/tests/acceptance/tests/functional/Magento/FunctionalTest/_generated/`.
-All tests that are not within a suite are generated in the _default_ suite at `.../Magento/FunctionalTest/_generated/default/`.
+The tests for each suite are generated in a separate directory under `<magento 2 root>/dev/tests/acceptance/tests/functional/Magento/_generated/`.
+All tests that are not within a suite are generated in the _default_ suite at `<magento 2 root>/dev/tests/acceptance/tests/functional/Magento/_generated/default`.
 
 <div class="bs-callout bs-callout-info">
  If a test is generated into at least one custom suite, it will not appear in the _default_ suite.
@@ -61,7 +61,7 @@ The code lives in one place and executes once per suite.
 
 -  Set up preconditions and postconditions using [actions] in [`<before>`] and [`<after>`] correspondingly, just similar to use in a [test].
 -  Clean up after suites just like after tests.
-  The MFTF enforces the presence of both `<before>` and `<after>` if either is present.
+MFTF enforces the presence of both `<before>` and `<after>` if either is present.
 
 ## Test writing
 
@@ -142,7 +142,7 @@ This suite includes all tests that contain the `<group value="WYSIWYG"/>` annota
 ### Execute Magento CLI commands in suite conditions
 
 ```xml
-<suites xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../dev/tests/acceptance/vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Suite/etc/suiteSchema.xsd">
+<suites xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:mftf:Suite/etc/suiteSchema.xsd">
     <suite name="Cache">
         <before>
             <magentoCLI stepKey="disableCache" command="cache:disable"/>
@@ -170,7 +170,7 @@ The suite includes a specific test `SomeCacheRelatedTest` and every `<test>` tha
 ### Change Magento configurations in suite conditions
 
 ```xml
-<suites xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../dev/tests/acceptance/vendor/magento/magento2-functional-testing-framework/src/Magento/FunctionalTestingFramework/Suite/etc/suiteSchema.xsd">
+<suites xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:mftf:Suite/etc/suiteSchema.xsd">
     <suite name="PaypalConfiguration">
         <before>
             <createData entity="SamplePaypalConfig" stepKey="createSamplePaypalConfig"/>

docs/update.md

@@ -1,7 +1,9 @@
 # Update the Magento Functional Testing Framework
 
 <div class="bs-callout bs-callout-info" markdown="1">
-Both Magento `2.2` and `2.3` supports MFTF `2.5.3` ([Find your version][] of the MFTF).
+[Find your version] of MFTF.
+The latest Magento 2.4.x release supports MFTF 3.x.
+The latest Magento 2.3.x release supports MFTF 2.6.x.
 </div>
 
 Tests and the Framework itself are stored in different repositories.
@@ -26,16 +28,24 @@ Takes place when **second** digit of version number changes.
 1. Check details about backward incompatible changes in the [Changelog][] and update your new or customized tests.
 1. Perform all the actions provided for [Patch Version Update][]
 1. When updating from versions below `2.5.0`, verify [WYSIWYG settings][]
-1. You may need to run the `upgrade:tests` using `vendor/bin/mftf upgrade:tests app`
+1. You may need to run the `upgrade:tests` using `vendor/bin/mftf upgrade:tests`
+
+## Major version update
+
+Takes place when **first** digit of version number changes.
+
+1. Check detailed explanation and instructions on major version upgrade in [Backward Incompatible Changes][] and upgrade your new or customized tests.
+1. Perform all the actions provided for [Minor Version Update][]
 
 ## After updating
 
 1. It is a good idea to regenerate your IDE Schema Definition catalog with `vendor/bin/mftf generate:urn-catalog .idea/`
-1. Update your tests, including data, metadata and other resoruces. Check if they contain tags that are unsupported in the newer version.
+1. Update your tests, including data, metadata and other resources. Check if they contain tags that are unsupported in the newer version.
 1. Remove the references to resources (ActionGroups, Sections, Tests) marked as deprecated.
 
 <!-- Link Definitions -->
 [Changelog]: https://github.com/magento/magento2-functional-testing-framework/blob/master/CHANGELOG.md
+[Backward Incompatible Changes]: backward-incompatible-changes.md
 [WYSIWYG settings]: getting-started.md#wysiwyg-settings
 [Security settings]: getting-started.md#security-settings
 [Find your version]: introduction.md#find-your-mftf-version