Merge branch 'develop' into 3.0.0-RC2

Author: okolesnyk

docs/test.md

@@ -1,9 +1,9 @@
 # Test
 
 Test cases in the Magento Functional Testing Framework (MFTF) are defined in XML as [`<tests>`].
-`<tests>` is a [Codeception test container][Codeception] that contains multiple individual tests with test metadata and before and after actions.
+`<tests>` is a [Codeception test container][Codeception] that contains individual test [`<test>`] with its metadata ([`<annotations>`]), before ([`<before>`]) and after ([`<after>`]) section.
 
-MFTF `<tests>` is considered a sequence of actions with associated parameters.
+MFTF `<test>` is considered a sequence of actions with associated parameters.
 Any failed [assertion] within a test constitutes a failed test.
 
 <div class="bs-callout bs-callout-info" markdown="1">
@@ -18,7 +18,7 @@ The following diagram shows the structure of an MFTF test case:
 
 ## Format
 
-The format of `<tests>` is:
+The format of a test XML file is:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -44,26 +44,23 @@ The format of `<tests>` is:
 
 The following conventions apply to MFTF tests:
 
-*  All names within the framework are in the CamelCase format.
-*  `<test>` name must be alphanumeric.
-*  Each action and action group has its own identifier `<stepKey>` for reference purposes.
-*  A test may have any number of [assertions][assertion] at any point within the `<test>`.
-*  If `<test>` is included in `<suite>`, it **cannot be generated in isolation** to the rest of the contents of the suite (see [suites] for details).
 *  One `<test>` tag is allowed per test XML file.
+*  All names within the framework are in the **PascalCase** format and must be alphanumeric.
+*  Each action and action group call should have its own identifier `<stepKey>`.
+*  A test may have any number of [assertions][assertion] at any point within the `<test>`.
+*  If `<test>` is included in [`<suite>`][suites], it **cannot be generated in isolation** from `<before>` and `<after>` section of the suite (see [suites] for details).
 
 ## Elements reference
 
-There are several XML elements that are used in `<tests>` in the MFTF.
+There are several XML elements that are used within `<test>` in the MFTF.
 
 ### tests {#tests-tag}
 
-`<tests>` is a container for multiple tests. It is a group of test methods that define test flows within a test case.
-
-`<tests>` must contain at least one [`<test>`].
+`<tests>` is a container for test and must contain exactly one [`<test>`].
 
 ### test {#test-tag}
 
-`<test>` is a set of steps, including [actions] and [assertions][assertion]. It is a sequence of test steps that define test flow within a test method.
+`<test>` is a set of steps, including [actions], [assertions][assertion] and Action Group calls. It is a sequence of test steps that define test flow within a test method.
 
 Attribute|Type|Use|Description
 ---|---|---|---
@@ -85,21 +82,20 @@ Allure annotations provide metadata for reporting.
 
 ### before {#before-tag}
 
-`<before>` wraps the steps to perform before the [`<test>`].
+`<before>` wraps the steps that are preconditions for the [`<test>`]. For example: Change configuration, create Customer Account, Create Category and Product.
 
 `<before>` may contain these child elements:
 
-*  Any [`<action>`][actions]
-*  [`<actionGroup>`]
+*  Any [Action][actions]
+*  [`<actionGroup>`]s
 
 ### after {#after-tag}
 
-`<after>` wraps the steps to perform after the [`<test>`].
-The steps are run in both successful **and** failed test runs.
+`<after>` wraps the steps to perform after the [`<test>`]. The steps are run in both successful **and** failed test runs. The goal of this section is to perform cleanup (revert the environment to the pre-test state).
 
 `<after>` may contain:
 
-*  Any [`<action>`][actions]
+*  Any [Action][actions]
 *  [`<actionGroup>`]
 
 ### actionGroup {#actiongroup-tag}

src/Magento/FunctionalTestingFramework/Console/GenerateDevUrnCommand.php

@@ -4,7 +4,7 @@
  * Copyright © Magento, Inc. All rights reserved.
  * See COPYING.txt for license details.
  */
-declare(strict_types = 1);
+declare(strict_types=1);
 
 namespace Magento\FunctionalTestingFramework\Console;
 
