MQE-2214: Part 1 Docs Annual Review

Author: tomreece

docs/configuration.md

@@ -1,12 +1,12 @@
 # Configuration
 
 The `*.env` file provides additional configuration for the Magento Functional Testing Framework (MFTF).
-To run the MFTF on your Magento instance, specify the basic configuration values.
+To run MFTF on your Magento instance, specify the basic configuration values.
 Advanced users can create custom configurations based on requirements and environment.
 
 ## Basic configuration
 
-These basic configuration values are __required__ and must be set by the user before the MFTF can function correctly.
+These basic configuration values are __required__ and must be set by the user before MFTF can function correctly.
 
 ### MAGENTO_BASE_URL
 
@@ -34,7 +34,7 @@ MAGENTO_BACKEND_NAME=admin_12346
 
 ### MAGENTO_BACKEND_BASE_URL
 
-(Optional) If you are running the Admin Panel on separate a domain, specify this value:
+(Optional) If you are running the Admin Panel on a separate domain, specify this value:
 
 Example:
 
@@ -64,7 +64,7 @@ MAGENTO_ADMIN_PASSWORD=1234reTyt%$7
 
 ## Advanced configuration
 
-Depending on the environment you use, you may need to configure the MFTF more precisely by setting more configuration parameters then for basic configuration.
+Depending on the environment you use, you may need to configure MFTF more precisely by setting additional configuration parameters.
 This section describes available configuration parameters and their default values (where applicable).
 
 ### DEFAULT_TIMEZONE
@@ -173,8 +173,8 @@ MAGENTO_RESTAPI_SERVER_PORT=5000
 ### \*_BP
 
 Settings to override base paths for the framework.
-You can use it when the MFTF is applied as a separate tool.
-For example, when you need to place the MFTF and the Magento codebase in separate projects.
+You can use it when MFTF is applied as a separate tool.
+For example, when you need to place MFTF and the Magento codebase in separate projects.
 
 ```conf
 MAGENTO_BP
@@ -227,7 +227,7 @@ TESTS_MODULE_PATH=~/magento2/dev/tests/acceptance/tests/functional/Magento/Funct
 ### MODULE_ALLOWLIST
 
 Use for a new module.
-When adding a new directory at `Magento/FunctionalTest`, add the directory name to `MODULE_ALLOWLIST` to enable the MFTF to process it.
+When adding a new directory at `Magento/FunctionalTest`, add the directory name to `MODULE_ALLOWLIST` to enable MFTF to process it.
 
 Example:
 
@@ -245,7 +245,7 @@ It points to `MAGENTO_BASE_URL` + `dev/tests/acceptance/utils/command.php`
 Modify the default value:
 
 -  for non-default Magento installation
--  when use a subdirectory in the `MAGENTO_BASE_URL`
+-  when using a subdirectory in the `MAGENTO_BASE_URL`
 
 Example: `dev/tests/acceptance/utils/command.php`
 

docs/credentials.md

@@ -3,20 +3,20 @@
 When you test functionality that involves external services such as UPS, FedEx, PayPal, or SignifyD,
 use the MFTF credentials feature to hide sensitive [data][] like integration tokens and API keys.
 
-Currently the MFTF supports three types of credential storage:
+Currently MFTF supports three types of credential storage:
 
 -  **.credentials file**
 -  **HashiCorp Vault**
 -  **AWS Secrets Manager**
 
 ## Configure File Storage
 
-The MFTF creates a sample file for credentials during [initial setup][]: `magento2/dev/tests/acceptance/.credentials.example`.
+MFTF creates a sample file for credentials during [initial setup][]: `magento2/dev/tests/acceptance/.credentials.example`.
 The file contains an example list of keys for fields that can require credentials.
 
 ### Create `.credentials`
 
-To make the MFTF process the file with credentials, in the command line, navigate to `magento2/dev/tests/acceptance/` and rename `.credentials.example` to `.credentials`.
+To make MFTF process the file with credentials, in the command line, navigate to `magento2/dev/tests/acceptance/` and rename `.credentials.example` to `.credentials`.
 
 ```bash
 cd dev/tests/acceptance/
@@ -78,7 +78,7 @@ vendor/my_awesome_service_token=rRVSVnh3cbDsVG39oTMz4A
 Hashicorp vault secures, stores, and tightly controls access to data in modern computing.
 It provides advanced data protection for your testing credentials.
 
