Merge pull request #633 from magento/MQE-2028

MQE-2028: DevDoc & MFTF Notice for MFTF 3.0.0 specific upgrade instructions

Author: KevinBKozan

CHANGELOG.md

@@ -1,5 +1,18 @@
 Magento Functional Testing Framework Changelog
 ================================================
+3.0.0
+-----
+### Upgrade Instructions
+* Run `bin/mftf reset --hard` to remove old generated configurations.
+* Run `bin/mftf build:project` to generate new configurations.
+* Run `bin/mftf upgrade:tests`. [See command page for details](./docs/commands/mftf.md#upgradetests).
+* After running the above command, some tests may need manually updates:
+    * Remove all occurrences of `<executeInSelenium>` and `<performOn>`
+    * Remove all occurrences of `<module file=""/>` from any `<suite>`s
+    * Ensure all `<assert*>` actions in your tests have a valid schema.
+* Lastly, try to generate all tests. Tests should all be generated as a result of the upgrades.
+    * If not, the most likely issue will be a changed XML schema. Check error messaging and search your codebase for the attributes listed.
+
 2.6.3
 -----
 

docs/commands/mftf.md

@@ -477,6 +477,10 @@ Otherwise, it will apply all the major version MFTF upgrade scripts to all insta
 
 `Test Module` should have the directory structure of ActionGroup, Data, Metadata, Page, Section, Test, and Suite.
 
+**Note**:
+
+The upgrade scripts are meant to be used for Test Modules under source code control. If you have old versions of test modules under vendor, those test modules will get upgraded
+
 #### Usage
 
 ```bash

docs/guides/git-vs-composer-install.md

@@ -55,6 +55,8 @@ The file structure under both paths is the same:
 │   └── ...
 ├── Section
 │   └── ...
+├── Suite
+│   └── ...
 └── Test
     └── ...
 ```
@@ -65,6 +67,7 @@ With either type of installation, all tests and test data are read and merged by
 
 1. `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/`
 1. `<magento_root>/vendor/<vendor_name>/<module_name>/Test/Mftf/`
+1. `<magento_root>/dev/tests/acceptance/tests/functional/<vendor_name>/<module_name>/`
 
 ## Conclusion
 

docs/introduction.md

@@ -1,5 +1,10 @@
 # Introduction to the Magento Functional Testing Framework
 
+<div class="bs-callout bs-callout-info" markdown="1">
+These are the docs for the latest MFTF release.
+To find older documentation, please refer to the [docs folder] of your desired release in Github.
+</div>
+
 [Find your MFTF version][] of the MFTF.
 
 The Magento Functional Testing Framework (MFTF) aims to replace the [Functional Testing Framework] in future releases.
@@ -99,14 +104,14 @@ codeception.dist.yml            // Codeception configuration (generated while ru
 
 ## MFTF tests
 
-The MFTF supports two different locations for storing the tests and test artifacts:
-
+The MFTF supports three 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>/dev/tests/acceptance/tests/functional/<vendor_name>/<module_name>/` is used to store tests that depend on multiple modules.
 
 All tests and test data from these locations are merged in the order indicated in the above list.
 
-The file structure under the both path cases is the same:
+Directories immediately following the above paths will use the same format, and sub-directories under each category are supported.
 
 ```tree
 <Path>
@@ -120,6 +125,8 @@ The file structure under the both path cases is the same:
 │   └── ...
 ├── Section
 │   └── ...
+├── Suite
+│   └── ...
 └── Test
     └── ...
 ```
@@ -134,3 +141,4 @@ Follow the [MFTF project] and [contribute on Github].
 [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
+[docs folder]: https://github.com/magento/magento2-functional-testing-framework/tree/master/docs