@@ -19,6 +19,14 @@
 
 class GenerateDevUrnCommand extends Command
 {
+    /**
+     * Argument for the path to IDE config file
+     */
+    const IDE_FILE_PATH_ARGUMENT = 'path';
+
+    const PROJECT_PATH_IDENTIFIER = '$PROJECT_DIR$';
+    const MFTF_SRC_PATH = 'src/Magento/FunctionalTestingFramework/';
+
     /**
      * Configures the current command.
      *
@@ -27,8 +35,12 @@ class GenerateDevUrnCommand extends Command
     protected function configure()
     {
         $this->setName('generate:urn-catalog')
-            ->setDescription('This command generates an URN catalog to enable PHPStorm to recognize and highlight URNs.')
-            ->addArgument('path', InputArgument::REQUIRED, 'path to PHPStorm misc.xml file (typically located in [ProjectRoot]/.idea/misc.xml)')
+            ->setDescription('Generates the catalog of URNs to *.xsd mappings for the IDE to highlight xml.')
+            ->addArgument(
+                self::IDE_FILE_PATH_ARGUMENT,
+                InputArgument::REQUIRED,
+                'Path to file to output the catalog. For PhpStorm use .idea/misc.xml'
+            )
             ->addOption(
                 "force",
                 'f',
@@ -47,7 +59,7 @@ protected function configure()
      */
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $miscXmlFilePath = $input->getArgument('path') . DIRECTORY_SEPARATOR . "misc.xml";
+        $miscXmlFilePath = $input->getArgument(self::IDE_FILE_PATH_ARGUMENT);
         $miscXmlFile = realpath($miscXmlFilePath);
         $force = $input->getOption('force');
 
@@ -71,7 +83,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
 
         //Locate ProjectResources node, create one if none are found.
         $nodeForWork = null;
-        foreach($dom->getElementsByTagName('component') as $child) {
+        foreach ($dom->getElementsByTagName('component') as $child) {
             if ($child->getAttribute('name') === 'ProjectResources') {
                 $nodeForWork = $child;
             }
@@ -109,35 +121,74 @@ protected function execute(InputInterface $input, OutputInterface $output)
 
     /**
      * Generates urn => location array for all MFTF schema.
+     *
      * @return array
-     * @throws TestFrameworkException
      */
     private function generateResourcesArray()
     {
         $resourcesArray = [
             'urn:magento:mftf:DataGenerator/etc/dataOperation.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/DataGenerator/etc/dataOperation.xsd'),
+                $this->getResourcePath('DataGenerator/etc/dataOperation.xsd'),
             'urn:magento:mftf:DataGenerator/etc/dataProfileSchema.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/DataGenerator/etc/dataProfileSchema.xsd'),
+                $this->getResourcePath('DataGenerator/etc/dataProfileSchema.xsd'),
             'urn:magento:mftf:Page/etc/PageObject.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/Page/etc/PageObject.xsd'),
+                $this->getResourcePath('Page/etc/PageObject.xsd'),
             'urn:magento:mftf:Page/etc/SectionObject.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/Page/etc/SectionObject.xsd'),
+                $this->getResourcePath('Page/etc/SectionObject.xsd'),
             'urn:magento:mftf:Test/etc/actionGroupSchema.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/Test/etc/actionGroupSchema.xsd'),
+                $this->getResourcePath('Test/etc/actionGroupSchema.xsd'),
             'urn:magento:mftf:Test/etc/testSchema.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/Test/etc/testSchema.xsd'),
+                $this->getResourcePath('Test/etc/testSchema.xsd'),
             'urn:magento:mftf:Suite/etc/suiteSchema.xsd' =>
-                realpath(FilePathFormatter::format(FW_BP)
-                    . 'src/Magento/FunctionalTestingFramework/Suite/etc/suiteSchema.xsd')
+                $this->getResourcePath('Suite/etc/suiteSchema.xsd')
         ];
         return $resourcesArray;
     }
 
+    /**
+     * Returns path (full or PhpStorm project-based) to XSD file
+     *
+     * @param $relativePath
+     * @return string
+     * @throws TestFrameworkException
+     */
+    private function getResourcePath($relativePath)
+    {
+        $urnPath = realpath(FilePathFormatter::format(FW_BP) . self::MFTF_SRC_PATH . $relativePath);
+        $projectRoot = $this->getProjectRootPath();
+
+        if ($projectRoot !== null) {
+            return str_replace($projectRoot, self::PROJECT_PATH_IDENTIFIER, $urnPath);
+        }
+
+        return $urnPath;
+    }
+
+    /**
+     * Returns Project root directory absolute path
+     * @TODO Find out how to detect other types of installation
+     *
+     * @return string|null
+     */
+    private function getProjectRootPath()
+    {
+        $frameworkRoot = realpath(__DIR__);
+
+        if ($this->isInstalledByComposer($frameworkRoot)) {
+            return strstr($frameworkRoot, '/vendor/', true);
+        }
+
+        return null;
+    }
+
+    /**
+     * Determines whether MFTF was installed using Composer
+     *
+     * @param string $frameworkRoot
+     * @return bool
+     */
+    private function isInstalledByComposer($frameworkRoot)
+    {
+        return false !== strpos($frameworkRoot, '/vendor/');
+    }
 }