Editorial pass

Author: dobooth

docs/best-practices.md

@@ -7,36 +7,36 @@ Check out our best practices below to ensure you are getting the absolute most o
 ### Use existing Tests and resources
 
 Magento offers more than **3000** acceptance tests, **2500** [Action group]s, **750** Page declarations with more than **1500** Section definitions.
-It is very probable that behaviour you want to test already exists as other Test or Action Group.
-Instead of writing everything by yourself - try to use `extends` attribute to refer to existing element and customize it.
+It is very probable that behaviour you want to test already exists as a Test or Action Group.
+Instead of writing everything by yourself - use `extends` attribute to refer to existing element and customize it.
 
-**Resources you can reuse**
+**Reusable Resources**
 
-* Tests (reusable with `<test extends="...">` argument)
-* Action Group (reusable with including `<actionGroup ref="...">`, or extending `<actionGroup extends="...">`)
-* Pages (reusable with reference `{{PageDefinition.url}}`)
-* Sections (reusable with reference `{{SectionDefinition.elementDefinition}}`)
-* Data Entities (reusable with reference `<createData entity="...">"` or extending `<entity extends="...">`)
+*  Tests (reusable with `<test extends="...">` argument)
+*  Action Group (reusable with including `<actionGroup ref="...">`, or extending `<actionGroup extends="...">`)
+*  Pages (reusable with reference `{{PageDefinition.url}}`)
+*  Sections (reusable with reference `{{SectionDefinition.elementDefinition}}`)
+*  Data Entities (reusable with reference `<createData entity="...">"` or extending `<entity extends="...">`)
 
 <div class="bs-callout bs-callout-warning" markdown="1">
 
-Avoid using resources that are marked as **Deprecated**. Usually there's a replacement provided for deprecated resource.
+Avoid using resources that are marked as **Deprecated**. Usually there is a replacement provided for a deprecated resource.
 
 </div>
 
 ### Extract repetitive Actions
 
-Instead of writing a few of Tests that perform mostly the same actions, you should thing about [Action group] that is a container for repetitive Actions. 
+Instead of writing a few of Tests that perform mostly the same actions, you should thing about [Action group] that is a container for repetitive Actions.
 If each run needs different data, use `<arguments>` to inject necessary information.
 
 We recommend to keep Action Groups having single responsibility, for example `AdminLoginActionGroup`, which expected outcome is being logged in as Administrator when [Action group] is executed.
 
 ## Contribute
 
-Althought Magento Core team and Contributors join their forces to cover most of the features with tests, it's impossible to have this done that quick.
+Althought the Magento Core team and Contributors join forces to cover most of the features with tests, it is impossible to have this done quickly.
 If you've covered Magento Core feature with Functional Tests - you are more than welcome to contribute.
 
-You can also help with [MFTF Test Migration] to get the experience and valuable feedback from other community members and maintainers.
+You can also help with MFTF Test Migration to get the experience and valuable feedback from other community members and maintainers.
 
 ## Action group
 
@@ -129,20 +129,20 @@ 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"/>`
--  Step keys. For example: `<click selector="..." stepKey="clickLogin"/>`
+*  Data keys. Example: `<data key="firstName">`
+*  Element names. Examples: `<element name="confirmDeleteButton"/>`
+*  Step keys. For example: `<click selector="..." stepKey="clickLogin"/>`
 
 ## Page object
 
@@ -180,9 +180,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/configuration.md

@@ -34,7 +34,7 @@ MAGENTO_BACKEND_NAME=admin_12346
 
 ### MAGENTO_BACKEND_BASE_URL
 
-(Optional) If you are running Admin Panel on separate domain, you may need to specify this value:
+(Optional) If you are running the Admin Panel on separate a domain, specify this value:
 
 Example:
 

docs/introduction.md

@@ -1,26 +1,26 @@
 # Introduction to the Magento Functional Testing Framework
 
-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 Tesitng Framework (MFTF) is a framework used to perform automated end-to-end functional testing.
 
 ## Goals
 
-- 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.
+-  To facilitate functional testing and minimize the effort it takes to perform regression testing.
+-  Enable extension developers to provide the Functional Tests to offered extensions.
+-  Ensuring a common standard of quality between Magento, Extension Developers and System Intergrators.
 
-**MFTF also focuses on**
+MFTF also focuses on
 
-- **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.
 
 ## Audience
 
-- **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.
+-  **Contributors**: Tests build 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.
 
 ## MFTF tests
 
@@ -52,7 +52,6 @@ Test
         └── ...
 ```
 
-
 <div class="bs-callout bs-callout-info" markdown="1">
 
 We are actively developing functional tests. Check out the [MFTF Test Migration][] repository.
@@ -61,30 +60,27 @@ We are actively developing functional tests. Check out the [MFTF Test Migration]
 
 ## Use cases
 
-* **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.
-
-* **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.
-
+-  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.
+-  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
+-  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
 
 All the Command Line commands needs to be executed from `<magento_root>`
 

docs/update.md

@@ -1,20 +1,15 @@
 # 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).
-
 </div>
 
+Tests and the Framework itself are stored in different repositories.
 
-**Tests and the Framework itself are stored in different repositories.**
-
-* Tests are stored in Module's directory.
-* The MFTF is installed separately (usually as a Composer dependency)
-
-While pulling the latest Magento codebase, you are going to get Tests and it's dependencies (eg. Action Groups).
+*  Tests are stored in Module's directory.
+*  MFTF is installed separately (usually as a Composer dependency)
 
-To understand types of update - please follow the [Versioning][] page. 
+To understand different types of update - please follow the [Versioning][] page.
 
 ## Patch version update
 
@@ -33,11 +28,11 @@ Takes place when **second** digit of version number changes.
 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`
 
-## Always after update
+## After updating
 
-1. It's good to regenerate your IDE Schema Definition catalog with `vendor/bin/mftf generate:urn-catalog .idea/`
-1. Update your own tests, including data, metadata and other resoruces. Validate if they contain tags that are unsupported in the newer version.
-1. As soon as possible - remove the references to resources (ActionGroups, Sections, Tests) marked as deprecated.
+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. 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