Finished the working draft

dshevtsov · dshevtsov · commit 406029b81da3 · 2018-11-08T14:13:11.000-06:00
diff --git a/mftf/2.3/credentials.md b/mftf/2.3/credentials.md
@@ -3,14 +3,16 @@
 
 # Credentials
 
-When you test functionality that involves external services such as UPS, FedEx, PayPal, SignifyD, use the MFTF credentials feature to hide sensitive data like integration tokens, API keys, etc.
+When you test functionality that involves external services such as UPS, FedEx, PayPal, SignifyD, use the MFTF credentials feature to hide sensitive [data][] like integration tokens, API keys, etc.
 
 ## Define sensitive data in `.credentials`
 
-The MFTF creates a sample file for credentials during [initial setup]: `magento2/dev/tests/acceptance/.credentials.example`.
-The file contains a list of fields for credentials you may need.
+The 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.
 
-To make the file with credentials visible for the MFTF, copy the `.credentials.example` to ``.credentials` while you are in the `<magento root>/dev/tests/acceptance/` directory:
+### Create `.credentials`
+
+To make the MFTF to process the file with credentials, copy `.credentials.example` to `.credentials` while you are at the `magento2/dev/tests/acceptance/` directory:
 
 ```bash
 cd dev/tests/acceptance/
@@ -20,7 +22,9 @@ cd dev/tests/acceptance/
 cp .credentials.example .credentials
 ```
 
-Verify whether the file is excluded from tracking by `.gitignore` (unless you need this behavior):
+### Add `.credentials` to `.gitignore`
+
+Verify that the file is excluded from tracking by `.gitignore` (unless you need this behavior):
 
 ```bash
 git check-ignore .credentials
@@ -32,65 +36,63 @@ The command outputs the path if the file is excluded:
 .credentials
 ```
 
+### Define sensitive data
+
 Open the file, uncomment the fields you want to use, and add your values:
 
 ```config
-carriers/usps/userid=test_user
-carriers/usps/password=Lmgxvrq89uPwECeV
-
-#carriers_dhl_id_us=
-#carriers_dhl_password_us=
+...
+# Credentials for the USPS service
+carriers_usps_userid=test_user
+carriers_usps_password=Lmgxvrq89uPwECeV
+
+# Credentials for the DHL service
+#carriers/dhl/id_us=
+#carriers/dhl/password_us=
 ....
 ```
 
-## Use credentials in test
+{: .bs-callout .bs-callout-info }
+The `/` symbol is not supported in a key name.
 
-Access data defined in the `.credentials` file using the [`fillField` ][] action with the `userInput` attribute defined in the `{{_CREDS.<your data key>}}` format.
-For example:
+You are free to use any other keys you like, as they are merely the keys to reference from your tests.
 
-```xml
-<fillField stepKey="FillAPIUsername" selector=".username" userInput="{{_CREDS.PAYMENTUSER}}"/>
-<fillField stepKey="FillAPIPassword" selector=".password" userInput="{{_CREDS.PAYMENTPASSWORD}}"/>
-```
+```conf
+# Credentials for the MyAwesome service
+my_awesome_service_token=rRVSVnh3cbDsVG39oTMz4A
 
