Merge branch 'pr625' into lbajsarowicz-doc-rollup

Author: KevinBKozan

docs/introduction.md

@@ -1,73 +1,101 @@
 # Introduction to the Magento Functional Testing Framework
 
-[Find your MFTF version][] of the MFTF.
+The **Magento Functional Tesitng Framework** (MFTF) is framework to perform end-to-end acceptance testing. Tests are performed in real web browser (eg. Google Chrome) just like the real user of the Magento store.
 
-The Magento Functional Testing Framework (MFTF) aims to replace the [Functional Testing Framework] in future releases.
-MFTF improves:
+## Goals
 
--  **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.
+- Facilitate functional testing and minimize the effort it takes to perform regression testing.
+- Enable extension developers to provide the Functional Tests to offered extensions.
+- Having common standard of Quality Assurrance between Magento, Extension Developers and System Intergrators.
 
-Because MFTF tests are written in XML, you no longer need to learn PHP to write tests.
+**MFTF also focuses on**
 
-<div class="bs-callout bs-callout-info" markdown="1">
-We are actively developing functional tests.
-Refer to `<magento_root>/app/code/<vendor_name>/<module_name>/Test/Mftf/` for examples.
-Check out the [MFTF Test Migration][] repo.
-</div>
+- **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.
 
 ## Audience
 
-This MFTF guide is intended for Magento developers and software engineers, such as QA specialists, PHP developers, and system integrators.
+- **Contributors**: Tests build their confidence about the results of changes introduced to the platform.
+- **Extension Developers**: Can adjust expected behaviour according to their customizations.
+- **System Integrators**: MFTF coverage provided out-of-the-box with Magento is solid base for Acceptance / Regression Tests.
 
-## Goals
+## 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 location of local, customized tests.
+-  `<magento_root>/vendor/<vendor_name>/<module_name>/Test/Mftf/` is location of tests provided by Magento and vendors.
+
+If you installed Magento with Composer, please refer to `vendor/magento/<module_dir>/Test/Mftf/` for examples.
+
+### Directory Structure
 
-The purpose of MFTF is to:
+The file structure under both of the both path cases is the same:
 
--  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.
+```tree
+Test
+└── Mftf
+    ├── ActionGroup
+    │   └── ...
+    ├── Data
+    │   └── ...
+    ├── Metadata
+    │   └── ...
+    ├── Page
+    │   └── ...
+    ├── Section
+    │   └── ...
+    └── Test
+        └── ...
+```
 
-## Scope
 
-MFTF will enable you to:
+<div class="bs-callout bs-callout-info" markdown="1">
 
--  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.
+We are actively developing functional tests. Check out the [MFTF Test Migration][] repository.
+
+</div>
 
 ## Use cases
 
-As a Magento developer, test changes, such as extended search functionality, a new form attribute, or new product tags.
+* **Contributor** changes the core behaviour, fixing the annoing bug.
+  He wants to have automated "supervisor" which is going to verify his work continuously across the stages of bug fixing. Finally, when fix is done - Functional Test is also proof of work done.
 
-As a software engineer, perform regression testing before release to ensure that Magento works as expected with new functionality.
+* **Extension Developer** offers extension that changes core behaviour.
+  He can easily write new tests to make sure that after enabling the feature, Magento behaves properly. Everything with just extending existing tests. As a result he don't need to write coverage from scratch.
+  
+* **Integration Agency** maintains Client's e-commerce.
+  They are able to customize tests delivered with Magento core to follow customizations implemented to Magento. After each upgrade they can just run the MFTF tests to know that no regression was introduced.
+
+
+## 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
 
 ## Find your MFTF version
 
 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
+All the Command Line commands needs to be executed from `<magento_root>`
 
-```bash
-cd <magento_root>/
-```
+### MFTF CLI
 
 ```bash
 vendor/bin/mftf --version
 ```
 
 ### Composer CLI
 
-```bash
-cd <magento_root>/
-```
-
 ```bash
 composer show magento/magento2-functional-testing-framework
 ```
@@ -89,41 +117,6 @@ utils                           // The test-running utilities.
 codeception.dist.yml            // Codeception configuration (generated while running 'bin/mftf build:project')
 ```
 
-## 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
-
-## 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).
-
-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:
-
-```tree
-<Path>
-├── ActionGroup
-│   └── ...
-├── Data
-│   └── ...
-├── Metadata
-│   └── ...
-├── Page
-│   └── ...
-├── Section
-│   └── ...
-└── Test
-    └── ...
-```
-
 ## MFTF on Github
 
 Follow the [MFTF project] and [contribute on Github].