Merge pull request #756 from magento/MQE-2214

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
@@ -221,13 +221,13 @@ The path to where the MFTF modules mirror Magento modules.
 Example:
 
 ```conf
-TESTS_MODULE_PATH=~/magento2/dev/tests/acceptance/tests/functional/Magento/FunctionalTest
+TESTS_MODULE_PATH=~/magento2/dev/tests/acceptance/tests/functional/Magento
 ```
 
 ### 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 `tests/functional/Magento`, 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.