MQE-1376: [SPIKE] Investigate Self-Documentation for MFTF

.gitignore

@@ -15,4 +15,5 @@ codeception.yml
 dev/tests/functional/MFTF.suite.yml
 dev/tests/functional/_output
 dev/mftf.log
-dev/tests/mftf.log
+dev/tests/mftf.log
+dev/tests/docs/*

dev/tests/_bootstrap.php

@@ -60,6 +60,28 @@
 defined('TESTS_BP') || define('TESTS_BP', __DIR__);
 defined('TESTS_MODULE_PATH') || define('TESTS_MODULE_PATH', TESTS_BP . $RELATIVE_TESTS_MODULE_PATH);
 defined('MAGENTO_BP') || define('MAGENTO_BP', __DIR__);
+define('DOCS_OUTPUT_DIR',
+    FW_BP .
+    DIRECTORY_SEPARATOR .
+    "dev" .
+    DIRECTORY_SEPARATOR .
+    "tests" .
+    DIRECTORY_SEPARATOR .
+    "unit" .
+    DIRECTORY_SEPARATOR .
+    "_output"
+);
+define('RESOURCE_DIR',
+    FW_BP .
+    DIRECTORY_SEPARATOR .
+    "dev" .
+    DIRECTORY_SEPARATOR .
+    "tests" .
+    DIRECTORY_SEPARATOR .
+    "unit" .
+    DIRECTORY_SEPARATOR .
+    "Resources"
+);
 
 $utilDir = DIRECTORY_SEPARATOR . 'Util'. DIRECTORY_SEPARATOR . '*.php';
 

dev/tests/unit/Magento/FunctionalTestFramework/Test/Util/ActionGroupAnnotationExtractorTest.php

@@ -0,0 +1,104 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace tests\unit\Magento\FunctionalTestFramework\Test\Util;
+
+use AspectMock\Test as AspectMock;
+use Magento\FunctionalTestingFramework\Test\Util\ActionGroupAnnotationExtractor;
+use PHPUnit\Framework\TestCase;
+use tests\unit\Util\TestLoggingUtil;
+
+class ActionGroupAnnotationExtractorTest extends TestCase
+{
+    /**
+     * Before test functionality
+     * @return void
+     */
+    public function setUp()
+    {
+        TestLoggingUtil::getInstance()->setMockLoggingUtil();
+    }
+
+    /**
+     * Annotation extractor takes in raw array and condenses it to expected format
+     *
+     * @throws \Exception
+     */
+    public function testActionGroupExtractAnnotations()
+    {
+        // Test Data
+        $actionGroupAnnotations = [
+            "nodeName" => "annotations",
+            "description" => [
+                "nodeName" => "description",
+                "value" => "someDescription"
+            ],
+            "page" => [
+                "nodeName" => "page",
+                "value" => "somePage"
+            ]
+        ];
+        // Perform Test
+        $extractor = new ActionGroupAnnotationExtractor();
+        $returnedAnnotations = $extractor->extractAnnotations($actionGroupAnnotations, "fileName");
+
+        // Asserts
+
+        $this->assertEquals("somePage", $returnedAnnotations['page']);
+        $this->assertEquals("someDescription", $returnedAnnotations['description']);
+    }
+
+    /**
+     * Annotation extractor should throw warning when required annotations are missing
+     *
+     * @throws \Exception
+     */
+    public function testActionGroupMissingAnnotations()
+    {
+        // Action Group Data, missing page and description
+        $testAnnotations = [];
+        // Perform Test
+        $extractor = new ActionGroupAnnotationExtractor();
+        AspectMock::double($extractor, ['isCommandDefined' => true]);
+        $extractor->extractAnnotations($testAnnotations, "fileName");
+
+        // Asserts
+        TestLoggingUtil::getInstance()->validateMockLogStatement(
+            'warning',
+            'DEPRECATION: Action Group File fileName is missing required annotations.',
+            [
+                'actionGroup' => 'fileName',
+                'missingAnnotations' => "description, page"
+            ]
+        );
+    }
+
+    /**
+     * Annotation extractor should not throw warning when required
+     * annotations are missing if command is not generate:docs
+     *
+     * @throws \Exception
+     */
+    public function testActionGroupMissingAnnotationsNoWarning()
+    {
+        // Action Group Data, missing page and description
+        $testAnnotations = [];
+        // Perform Test
+        $extractor = new ActionGroupAnnotationExtractor();
+        $extractor->extractAnnotations($testAnnotations, "fileName");
+
+        // Asserts
+        TestLoggingUtil::getInstance()->validateMockLogEmpty();
+    }
+
+    /**
+     * After class functionality
+     * @return void
+     */
+    public static function tearDownAfterClass()
+    {
+        TestLoggingUtil::getInstance()->clearMockLoggingUtil();
+    }
+}