-The MFTF works with both `vault enterprise` and `vault open source` that use `KV Version 2` secret engine.
+MFTF works with both `vault enterprise` and `vault open source` that use `KV Version 2` secret engine.
 
 ### Install vault CLI
 
@@ -92,11 +92,11 @@ Authenticate to vault server via the vault CLI tool: [Login Vault][Login Vault].
 vault login -method -path
 ```
 
-**Do not** use `-no-store` command option, as the MFTF will rely on the persisted token in the token helper (usually the local filesystem) for future API requests.
+**Do not** use `-no-store` command option, as MFTF will rely on the persisted token in the token helper (usually the local filesystem) for future API requests.
 
 ### Store secrets in vault
 
-The MFTF uses the `KV Version 2` secret engine for secret storage.
+MFTF uses the `KV Version 2` secret engine for secret storage.
 More information for working with `KV Version 2` can be found in [Vault KV2][Vault KV2].
 
 #### Secrets path and key convention
@@ -225,7 +225,7 @@ export CREDENTIAL_AWS_ACCOUNT_ID=<Your_12_Digits_AWS_Account_ID>
 ## Configure multiple credential storage
 
 It is possible and sometimes useful to setup and use multiple credential storage at the same time.
-In this case, the MFTF tests are able to read secret data at runtime from all storage options, in this case MFTF use the following precedence:
+In this case, the MFTF tests are able to read secret data at runtime from all storage options. MFTF will use the following precedence:
 
 ```
 .credentials File > HashiCorp Vault > AWS Secrets Manager
@@ -253,7 +253,7 @@ For example, to reference secret data in the [`fillField`][] action, use the `us
 ## Implementation details
 
 The generated tests do not contain credentials values.
-The MFTF dynamically retrieves, encrypts, and decrypts the sensitive data during test execution.
+MFTF dynamically retrieves, encrypts, and decrypts the sensitive data during test execution.
 Decrypted credentials do not appear in the console, error logs, or [test reports][].
 The decrypted values are only available in the `.credentials` file or within vault.
 
@@ -277,4 +277,4 @@ The MFTF tests delivered with Magento application do not use credentials and do
 [`CREDENTIAL_AWS_SECRETS_MANAGER_PROFILE`]: configuration.md#credential_aws_secrets_manager_profile
 [`CREDENTIAL_AWS_SECRETS_MANAGER_REGION`]: configuration.md#credential_aws_secrets_manager_region
 [Key Management Service]: https://aws.amazon.com/kms/
-[Amazon Resource Name]: https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html
+[Amazon Resource Name]: https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html

docs/data.md

@@ -1,6 +1,6 @@
 # Input testing data
 
-The MFTF enables you to specify and use `<data>` entities defined in XML. Default `<data>` entities are provided for use and as templates for entity creation and manipulation.
+MFTF enables you to specify and use `<data>` entities defined in XML. Default `<data>` entities are provided for use and as templates for entity creation and manipulation.
 The following diagram shows the XML structure of an MFTF data object:
 
 ![MFTF Data Object](img/data-dia.svg)
@@ -67,7 +67,7 @@ In this example:
 As of MFTF 2.3.6, you no longer need to differentiate between scopes (a test, a hook, or a suite) for persisted data when referencing it in tests.
 </div>
 
-The MFTF now stores the persisted data and attempts to retrieve it using the combination of `stepKey` and the scope of where it has been called.
+MFTF now stores the persisted data and attempts to retrieve it using the combination of `stepKey` and the scope of where it has been called.
 The current scope is preferred, then widening to _test > hook > suite_ or _hook > test > suite_.
 
 This emphasizes the practice for the `stepKey` of `createData` to be descriptive and unique, as a duplicated `stepKey` in both a `<test>` and `<before>` prefers the `<test>` data.

docs/extending.md

@@ -115,7 +115,7 @@ __Use case__: Create two similar tests where the second test contains two additi
 </tests>
 ```
 
-### Update a test annotation
+### Update a test before hook
 
 __Use case__: Create two similar tests where the second one contains two additional actions in the `before` hook:
 

docs/getting-started.md

@@ -1,9 +1,9 @@
 # Getting started
 
 <div class="bs-callout bs-callout-info" markdown="1">
