Merge branch 'pr628' into lbajsarowicz-doc-rollup

Author: KevinBKozan

docs/best-practices.md

@@ -2,11 +2,46 @@
 
 Check out our best practices below to ensure you are getting the absolute most out of the Magento Functional Testing Framework.
 
+## Focus on reusability
+
+### 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.
+
+**Resources you can reuse**
+
+* 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.
+
+</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. 
+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.
+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.
+
 ## Action group
 
-1. [Action group] names should be sufficiently descriptive to inform a test writer of what the action group does and when it should be used.
- Add additional explanation in annotations if needed.
-2. Provide default values for the arguments that apply to your most common case scenarios.
+1. [Action group] names should be sufficiently descriptive to inform a test writer of what the action group does and when it should be used. Add additional explanation in annotations if needed.
+1. Provide default values for the arguments that apply to your most common case scenarios.
 
 ## `actionGroups` vs `extends`
 
@@ -175,3 +210,4 @@ Since the configurable product module could be disabled, this approach is more r
 [merging]: merging.html
 [parameterized selectors]: section/parameterized-selectors.html
 [sections]: section.html
+[MFTF Test Migration]: https://github.com/magento/magento-functional-tests-migration