From 260107450725c8af5a520598604a9650661ff87b Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Wed, 11 Mar 2020 16:19:48 -0500 Subject: [PATCH] MQE-2018: Remove dead code: GenerateDocsCommand --- .../ActionGroupAnnotationExtractorTest.php | 43 ------ .../Util/DocGeneratorTest.php | 127 ---------------- docs/commands/mftf.md | 34 ----- .../Console/CommandList.php | 1 - .../Console/GenerateDocsCommand.php | 86 ----------- .../Util/ActionGroupAnnotationExtractor.php | 50 ------- .../Util/DocGenerator.php | 137 ------------------ 7 files changed, 478 deletions(-) delete mode 100644 dev/tests/unit/Magento/FunctionalTestFramework/Util/DocGeneratorTest.php delete mode 100644 src/Magento/FunctionalTestingFramework/Console/GenerateDocsCommand.php delete mode 100644 src/Magento/FunctionalTestingFramework/Util/DocGenerator.php diff --git a/dev/tests/unit/Magento/FunctionalTestFramework/Test/Util/ActionGroupAnnotationExtractorTest.php b/dev/tests/unit/Magento/FunctionalTestFramework/Test/Util/ActionGroupAnnotationExtractorTest.php index af39298b1..392c870d9 100644 --- a/dev/tests/unit/Magento/FunctionalTestFramework/Test/Util/ActionGroupAnnotationExtractorTest.php +++ b/dev/tests/unit/Magento/FunctionalTestFramework/Test/Util/ActionGroupAnnotationExtractorTest.php @@ -44,49 +44,6 @@ public function testActionGroupExtractAnnotations() $this->assertEquals("someDescription", $returnedAnnotations['description']); } - /** - * Annotation extractor should throw warning when required annotations are missing - * - * @throws \Exception - */ - public function testActionGroupMissingAnnotations() - { - // Action Group Data, missing 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" - ] - ); - } - - /** - * 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 description - $testAnnotations = []; - // Perform Test - $extractor = new ActionGroupAnnotationExtractor(); - $extractor->extractAnnotations($testAnnotations, "fileName"); - - // Asserts - TestLoggingUtil::getInstance()->validateMockLogEmpty(); - } - /** * After class functionality * @return void diff --git a/dev/tests/unit/Magento/FunctionalTestFramework/Util/DocGeneratorTest.php b/dev/tests/unit/Magento/FunctionalTestFramework/Util/DocGeneratorTest.php deleted file mode 100644 index 0fb73e53f..000000000 --- a/dev/tests/unit/Magento/FunctionalTestFramework/Util/DocGeneratorTest.php +++ /dev/null @@ -1,127 +0,0 @@ - "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 = [ - "description" => "someDescription" - ]; - $actionGroupUnderTest = (new ActionGroupObjectBuilder()) - ->withAnnotations($annotations) - ->withFilename("filename") - ->build(); - $docGenerator = new DocGenerator(); - $docGenerator->createDocumentation( - [$actionGroupUnderTest->getName() => $actionGroupUnderTest], - DOCS_OUTPUT_DIR, - true - ); - - $annotations = [ - "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 = [ - "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 - ); - } -} diff --git a/docs/commands/mftf.md b/docs/commands/mftf.md index 9b16e23a4..7a4852efb 100644 --- a/docs/commands/mftf.md +++ b/docs/commands/mftf.md @@ -89,14 +89,6 @@ vendor/bin/mftf run:failed This command cleans up the previously generated tests; generates and runs the tests listed in `dev/tests/acceptance/tests/_output/failed`. For more details about `failed`, refer to [Reporting][]. -### Generate documentation for action groups - -```bash -vendor/bin/mftf generate:docs -``` - -This command generates documentation for action groups. - ## Reference ### `build:project` @@ -270,32 +262,6 @@ vendor/bin/mftf generate:urn-catalog [--force] [/dev/tests/docs/documentation.md`. - -#### Usage - -```bash -vendor/bin/mftf generate:docs [--clean] [--output=/path/to/alternate/dir] -``` - -#### Options - -| Option | Description | -| ------------- | --------------------------------------------------------------------- | -| `-c, --clean` | Overwrites previously existing documentation | -| `-o, --output` | Changes the default output directory to a user specified directory | - -#### Example - -```bash -vendor/bin/mftf generate:docs --clean -``` - ### `reset` #### Description diff --git a/src/Magento/FunctionalTestingFramework/Console/CommandList.php b/src/Magento/FunctionalTestingFramework/Console/CommandList.php index bf9cbd58e..f77c2c576 100644 --- a/src/Magento/FunctionalTestingFramework/Console/CommandList.php +++ b/src/Magento/FunctionalTestingFramework/Console/CommandList.php @@ -31,7 +31,6 @@ public function __construct(array $commands = []) $this->commands = [ 'build:project' => new BuildProjectCommand(), 'doctor' => new DoctorCommand(), - 'generate:docs' => new GenerateDocsCommand(), 'generate:suite' => new GenerateSuiteCommand(), 'generate:tests' => new GenerateTestsCommand(), 'generate:urn-catalog' => new GenerateDevUrnCommand(), diff --git a/src/Magento/FunctionalTestingFramework/Console/GenerateDocsCommand.php b/src/Magento/FunctionalTestingFramework/Console/GenerateDocsCommand.php deleted file mode 100644 index ce920e39d..000000000 --- a/src/Magento/FunctionalTestingFramework/Console/GenerateDocsCommand.php +++ /dev/null @@ -1,86 +0,0 @@ -setName('generate:docs') - ->setDescription('This command generates documentation for created MFTF files.') - ->addOption( - "output", - 'o', - InputOption::VALUE_REQUIRED, - 'Output Directory' - )->addOption( - "clean", - 'c', - InputOption::VALUE_NONE, - 'Clean Output Directory' - )->addOption( - "force", - 'f', - InputOption::VALUE_NONE, - 'Force Document Generation For All Action Groups' - ); - } - - /** - * Executes the current command. - * - * @param InputInterface $input - * @param OutputInterface $output - * @return void - * @throws TestFrameworkException - * @throws \Magento\FunctionalTestingFramework\Exceptions\TestReferenceException - * @throws \Magento\FunctionalTestingFramework\Exceptions\XmlException - */ - protected function execute(InputInterface $input, OutputInterface $output) - { - defined('COMMAND') || define('COMMAND', 'generate:docs'); - $config = $input->getOption('output'); - $clean = $input->getOption('clean'); - $force = $input->getOption('force'); - - MftfApplicationConfig::create( - $force, - MftfApplicationConfig::GENERATION_PHASE, - false, - MftfApplicationConfig::LEVEL_DEFAULT, - true - ); - - $allActionGroups = ActionGroupObjectHandler::getInstance()->getAllObjects(); - $docGenerator = new DocGenerator(); - $docGenerator->createDocumentation($allActionGroups, $config, $clean); - - $output->writeln("Generate Docs Command Run"); - - if (empty($config)) { - $output->writeln("Output to ". DocGenerator::DEFAULT_OUTPUT_DIR); - } else { - $output->writeln("Output to ". $config); - } - } -} diff --git a/src/Magento/FunctionalTestingFramework/Test/Util/ActionGroupAnnotationExtractor.php b/src/Magento/FunctionalTestingFramework/Test/Util/ActionGroupAnnotationExtractor.php index 9d3a9877e..65f0f41b0 100644 --- a/src/Magento/FunctionalTestingFramework/Test/Util/ActionGroupAnnotationExtractor.php +++ b/src/Magento/FunctionalTestingFramework/Test/Util/ActionGroupAnnotationExtractor.php @@ -13,11 +13,6 @@ */ class ActionGroupAnnotationExtractor extends AnnotationExtractor { - const ACTION_GROUP_REQUIRED_ANNOTATIONS = [ - "description" - ]; - const GENERATE_DOCS_COMMAND = 'generate:docs'; - /** * This method trims away irrelevant tags and returns annotations used in the array passed. The annotations * can be found in both Tests and their child element tests. @@ -35,52 +30,7 @@ public function extractAnnotations($testAnnotations, $filename) foreach ($annotations as $annotationKey => $annotationData) { $annotationObjects[$annotationKey] = $annotationData[parent::ANNOTATION_VALUE]; } - // TODO: Remove this when all action groups have annotations - if ($this->isCommandDefined()) { - $this->validateMissingAnnotations($annotationObjects, $filename); - } return $annotationObjects; } - - /** - * Validates given annotations against list of required annotations. - * - * @param array $annotationObjects - * @return void - * @throws \Exception - */ - private function validateMissingAnnotations($annotationObjects, $filename) - { - $missingAnnotations = []; - - foreach (self::ACTION_GROUP_REQUIRED_ANNOTATIONS as $REQUIRED_ANNOTATION) { - if (!array_key_exists($REQUIRED_ANNOTATION, $annotationObjects)) { - $missingAnnotations[] = $REQUIRED_ANNOTATION; - } - } - - if (!empty($missingAnnotations)) { - $message = "Action Group File {$filename} is missing required annotations."; - LoggingUtil::getInstance()->getLogger(ActionObject::class)->deprecation( - $message, - ["actionGroup" => $filename, "missingAnnotations" => implode(", ", $missingAnnotations)], - true - ); - } - } - - /** - * Checks if command is defined as generate:docs - * - * @return boolean - */ - private function isCommandDefined() - { - if (defined('COMMAND') and COMMAND == self::GENERATE_DOCS_COMMAND) { - return true; - } else { - return false; - } - } } diff --git a/src/Magento/FunctionalTestingFramework/Util/DocGenerator.php b/src/Magento/FunctionalTestingFramework/Util/DocGenerator.php deleted file mode 100644 index 7a28f8969..000000000 --- a/src/Magento/FunctionalTestingFramework/Util/DocGenerator.php +++ /dev/null @@ -1,137 +0,0 @@ - $object) { - $annotations = $object->getAnnotations(); - $filenames = explode(',', $object->getFilename()); - $arguments = $object->getArguments(); - - $info = [ - actionGroupObject::ACTION_GROUP_DESCRIPTION => $annotations[actionGroupObject::ACTION_GROUP_DESCRIPTION] - ?? 'NO_DESCRIPTION_SPECIFIED', - self::FILENAMES => $filenames, - ActionGroupObjectExtractor::ACTION_GROUP_ARGUMENTS => $arguments - ]; - - $pageGroups = array_merge_recursive( - $pageGroups, - [$annotations[ActionGroupObject::ACTION_GROUP_PAGE] ?? 'NO_PAGE_SPECIFIED' => [$name => $info]] - ); - } - - ksort($pageGroups); - foreach ($pageGroups as $page => $groups) { - ksort($groups); - $pageGroups[$page] = $groups; - } - - $markdown = $this->transformToMarkdown($pageGroups); - - file_put_contents($filePath, $markdown); - } - - /** - * This creates html documentation for objects passed in - * - * @param array $annotationList - * @return string - */ - private function transformToMarkdown($annotationList) - { - $markdown = "#Action Group Information" . PHP_EOL; - $markdown .= "This documentation contains a list of all Action Groups." . - PHP_EOL . - PHP_EOL; - - $markdown .= "---" . PHP_EOL; - foreach ($annotationList as $group => $objects) { - foreach ($objects as $name => $annotations) { - $markdown .= "###$name" . PHP_EOL; - $markdown .= "**Description**:" . PHP_EOL; - $markdown .= "- " . $annotations[actionGroupObject::ACTION_GROUP_DESCRIPTION] . PHP_EOL . PHP_EOL; - if (!empty($annotations[ActionGroupObjectExtractor::ACTION_GROUP_ARGUMENTS])) { - $markdown .= "**Action Group Arguments**:" . PHP_EOL . PHP_EOL; - $markdown .= "| Name | Type |" . PHP_EOL; - $markdown .= "| ---- | ---- |" . PHP_EOL; - foreach ($annotations[ActionGroupObjectExtractor::ACTION_GROUP_ARGUMENTS] as $argument) { - $argumentName = $argument->getName(); - $argumentType = $argument->getDataType(); - $markdown .= "| $argumentName | $argumentType |" . PHP_EOL; - } - $markdown .= PHP_EOL; - } - $markdown .= "**Located In**:" . PHP_EOL; - foreach ($annotations[self::FILENAMES] as $filename) { - $relativeFilename = str_replace(MAGENTO_BP . DIRECTORY_SEPARATOR, "", $filename); - $markdown .= PHP_EOL . "- $relativeFilename"; - } - $markdown .= PHP_EOL . "***" . PHP_EOL; - } - } - return $markdown; - } -}