-[Find your MFTF version][] of the MFTF.
-The latest Magento 2.3.x release supports MFTF 2.5.3.
-The latest Magento 2.2.x release supports MFTF 2.4.5.
+[Find your version] of MFTF.
+The latest Magento 2.3.x release supports MFTF 2.6.4.
+The latest Magento 2.2.x release supports MFTF 2.5.3.
 </div>
 
 ## Prepare environment {#prepare-environment}
@@ -64,7 +64,7 @@ A Selenium web driver cannot enter data to fields with WYSIWYG.
 To disable the WYSIWYG and enable the web driver to process these fields as simple text areas:
 
 1. Log in to the Magento Admin as an administrator.
-2. Navigate to **Stores** > Settings > **Configuration** > **General** > **Content Management**.
+2. Navigate to **Stores** > **Settings** > **Configuration** > **General** > **Content Management**.
 3. In the WYSIWYG Options section set the **Enable WYSIWYG Editor** option to **Disabled Completely**.
 4. Click **Save Config**.
 
@@ -88,7 +88,7 @@ When you want to test the WYSIWYG functionality, re-enable WYSIWYG in your test
 
 To enable the **Admin Account Sharing** setting, to avoid unpredictable logout during a testing session, and disable the **Add Secret Key in URLs** setting, to open pages using direct URLs:
 
-1. Navigate to **Stores** > Settings > **Configuration** > **Advanced** > **Admin** > **Security**.
+1. Navigate to **Stores** > **Settings** > **Configuration** > **Advanced** > **Admin** > **Security**.
 2. Set **Admin Account Sharing** to **Yes**.
 3. Set **Add Secret Key to URLs** to **No**.
 4. Click **Save Config**.