+# Credentials for the USPS service
+carriers_usps_userid=test_user
+carriers_usps_password=Lmgxvrq89uPwECeV
+....
+```
 
-When you need to use credentials in your tests such as integration token, you can do it without exposing the sensitive data in your XML tests.
+## Use credentials in test
 
-The MFTF enables you to store credentials for external services in the `.credentials` file which is 
-The template file is `.credentials.example`.
+<!--{% raw %}-->
+Access the data defined in the `.credentials` file using the [`fillField`][] action with the `userInput` attribute.
+Define the value as a reference to the corresponding key in the credentials file such as `{{_CREDS.my_data_key}}`:
 
+- `_CREDS` is an environment constant pointing to the `.credentials` file
+- `my_data_key` is a key in the the `.credentials` file that contains the value to be used in a test step
 
+For example:
 
-1. When do I need people would need credentials in the MFTF?
-    - Credentials are used for when you need to input an integration token or other security credential via a `fillField`.
-    - You shouldn't have security tokens checked in to any repo, so storing it in a DATA.xml file is a bad idea
-    - Furthermore, if you used data.xml, the Allure Report would show your security token like:
-        I fill field "SECURITYTOKEN".
-        - Use of {{_CREDS.TOKEN}} turns a `fillField` action into `fillSecretField` which scrubs the allure report.
+```xml
+<fillField stepKey="FillApiToken" selector=".api-token" userInput="{{_CREDS.my_data_key}}" />
+```
 
-2. What functionality does the MFTF credentials feature cover?
-    - How to store credentials
-        - build:project copies over .credentials.example, copy and remove the `.example`
-        - Store new credentials in a new line as `KEY=VALUE`
-    - How to use Credentials in test actions
-        - In fillField actions, you can reference it as {{_CREDS.KEY}}
-        - data.md has info on this, check out "Sensitive Data"
+## Implementations details
 
-3. How to implement credentials in test design?
-    - Credentials should only every be used if you have the need to connect to some external integration for your test
-    - Credentials should NOT be used to store stuff like Username/Password in your sandbox test environment; should be limited to tokens and passwords that would propose a security risk.
+The generated tests does not contain credentials values.
+The 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.
 
-4. How to setup credentials?
-    - build:project copies over .credentials.example, copy and remove the `.example`
-    - Store new credentials in a new line as
-        - KEY=VALUE
-    - You CANNOT check in the .credentials file
-        - For Magneto Devs, DevOps is still working on the solution of how to store credentials to be used in a build enviroment
-        - For outside Devs, they can store the credentials and build their own .credentials file as part of build steps
+<!--{% endraw %}-->
 
-5. Examples of daily routine tasks using credentials in the MFTF.
-    - In my test, I am wanting to test a Payment Method integration. This requires me to add a Payment via the Configuration page in the admin backend.
-    - I need to use the credentials to my Sandbox Environment, but I don't want those visible in the Allure Report:
-        - <fillField stepKey="FillAPIUsername" selector=".username" userInput="{{_CREDS.PAYMENTUSER}}"/>
-        - <fillField stepKey="FillAPIPassword" selector=".password" userInput="{{_CREDS.PAYMENTPASSWORD}}"/>
-  
+<!-- Link definitions -->
+[`fillField`]: test/actions.html#fillfield
+[data]: data.html
+[initial setup]: getting-started.html
+[test reports]: reporting.html
diff --git a/mftf/2.3/data.md b/mftf/2.3/data.md
@@ -8,15 +8,13 @@ redirect_from: /guides/v2.3/magento-functional-testing-framework/2.3/data.html
 _This topic was updated due to the {{page.mftf-release}} MFTF release._
 {: style="text-align: right"}
 
-Tests require data to function properly.
-
-The MFTF allows 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 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:
 
 {%include_relative img/data-dia.svg%}
 
-### Supply data to test by reference to a data entity
+## Supply data to test by reference to a data entity
+
 {%raw%}
 Test steps requiring `<data>` input in an action, like filling a field with a string, may reference an attribute from a data entity:
 
@@ -29,8 +27,7 @@ In this example:
 * `SimpleSubCategory` is an entity name.
 * `name` is a `<data>` key of the entity. The corresponding value will be assigned to `userInput` as a result.
 
-****
-#### Environmental data
+### Environmental data
 
 ```xml
 userInput="{{_ENV.MAGENTO_ADMIN_USERNAME}}"
@@ -40,23 +37,24 @@ In this example:
 
 * `_ENV` is a reference to the `dev/tests/acceptance/.env` file, where basic environment variables are set.
 * `MAGENTO_ADMIN_USERNAME` is a name of an environment variable.
-The corresponding value will be assigned to `userInput` as a result.
+   The corresponding value will be assigned to `userInput` as a result.
 
-#### Sensitive data
+### Sensitive data
 
 ```xml
-userInput="{{_CREDS.MY_SECRET_TOKEN}}"
+userInput="{{_CREDS.my_secret_token}}"
 ```
 
 In this example:
 
-* `_CREDS` is a reference to the `dev/tests/acceptance/.credentials` file, where sensitive data and secrets are stored for use in a test.
+* `_CREDS` is a constant to reference to the `dev/tests/acceptance/.credentials` file, where sensitive data and secrets are stored for use in a test.
 * `MY_SECRET_TOKEN` is the name of a key in the credentials variable.
-The corresponding value of the credential will be assigned to `userInput` as a result.
-* Credential values are not generated into a test. Instead, they are dynamically retrieved, encrypted and decrypted when used by a specific action during the test's execution.
-* References to credentials do not appear decrypted in the console, error logs or test reports, their values can only be seen decrypted in the .credentials file in which they are stored.
+  The corresponding value of the credential will be assigned to `userInput` as a result.
+* The decrypted values are only available in the `.credentials` file in which they are stored.
 
-### Persist a data entity as a prerequisite of a test
+Learn more in [Credentials][].
+
+## Persist a data entity as a prerequisite of a test
 
 A test can specify an entity to be persisted (created in the database) so that the test actions could operate on the existing known data.
 
@@ -84,7 +82,8 @@ The current scope is preferred, then widening to _test > hook > suite_ or _hook
 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.'
 %}
 
-### Use data returned by test actions
+## Use data returned by test actions
+
 {%raw%}
 A test can also reference data that was returned as a result of [test actions](./test/actions.html#actions-returning-a-variable), like the action `<grabValueFrom selector="someSelector" stepKey="grabStepKey>`.
 
@@ -97,7 +96,7 @@ The following example shows the usage of `grabValueFrom` in testing, where the r
 <fillField selector=".functionalTestSelector" userInput="{$grabStepKey}" stepKey="fillFieldKey1"/>
 ```
 
-### Hard-coded data input
+## Hard-coded data input
 
 The data to operate against can be included as literals in a test. Hard-coded data input can be useful in assertions.
 
