Formatting

Author: dobooth

docs/guides/using-suites.md

@@ -1,24 +1,24 @@
 # Using suites
 
-With increasing number of MFTF tests, it's important to have a mechanism to organize and consolidate them for ease-of-use.
+With an increasing number of MFTF tests, it is important to have a mechanism to organize and consolidate them for ease-of-use.
 
 ### What is a suite?
 
-Suite is a collection of MFTF tests that are intended to test specific behaviors of Magento. It may contain common initialization and clean up steps specific to the test cases included. It allows you to include, exclude and/or group tests with preconditions and post conditions.
+A suite is a collection of MFTF tests that are intended to test specific behaviors of Magento. It may contain initialization and clean up steps common to the included test cases. It allows you to include, exclude and/or group tests with preconditions and post conditions.
 You can create a suite referencing tests, test groups and modules.
 
 ### How is a suite defined?
 
-A suite should be created under `<magento 2 root>/dev/tests/acceptance/tests/_suite` if it has cross-module references. If a suite references only a specific module, it should be created under `<module>/Test/Mftf/Suite`. The generated tests for each suite are grouped into their own directory under `<magento 2 root>/dev/tests/acceptance/tests/functional/Magento/FunctionalTest/_generated/`.
+A suite should be created under `<magento2 root>/dev/tests/acceptance/tests/_suite` if it has cross-module references. If a suite references only a single module, it should be created under `<module>/Test/Mftf/Suite`. The generated tests for each suite are grouped into their own directory under `<magento2 root>/dev/tests/acceptance/tests/functional/Magento/FunctionalTest/_generated/`.
 
 ### What is the format of a suite?
 
-A suite comprises of the below blocks:
+A suite is comprised of blocks:
 
-* `<before>` : executes precondition once per suite run.
-* `<after>`  : executes postcondition once per suite run.
-* `<include>`: includes specific tests/groups/modules in the suite.
-* `<exclude>`: excludes specific tests/groups/modules from the suite.
+*  `<before>` : executes precondition once per suite run.
+*  `<after>`  : executes postcondition once per suite run.
+*  `<include>`: includes specific tests/groups/modules in the suite.
+*  `<exclude>`: excludes specific tests/groups/modules from the suite.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -65,34 +65,37 @@ A suite comprises of the below blocks:
 ```
 
 This example declares a suite with name `WYSIWYGDisabledSuite`:
-* Disables WYSIWYG of the Magento instance before running the tests.
-* Runs all tests from `Catalog` module, except `WYSIWYGIncompatibleTest`
-* Returns the Magento instance back to it's original state by enabling WYSIWYG at the end of testing.
+
+*  Disables WYSIWYG of the Magento instance before running the tests.
+*  Runs all tests from the `Catalog` module, except `WYSIWYGIncompatibleTest`
+*  Returns the Magento instance back to its original state, by enabling WYSIWYG at the end of testing.
 
 ### Using MFTF suite commands
 
-* Generate all tests within a suite.
-```bash
-  vendor/bin/mftf generate:suite <suiteName> [<suiteName>]
-```
-* Run all tests within suite.
-```bash
-  vendor/bin/mftf run:group <suiteName> [<suiteName>]
-```
-* Generates any combination of suites and tests.
-```bash
-  vendor/bin/mftf generate:tests --tests '{"tests":["testName1","testName2"],"suites":{"suite1":["suite_test1"],"suite2":null}}'
-```
+*  Generate all tests within a suite.
+
+    ```bash
+    vendor/bin/mftf generate:suite <suiteName> [<suiteName>]
+    ```
+*  Run all tests within suite.
+
+    ```bash
+    vendor/bin/mftf run:group <suiteName> [<suiteName>]
+    ```
+*  Generates any combination of suites and tests.
+
+    ```bash
+    vendor/bin/mftf generate:tests --tests '{"tests":["testName1","testName2"],"suites":{"suite1":["suite_test1"],"suite2":null}}'
+    ```
 
-### How to run specific tests within a suite?
+### Run specific tests within a suite
+
+If a test is referenced in a suite, it can be run in the suite's context with MFTF `run` command. If a test is referenced in multiple suites, the `run` command will run the test multiple times in all contexts.
 
-If a test is referenced in a suite, it can be run in the suite's context with MFTF run command. If a test is referenced in multiple suites, the run command will run the test multiple times in all contexts.
 ```bash
-  vendor/bin/mftf run:test <testName> [<testName>]
+vendor/bin/mftf run:test <testName> [<testName>]
 ```  
 
 ### When to use suites?
 
-Suites are a great way to organize tests which need magento environment to be configured in a specific way as a pre-requisite. The conditions are executed once per suite which optimizes test execution time. If you wish to categorize tests solely based on functionality, use group tags instead.
-
-<!-- Link definitions -->
+Suites are a great way to organize tests which need the Magento environment to be configured in a specific way as a pre-requisite. The conditions are executed once per suite which optimizes test execution time. If you wish to categorize tests solely based on functionality, use group tags instead.