dev/tests/unit/Magento/FunctionalTestFramework/Util/DocGeneratorTest.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * Copyright © Magento, Inc. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Tests\unit\Magento\FunctionalTestFramework\Test\Handlers;
+
+use Magento\FunctionalTestingFramework\Exceptions\TestFrameworkException;
+use Magento\FunctionalTestingFramework\Util\MagentoTestCase;
+use Magento\FunctionalTestingFramework\Util\DocGenerator;
+use tests\unit\Util\ActionGroupObjectBuilder;
+
+class DocGeneratorTest extends MagentoTestCase
+{
+    const DOC_FILENAME = "documentation";
+
+    /**
+     * Basic test to check creation of documentation
+     *
+     * @throws \Exception
+     */
+    public function testBasicCreateDocumentation()
+    {
+        $annotations = [
+            "page" => "somePage",
+            "description" => "someDescription"
+        ];
+        $actionGroupUnderTest = (new ActionGroupObjectBuilder())
+            ->withAnnotations($annotations)
+            ->withFilename("filename")
+            ->build();
+        $docGenerator = new DocGenerator();
+        $docGenerator->createDocumentation(
+            [$actionGroupUnderTest->getName() => $actionGroupUnderTest],
+            DOCS_OUTPUT_DIR,
+            true
+        );
+
+        $docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
+
+        $this->assertTrue(file_exists($docFile));
+
+        $this->assertFileEquals(
+            RESOURCE_DIR . DIRECTORY_SEPARATOR . "basicDocumentation.txt",
+            $docFile
+        );
+    }
+
+    /**
+     * Test to check creation of documentation when overwriting previous
+     *
+     * @throws \Exception
+     */
+    public function testCreateDocumentationWithOverwrite()
+    {
+        $annotations = [
+            "page" => "somePage",
+            "description" => "someDescription"
+        ];
+        $actionGroupUnderTest = (new ActionGroupObjectBuilder())
+            ->withAnnotations($annotations)
+            ->withFilename("filename")
+            ->build();
+        $docGenerator = new DocGenerator();
+        $docGenerator->createDocumentation(
+            [$actionGroupUnderTest->getName() => $actionGroupUnderTest],
+            DOCS_OUTPUT_DIR,
+            true
+        );
+
+        $annotations = [
+            "page" => "alteredPage",
+            "description" => "alteredDescription"
+        ];
+        $actionGroupUnderTest = (new ActionGroupObjectBuilder())
+            ->withAnnotations($annotations)
+            ->withFilename("filename")
+            ->build();
+        $docGenerator = new DocGenerator();
+        $docGenerator->createDocumentation(
+            [$actionGroupUnderTest->getName() => $actionGroupUnderTest],
+            DOCS_OUTPUT_DIR,
+            true
+        );
+
+        $docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
+
+        $this->assertTrue(file_exists($docFile));
+
+        $this->assertFileEquals(
+            RESOURCE_DIR . DIRECTORY_SEPARATOR . "alteredDocumentation.txt",
+            $docFile
+        );
+    }
+
+    /**
+     * Test for existing documentation without clean
+     *
+     * @throws \Exception
+     */
+    public function testCreateDocumentationNotCleanException()
+    {
+        $annotations = [
+            "page" => "somePage",
+            "description" => "someDescription"
+        ];
+        $actionGroupUnderTest = (new ActionGroupObjectBuilder())
+            ->withAnnotations($annotations)
+            ->withFilename("filename")
+            ->build();
+        $docGenerator = new DocGenerator();
+        $docGenerator->createDocumentation(
+            [$actionGroupUnderTest->getName() => $actionGroupUnderTest],
+            DOCS_OUTPUT_DIR,
+            true
+        );
+
+        $docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
+
+        $this->expectException(TestFrameworkException::class);
+        $this->expectExceptionMessage("$docFile already exists, please add --clean if you want to overwrite it.");
+
+        $docGenerator = new DocGenerator();
+        $docGenerator->createDocumentation(
+            [$actionGroupUnderTest->getName() => $actionGroupUnderTest],
+            DOCS_OUTPUT_DIR,
+            false
+        );
+    }
+}

dev/tests/unit/Resources/alteredDocumentation.txt

@@ -0,0 +1,16 @@
+#Action Group Information
+This documentation contains a list of all action groups on the pages on which they start
+
+##List of Pages
+- [ alteredPage ](#alteredPage)
+---
+<a name="alteredPage"></a>
+##alteredPage
+
+###testActionGroupObject
+alteredDescription
+
+Located in:
+
+- filename
+***

dev/tests/unit/Resources/basicDocumentation.txt

@@ -0,0 +1,16 @@
+#Action Group Information
+This documentation contains a list of all action groups on the pages on which they start
+
+##List of Pages
+- [ somePage ](#somePage)
+---
+<a name="somePage"></a>
+##somePage
+
+###testActionGroupObject
+someDescription
+
+Located in:
+
+- filename
+***

dev/tests/unit/Util/ActionGroupObjectBuilder.php

@@ -27,6 +27,13 @@ class ActionGroupObjectBuilder
      */
     private $actionObjects = [];
 
+    /**
+     * Action Group Object Builder default entity annotations.
+     *
+     * @var array
+     */
+    private $annotations = [];
+
     /**
      * Action Group Object Builder default entity arguments.
      *
@@ -41,6 +48,13 @@ class ActionGroupObjectBuilder
      */
     private $extends = null;
 
+    /**
+     * Action Group Object Builder default filenames
+     *
+     * @var string
+     */
+    private $filename = [];
+
     /**
      * Setter for the Action Group Object name
      *
@@ -53,6 +67,18 @@ public function withName($name)
         return $this;
     }
 
+    /**
+     * Setter for the Action Group Object annotations
+     *
+     * @param array $annotations
+     * @return ActionGroupObjectBuilder
+     */
+    public function withAnnotations($annotations)
+    {
+        $this->annotations = $annotations;
+        return $this;
+    }
+
     /**
      * Setter for the Action Group Object arguments
      *
@@ -89,6 +115,18 @@ public function withExtendedAction($extendedActionGroup)
         return $this;
     }
 
+    /**
+     * Setter for the Action Group Object filename
+     *
+     * @param string $filename
+     * @return ActionGroupObjectBuilder
+     */
+    public function withFilename($filename)
+    {
+        $this->filename = $filename;
+        return $this;
+    }
+
     /**
      * ActionGroupObjectBuilder constructor.
      */
@@ -108,9 +146,11 @@ public function build()
     {
         return new ActionGroupObject(
             $this->name,
+            $this->annotations,
             $this->arguments,
             $this->actionObjects,
-            $this->extends
+            $this->extends,
+            $this->filename
         );
     }
 }