magento · KevinBKozan · Sep 23, 2019 · Aug 13, 2019 · Aug 15, 2019 · Aug 16, 2019
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,47 @@
 Magento Functional Testing Framework Changelog
 ================================================
 
+2.5.0
+-----
+* Traceability
+    * Allure output has been enhanced to contain new test artifacts created and used per MFTF step:
+        * `makeScreenshot` will contain an attachment under its Allure step.
+        * `seeInCurrentUrl` and all other `Url` asserts now contain an attachment with the expects vs actual comparison.
+        * `createData` and all other `Data` actions now contain attachments with `Request Body` and `Response Body`.
+* Modularity
+    * Added a new `mftf run:manifest` command to run testManifest files generated by `generate:tests`.
+        * See DevDocs for details
+    * `mftf generate/run:test` commands now implicitly generates the `suite` the test exists in.
+        * If a test exists in multiple suites, it will generate it in all suite contexts.
+    * `mftf run:test <testName>` will now only run the exact test provided, regardless of what is generated.
+* Maintainability
+    * Added an `--allow-skipped` flag that allows MFTF to ignore the `<skip>` annotation. This was added to the following commands:
+        * `generate:test`
+        * `run:test`
+        * `run:group`
+        * `run:failed`
+* Customizability
+    * `<entity>` defined in data.xml can now reference other `<entity>` directly.
+        * See DevDocs for details
+    * Added vault as an alternative credential storage.
+        * See DevDocs for details
+
+### Fixes
+* Fixed an issue where `grab` action variables were not substituting correctly when used as an element parameter.
+* Framework will not throw a descriptive error when referencing a `$persisted.field$` that does not exist.
+* MFTF test materials that `extends=""` itself will no longer cause infinite recursion.
+* Fixed an issue where a test could not reference a `$data.field$` whose casing was modified by the API that it used.
+* Fixed an issue with the default `functional.suite.yml` where it was incompatible with `symfony/yaml 4.0.0`.
+* Improved test generation performance via class refactors (`~10%` faster).
+
+### GitHub Issues/Pull requests:
+* [#377](https://github.com/magento/magento2-functional-testing-framework/pull/377) -- Non-API operations fixes
+
+2.4.5
+-----
+### Fixes
+* Fixed an issue where `.credentials` was required when using `<createData>` actions with field overrides.
+
 2.4.4
 -----
 ### Fixes

diff --git a/bin/mftf b/bin/mftf
@@ -29,7 +29,7 @@ try {
 try {
     $application = new Symfony\Component\Console\Application();
     $application->setName('Magento Functional Testing Framework CLI');
-    $application->setVersion('2.4.4');
+    $application->setVersion('2.5.0');
     /** @var \Magento\FunctionalTestingFramework\Console\CommandListInterface $commandList */
     $commandList = new \Magento\FunctionalTestingFramework\Console\CommandList;
     foreach ($commandList->getCommands() as $command) {

diff --git a/composer.json b/composer.json
@@ -2,7 +2,7 @@
     "name": "magento/magento2-functional-testing-framework",
     "description": "Magento2 Functional Testing Framework",
     "type": "library",
-    "version": "2.4.4",
+    "version": "2.5.0",
     "license": "AGPL-3.0",
     "keywords": ["magento", "automation", "functional", "testing"],
     "config": {

diff --git a/composer.lock b/composer.lock
diff --git a/docs/actiongroup-list.md b/docs/actiongroup-list.md
@@ -0,0 +1,6 @@
+# MFTF action group reference
+
+Action groups are important building blocks for quickly creating tests for the Magento Functional Testing Framework.
+This page lists all current action groups so developers can see what is available to them.
+
+{% include mftf/actiongroup_data.md %}
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,7 +1,7 @@
 # Configuration
 
 The `*.env` file provides additional configuration for the Magento Functional Testing Framework (MFTF).
-To run the MFTF on your Magento testing instance, specify the basic configuration values.
+To run the MFTF on your Magento instance, specify the basic configuration values.
 Advanced users can create custom configurations based on requirements and environment.
 
 ## Basic configuration
@@ -204,7 +204,7 @@ Example:
 FW_BP=~/magento/magento2-functional-testing-framework
 ```
 
-#### TESTS_MODULE_PATH
+### TESTS_MODULE_PATH
 
 The path to where the MFTF modules mirror Magento modules.
 
@@ -234,8 +234,8 @@ 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`
+-  for non-default Magento installation
+-  when use a subdirectory in the `MAGENTO_BASE_URL`
 
 Example: `dev/tests/acceptance/utils/command.php`
 
@@ -251,9 +251,35 @@ Example:
 BROWSER=firefox
 ```
 
+### CREDENTIAL_VAULT_ADDRESS
+
+The Api address for a vault server.
+
+Default: http://127.0.0.1:8200
+
+Example:
+
+```conf
+# Default api address for local vault dev server
+CREDENTIAL_VAULT_ADDRESS=http://127.0.0.1:8200
+```
+
+### CREDENTIAL_VAULT_SECRET_BASE_PATH
+
+Vault secret engine base path.
+
+Default: secret
+
+Example:
+
+```conf
+# Default base path for kv secret engine in local vault dev server
+CREDENTIAL_VAULT_SECRET_BASE_PATH=secret
+```
+
 <!-- Link definitions -->
 
 [`MAGENTO_CLI_COMMAND_PATH`]: #magento_cli_command_path
 [generateDate]: test/actions.md#generatedate
 [mftf]: commands/mftf.md
-[timezones]: http://php.net/manual/en/timezones.php
+[timezones]: http://php.net/manual/en/timezones.php
diff --git a/docs/credentials.md b/docs/credentials.md
@@ -1,15 +1,21 @@
 # Credentials
 
-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.
+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.
 
-## Define sensitive data in `.credentials`
+Currently the MFTF supports two types of credential storage:
+
+-  **.credentials file**
+-  **HashiCorp vault**
+
+## Configure File Storage
 
 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.
 
 ### Create `.credentials`
 
-To make the MFTF process the file with credentials, change directories to `magento2/dev/tests/acceptance/` and copy `.credentials.example` to `.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`.
 
 ```bash
 cd dev/tests/acceptance/
@@ -33,49 +39,119 @@ The command outputs the path if the file is excluded:
 .credentials
 ```
 
-### Define sensitive data
+### Define sensitive data in the `.credentials` file
 
-Open the `.credentials` file, uncomment the fields you want to use, and add your values:
+Open the `.credentials` file and, for Magento core credentials, uncomment the fields you want to use and add your values:
 
-```config
+```conf
 ...
 # Credentials for the USPS service
-carriers_usps_userid=test_user
-carriers_usps_password=Lmgxvrq89uPwECeV
+magento/carriers_usps_userid=usps_test_user
+magento/carriers_usps_password=Lmgxvrq89uPwECeV
 
 # Credentials for the DHL service
-#carriers/dhl/id_us=
-#carriers/dhl/password_us=
+#magento/carriers_dhl_id_us=dhl_test_user
+#magento/carriers_dhl_password_us=Mlgxv3dsagVeG
 ....
+```  
+
+Or add new key & value pairs for your own credentials. The keys use the following format:
+
+```conf
+<vendor>/<key_name>=<key_value>
 ```
 
 <div class="bs-callout bs-callout-info" markdown="1">
-The `/` symbol is not supported in a key name.
+The `/` symbol is not supported in a `key_name` other than the one after your vendor or extension name.
 </div>
-
-You are free to use any other keys you like, as they are merely the keys to reference from your tests.
+ 
+Otherwise you are free to use any other `key_name` you like, as they are merely the keys to reference from your tests.
 
 ```conf
 # Credentials for the MyAwesome service
-my_awesome_service_token=rRVSVnh3cbDsVG39oTMz4A
+vendor/my_awesome_service_token=rRVSVnh3cbDsVG39oTMz4A
+```
 
-# Credentials for the USPS service
-carriers_usps_userid=test_user
-carriers_usps_password=Lmgxvrq89uPwECeV
-....
+## Configure Vault Storage
+
+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. 
+
+### Install vault CLI
+
+Download and install vault CLI tool if you want to run or develop MFTF tests locally. [Download Vault][Download Vault]
+
+### Authenticate to vault via vault CLI
+
+Authenticate to vault server via the vault CLI tool: [Login Vault][Login Vault].
+
+```bash
+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.
+
+### Store secrets in vault
+
+The 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
+
+The path and key for secret data must follow the format:
+
+```conf
+<SECRETS_BASE_PATH>/mftf/<VENDOR>/<SECRET_KEY>
+```
+
+```conf
+# Secret path and key for carriers_usps_userid
+secret/mftf/magento/carriers_usps_userid
+
+# Secret path and key for carriers_usps_password
+secret/mftf/magento/carriers_usps_password
+```
+
+#### Write secrets to vault
+
+You can use vault CLI or API to write secret data (credentials, etc) to vault. Here is a CLI example:
+
+```bash
+vault kv put secret/mftf/magento/carriers_usps_userid carriers_usps_userid=usps_test_user
+vault kv put secret/mftf/magento/carriers_usps_password carriers_usps_password=Lmgxvrq89uPwECeV
 ```
 
+### Setup MFTF to use vault
+
+Add vault configuration environment variables [`CREDENTIAL_VAULT_ADDRESS`][] and [`CREDENTIAL_VAULT_SECRET_BASE_PATH`][] 
+from `etc/config/.env.example` in `.env`.
+Set values according to your vault server configuration.  
+
+```conf
+# Default vault dev server
+CREDENTIAL_VAULT_ADDRESS=http://127.0.0.1:8200
+CREDENTIAL_VAULT_SECRET_BASE_PATH=secret
+```
+
+## Configure both File Storage and Vault Storage
+
+It is possible and sometimes useful to setup and use both `.credentials` file and vault for secret storage at the same time. 
+In this case, the MFTF tests are able to read secret data at runtime from both storage options, but the local `.credentials` file will take precedence.
+
 <!-- {% raw %} -->
 
 ## Use credentials in a test
 
-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}}`:
+Credentials can be used in actions: [`fillField`][], [`magentoCLI`][], and [`createData`][].
+
+Define the value as a reference to the corresponding key in the credentials file or vault 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
+- `my_data_key` is a key in the the `.credentials` file or vault that contains the value to be used in a test step
 
-For example:
+For example, reference secret data in the [`fillField`][] action with the `userInput` attribute.
 
 ```xml
 <fillField stepKey="FillApiToken" selector=".api-token" userInput="{{_CREDS.my_data_key}}" />
@@ -88,13 +164,21 @@ For example:
 The generated tests do 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.
+The decrypted values are only available in the `.credentials` file or within vault.
 
 <div class="bs-callout bs-callout-info">
-The MFTF tests delivered with Magento application do not use credentials and do not cover external services, because of sensitivity of the data.</div>
+The MFTF tests delivered with Magento application do not use credentials and do not cover external services, because of sensitivity of the data.
+</div>
 
 <!-- Link definitions -->
 [`fillField`]: test/actions.md#fillfield
+[`magentoCLI`]: test/actions.md#magentocli
+[`createData`]: test/actions.md#createdata
 [data]: data.md
 [initial setup]: getting-started.md
 [test reports]: reporting.md
+[Download Vault]: https://www.hashicorp.com/products/vault/
+[Login Vault]: https://www.vaultproject.io/docs/commands/login.html
+[Vault KV2]: https://www.vaultproject.io/docs/secrets/kv/kv-v2.html
+[`CREDENTIAL_VAULT_ADDRESS`]: configuration.md#CREDENTIAL_VAULT_ADDRESS
+[`CREDENTIAL_VAULT_SECRET_BASE_PATH`]: configuration.md#CREDENTIAL_VAULT_SECRET_BASE_PATH
diff --git a/docs/data.md b/docs/data.md
@@ -173,6 +173,16 @@ The following is an example of a call in test:
 
 This action inputs data from the `name` of the `_defaultCategory` entity (for example, `simpleCategory598742365`) into the field with the locator defined in the selector of the `categoryNameInput` element of the `AdminCategoryBasicFieldSection`.
 
+You can also call data from the xml definition of a `data` tag directly:
+
+```xml
+<entity name="NewAdminUser" type="user">
+    <data key="username" unique="suffix">admin</data>
+    <data key="current_password">{{AnotherUser.current_password}}</data>  <!-- Data from another entity -->
+    <data key="current_password">{{_ENV.MAGENTO_ADMIN_PASSWORD}}</data>  <!-- ENV file reference -->
+</entity>
+```
+
 ## Reference
 
 ### entities {#entities-tag}

diff --git a/docs/selectors.md b/docs/selectors.md
@@ -0,0 +1,35 @@
+## Selectors
+
+These guidelines should help you to write high quality selectors.
+
+### Selectors SHOULD be written in CSS instead of XPath whenever possible
+
+CSS is generally easier to read than XPath. For example, `//*[@id="foo"]` in XPath can be expressed as simply as `#foo` in CSS.
+See this [XPath Cheatsheet](https://devhints.io/xpath) for more examples.
+
+### XPath selectors SHOULD NOT use `@attribute="foo"`. 
+
+This would fail if the attribute was `attribute="foo bar"`.
+Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`.
+
+### CSS and XPath selectors SHOULD be implemented in their most simple form
+
+* <span class="color:green">GOOD:</span> `#foo`
+* <span class="color:red">BAD:</span> `button[contains(@id, "foo")]`
+
+### CSS and XPath selectors SHOULD avoid making use of hardcoded indices
+
+Instead you SHOULD parameterize the selector.
+
+* <span class="color:green">GOOD:</span> `.foo:nth-of-type({{index}})`
+* <span class="color:red">BAD:</span> `.foo:nth-of-type(1)`
+
+* <span class="color:green">GOOD:</span> `button[contains(@id, "foo")][{{index}}]`
+* <span class="color:red">BAD:</span> `button[contains(@id, "foo")][1]`
+
+* <span class="color:green">GOOD:</span> `#actions__{{index}}__aggregator`
+* <span class="color:red">BAD:</span> `#actions__1__aggregator`
+
+### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute
+
+The `@data-bind` attribute is used by KnockoutJS, a framework Magento uses to create dynamic Javascript pages. Since this `@data-bind` attribute is tied to a specific framework, it should not be used for selectors. If Magento decides to use a different framework then these `@data-bind` selectors would break.