@@ -115,7 +115,7 @@ If the Magento instance under test has the [Magento Two-Factor Authentication (2
 
 ### Webserver configuration {#web-server-configuration}
 
-The MFTF does not support executing CLI commands if your web server points to `<MAGE_ROOT_DIR>/pub` directory as recommended in the [Installation Guide][Installation Guide docroot]. For the MFTF to execute the CLI commands, the web server must point to the Magento root directory.
+MFTF does not support executing CLI commands if your web server points to `<MAGE_ROOT_DIR>/pub` directory as recommended in the [Installation Guide][Installation Guide docroot]. For MFTF to execute the CLI commands, the web server must point to the Magento root directory.
 
 ### Nginx settings {#nginx-settings}
 
@@ -137,11 +137,11 @@ location ~* ^/dev/tests/acceptance/utils($|/) {
 
 ## Set up an embedded MFTF {#setup-framework}
 
-This is the default setup of the MFTF that you would need to cover your Magento project with functional tests.
+This is the default setup of MFTF that you would need to cover your Magento project with functional tests.
 It installs the framework using an existing Composer dependency such as `magento/magento2-functional-testing-framework`.
-If you want to set up the MFTF as a standalone tool, refer to [Set up a standalone MFTF][].
+If you want to set up MFTF as a standalone tool, refer to [Set up a standalone MFTF][].
 
-Install the MFTF.
+Install MFTF.
 
 ```bash
 composer install
@@ -204,7 +204,7 @@ Learn more about environmental settings in [Configuration][].
 
 ### Step 3. Enable the Magento CLI commands
 
-In the Magento project root, run the following command to enable the MFTF to send Magento CLI commands to your Magento instance.
+In the Magento project root, run the following command to enable MFTF to send Magento CLI commands to your Magento instance.
 
  ```bash
 cp dev/tests/acceptance/.htaccess.sample dev/tests/acceptance/.htaccess
@@ -251,9 +251,7 @@ See more commands in [`mftf`][].
 
 ### Step 5. Generate reports {#reports}
 
-During testing, the MFTF generates test reports in CLI.
-You can generate visual representations of the report data using [Allure Framework][].
-To view the reports in GUI:
+During testing, MFTF generates test reports in CLI. You can generate visual representations of the report data using the [Allure Framework][]. To view the reports in a GUI:
 
 -  [Install Allure][]
 -  Run the tool to serve the artifacts in `dev/tests/acceptance/tests/_output/allure-results/`:
@@ -266,18 +264,16 @@ Learn more about Allure in the [official documentation][allure docs].
 
 ## Set up a standalone MFTF
 
-The MFTF is a root level Magento dependency, but it is also available for use as a standalone application.
-You may want to use a standalone application when you develop for or contribute to MFTF, which facilitates debugging and tracking changes.
-These guidelines demonstrate how to set up and run Magento acceptance functional tests using standalone MFTF.
+MFTF is a root level Magento dependency, but it is also available for use as a standalone application. You may want to use a standalone application when you develop for or contribute to MFTF, which facilitates debugging and tracking changes. These guidelines demonstrate how to set up and run Magento acceptance functional tests using standalone MFTF.
 
 ### Prerequisites
 
 This installation requires a local instance of the Magento application.
-The MFTF uses the [tests from Magento modules][mftf tests] as well as the `app/autoload.php` file.
+MFTF uses the [tests from Magento modules][mftf tests] as well as the `app/autoload.php` file.
 
 ### Step 1. Clone the MFTF repository
 
-If you develop or contribute to the MFTF, it makes sense to clone your fork of the MFTF repository.
+If you develop or contribute to MFTF, it makes sense to clone your fork of the MFTF repository.
 For contribution guidelines, refer to the [Contribution Guidelines for the Magento Functional Testing Framework][contributing].
 
 ### Step 2. Install the MFTF
@@ -307,7 +303,7 @@ Create the `utils/` directory, if you didn't find it.
 
 ### Step 6. Remove the MFTF package dependency in Magento
 
-The MFTF uses the Magento `app/autoload.php` file to read Magento modules.
+MFTF uses the Magento `app/autoload.php` file to read Magento modules.
 The MFTF dependency in Magento supersedes the standalone registered namespaces unless it is removed at a Composer level.
 
 ```bash
@@ -355,6 +351,6 @@ allure serve dev/tests/_output/allure-results/
 [selenium server]: https://www.seleniumhq.org/download/
 [Set up a standalone MFTF]: #set-up-a-standalone-mftf
 [test suite]: suite.html
-[Find your MFTF version]: introduction.html#find-your-mftf-version
+[Find your version]: introduction.html#find-your-mftf-version
 [Installation Guide docroot]: https://devdocs.magento.com/guides/v2.3/install-gde/tutorials/change-docroot-to-pub.html
 [Magento Two-Factor Authentication (2FA) extension]: https://devdocs.magento.com/guides/v2.3/security/two-factor-authentication.html

docs/introduction.md

@@ -5,15 +5,15 @@ 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.
+[Find your version] of MFTF.
 
 The Magento Functional Testing Framework (MFTF) is a framework used to perform automated end-to-end functional testing.
 
 ## Goals
 
 -  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.
+-  Enable extension developers to provide functional tests for their extensions.
+-  Ensure a common standard of quality between Magento, extension developers and system integrators.
 
 MFTF also focuses on
 
@@ -31,7 +31,7 @@ MFTF also focuses on
 
 ## MFTF tests
 
-The MFTF supports two different locations for storing the tests and test artifacts:
+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.
@@ -40,7 +40,7 @@ If you installed Magento with Composer, please refer to `vendor/magento/<module_
 
 ### Directory Structure
 
-The file structure under both of the both path cases is the same:
+The file structure under both cases is the same:
 
 ```tree
 Test
@@ -59,12 +59,6 @@ Test
         └── ...
 ```
 
-<div class="bs-callout bs-callout-info" markdown="1">
-
-We are actively developing functional tests. Check out the [MFTF Test Migration][] repository.
-
-</div>
-
 ## Use cases
 
 -  Contributor: changes the core behaviour, fixing the annoing bug.
@@ -130,7 +124,7 @@ codeception.dist.yml            // Codeception configuration (generated while ru
 
 ## MFTF tests
 
-The MFTF supports three different locations for storing the tests and test artifacts:
+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.
@@ -163,8 +157,6 @@ Follow the [MFTF project] and [contribute on Github].
 
 <!-- Link definitions -->
 [contribute on Github]: https://github.com/magento/magento2-functional-testing-framework/blob/master/.github/CONTRIBUTING.md
-[Functional Testing Framework]: https://devdocs.magento.com/guides/v2.3/mtf/mtf_introduction.html
 [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
+[Find your version]: #find-your-mftf-version
 [docs folder]: https://github.com/magento/magento2-functional-testing-framework/tree/master/docs