Skip to content

Commit a86f010

Browse files
KevinBKozanKevinBKozan
authored
Merge pull request #324 from magento/MQE-1376
MQE-1376: [SPIKE] Investigate Self-Documentation for MFTF
2 parents 8af7dc4 + a766d44 commit a86f010

18 files changed

+753
-7
lines changed

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,5 @@ codeception.yml
1515
dev/tests/functional/MFTF.suite.yml
1616
dev/tests/functional/_output
1717
dev/mftf.log
18-
dev/tests/mftf.log
18+
dev/tests/mftf.log
19+
dev/tests/docs/*

‎dev/tests/_bootstrap.php

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,28 @@
6060
defined('TESTS_BP') || define('TESTS_BP', __DIR__);
6161
defined('TESTS_MODULE_PATH') || define('TESTS_MODULE_PATH', TESTS_BP . $RELATIVE_TESTS_MODULE_PATH);
6262
defined('MAGENTO_BP') || define('MAGENTO_BP', __DIR__);
63+
define('DOCS_OUTPUT_DIR',
64+
FW_BP .
65+
DIRECTORY_SEPARATOR .
66+
"dev" .
67+
DIRECTORY_SEPARATOR .
68+
"tests" .
69+
DIRECTORY_SEPARATOR .
70+
"unit" .
71+
DIRECTORY_SEPARATOR .
72+
"_output"
73+
);
74+
define('RESOURCE_DIR',
75+
FW_BP .
76+
DIRECTORY_SEPARATOR .
77+
"dev" .
78+
DIRECTORY_SEPARATOR .
79+
"tests" .
80+
DIRECTORY_SEPARATOR .
81+
"unit" .
82+
DIRECTORY_SEPARATOR .
83+
"Resources"
84+
);
6385

6486
$utilDir = DIRECTORY_SEPARATOR . 'Util'. DIRECTORY_SEPARATOR . '*.php';
6587

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

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
<?php
2+
/**
3+
* Copyright © Magento, Inc. All rights reserved.
4+
* See COPYING.txt for license details.
5+
*/
6+
namespace tests\unit\Magento\FunctionalTestFramework\Test\Util;
7+
8+
use AspectMock\Test as AspectMock;
9+
use Magento\FunctionalTestingFramework\Test\Util\ActionGroupAnnotationExtractor;
10+
use PHPUnit\Framework\TestCase;
11+
use tests\unit\Util\TestLoggingUtil;
12+
13+
class ActionGroupAnnotationExtractorTest extends TestCase
14+
{
15+
/**
16+
* Before test functionality
17+
* @return void
18+
*/
19+
public function setUp()
20+
{
21+
TestLoggingUtil::getInstance()->setMockLoggingUtil();
22+
}
23+
24+
/**
25+
* Annotation extractor takes in raw array and condenses it to expected format
26+
*
27+
* @throws \Exception
28+
*/
29+
public function testActionGroupExtractAnnotations()
30+
{
31+
// Test Data
32+
$actionGroupAnnotations = [
33+
"nodeName" => "annotations",
34+
"description" => [
35+
"nodeName" => "description",
36+
"value" => "someDescription"
37+
],
38+
"page" => [
39+
"nodeName" => "page",
40+
"value" => "somePage"
41+
]
42+
];
43+
// Perform Test
44+
$extractor = new ActionGroupAnnotationExtractor();
45+
$returnedAnnotations = $extractor->extractAnnotations($actionGroupAnnotations, "fileName");
46+
47+
// Asserts
48+
49+
$this->assertEquals("somePage", $returnedAnnotations['page']);
50+
$this->assertEquals("someDescription", $returnedAnnotations['description']);
51+
}
52+
53+
/**
54+
* Annotation extractor should throw warning when required annotations are missing
55+
*
56+
* @throws \Exception
57+
*/
58+
public function testActionGroupMissingAnnotations()
59+
{
60+
// Action Group Data, missing page and description
61+
$testAnnotations = [];
62+
// Perform Test
63+
$extractor = new ActionGroupAnnotationExtractor();
64+
AspectMock::double($extractor, ['isCommandDefined' => true]);
65+
$extractor->extractAnnotations($testAnnotations, "fileName");
66+
67+
// Asserts
68+
TestLoggingUtil::getInstance()->validateMockLogStatement(
69+
'warning',
70+
'DEPRECATION: Action Group File fileName is missing required annotations.',
71+
[
72+
'actionGroup' => 'fileName',
73+
'missingAnnotations' => "description, page"
74+
]
75+
);
76+
}
77+
78+
/**
79+
* Annotation extractor should not throw warning when required
80+
* annotations are missing if command is not generate:docs
81+
*
82+
* @throws \Exception
83+
*/
84+
public function testActionGroupMissingAnnotationsNoWarning()
85+
{
86+
// Action Group Data, missing page and description
87+
$testAnnotations = [];
88+
// Perform Test
89+
$extractor = new ActionGroupAnnotationExtractor();
90+
$extractor->extractAnnotations($testAnnotations, "fileName");
91+
92+
// Asserts
93+
TestLoggingUtil::getInstance()->validateMockLogEmpty();
94+
}
95+
96+
/**
97+
* After class functionality
98+
* @return void
99+
*/
100+
public static function tearDownAfterClass()
101+
{
102+
TestLoggingUtil::getInstance()->clearMockLoggingUtil();
103+
}
104+
}

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<?php
2+
/**
3+
* Copyright © Magento, Inc. All rights reserved.
4+
* See COPYING.txt for license details.
5+
*/
6+
7+
namespace Tests\unit\Magento\FunctionalTestFramework\Test\Handlers;
8+
9+
use Magento\FunctionalTestingFramework\Exceptions\TestFrameworkException;
10+
use Magento\FunctionalTestingFramework\Util\MagentoTestCase;
11+
use Magento\FunctionalTestingFramework\Util\DocGenerator;
12+
use tests\unit\Util\ActionGroupObjectBuilder;
13+
14+
class DocGeneratorTest extends MagentoTestCase
15+
{
16+
const DOC_FILENAME = "documentation";
17+
18+
/**
19+
* Basic test to check creation of documentation
20+
*
21+
* @throws \Exception
22+
*/
23+
public function testBasicCreateDocumentation()
24+
{
25+
$annotations = [
26+
"page" => "somePage",
27+
"description" => "someDescription"
28+
];
29+
$actionGroupUnderTest = (new ActionGroupObjectBuilder())
30+
->withAnnotations($annotations)
31+
->withFilename("filename")
32+
->build();
33+
$docGenerator = new DocGenerator();
34+
$docGenerator->createDocumentation(
35+
[$actionGroupUnderTest->getName() => $actionGroupUnderTest],
36+
DOCS_OUTPUT_DIR,
37+
true
38+
);
39+
40+
$docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
41+
42+
$this->assertTrue(file_exists($docFile));
43+
44+
$this->assertFileEquals(
45+
RESOURCE_DIR . DIRECTORY_SEPARATOR . "basicDocumentation.txt",
46+
$docFile
47+
);
48+
}
49+
50+
/**
51+
* Test to check creation of documentation when overwriting previous
52+
*
53+
* @throws \Exception
54+
*/
55+
public function testCreateDocumentationWithOverwrite()
56+
{
57+
$annotations = [
58+
"page" => "somePage",
59+
"description" => "someDescription"
60+
];
61+
$actionGroupUnderTest = (new ActionGroupObjectBuilder())
62+
->withAnnotations($annotations)
63+
->withFilename("filename")
64+
->build();
65+
$docGenerator = new DocGenerator();
66+
$docGenerator->createDocumentation(
67+
[$actionGroupUnderTest->getName() => $actionGroupUnderTest],
68+
DOCS_OUTPUT_DIR,
69+
true
70+
);
71+
72+
$annotations = [
73+
"page" => "alteredPage",
74+
"description" => "alteredDescription"
75+
];
76+
$actionGroupUnderTest = (new ActionGroupObjectBuilder())
77+
->withAnnotations($annotations)
78+
->withFilename("filename")
79+
->build();
80+
$docGenerator = new DocGenerator();
81+
$docGenerator->createDocumentation(
82+
[$actionGroupUnderTest->getName() => $actionGroupUnderTest],
83+
DOCS_OUTPUT_DIR,
84+
true
85+
);
86+
87+
$docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
88+
89+
$this->assertTrue(file_exists($docFile));
90+
91+
$this->assertFileEquals(
92+
RESOURCE_DIR . DIRECTORY_SEPARATOR . "alteredDocumentation.txt",
93+
$docFile
94+
);
95+
}
96+
97+
/**
98+
* Test for existing documentation without clean
99+
*
100+
* @throws \Exception
101+
*/
102+
public function testCreateDocumentationNotCleanException()
103+
{
104+
$annotations = [
105+
"page" => "somePage",
106+
"description" => "someDescription"
107+
];
108+
$actionGroupUnderTest = (new ActionGroupObjectBuilder())
109+
->withAnnotations($annotations)
110+
->withFilename("filename")
111+
->build();
112+
$docGenerator = new DocGenerator();
113+
$docGenerator->createDocumentation(
114+
[$actionGroupUnderTest->getName() => $actionGroupUnderTest],
115+
DOCS_OUTPUT_DIR,
116+
true
117+
);
118+
119+
$docFile = DOCS_OUTPUT_DIR . DIRECTORY_SEPARATOR . self::DOC_FILENAME . ".md";
120+
121+
$this->expectException(TestFrameworkException::class);
122+
$this->expectExceptionMessage("$docFile already exists, please add --clean if you want to overwrite it.");
123+
124+
$docGenerator = new DocGenerator();
125+
$docGenerator->createDocumentation(
126+
[$actionGroupUnderTest->getName() => $actionGroupUnderTest],
127+
DOCS_OUTPUT_DIR,
128+
false
129+
);
130+
}
131+
}

‎dev/tests/unit/Resources/alteredDocumentation.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#Action Group Information
2+
This documentation contains a list of all action groups on the pages on which they start
3+
4+
##List of Pages
5+
- [ alteredPage ](#alteredPage)
6+
---
7+
<a name="alteredPage"></a>
8+
##alteredPage
9+
10+
###testActionGroupObject
11+
alteredDescription
12+
13+
Located in:
14+
15+
- filename
16+
***

‎dev/tests/unit/Resources/basicDocumentation.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#Action Group Information
2+
This documentation contains a list of all action groups on the pages on which they start
3+
4+
##List of Pages
5+
- [ somePage ](#somePage)
6+
---
7+
<a name="somePage"></a>
8+
##somePage
9+
10+
###testActionGroupObject
11+
someDescription
12+
13+
Located in:
14+
15+
- filename
16+
***

‎dev/tests/unit/Util/ActionGroupObjectBuilder.php

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@ class ActionGroupObjectBuilder
2727
*/
2828
private $actionObjects = [];
2929

30+
/**
31+
* Action Group Object Builder default entity annotations.
32+
*
33+
* @var array
34+
*/
35+
private $annotations = [];
36+
3037
/**
3138
* Action Group Object Builder default entity arguments.
3239
*
@@ -41,6 +48,13 @@ class ActionGroupObjectBuilder
4148
*/
4249
private $extends = null;
4350

51+
/**
52+
* Action Group Object Builder default filenames
53+
*
54+
* @var string
55+
*/
56+
private $filename = [];
57+
4458
/**
4559
* Setter for the Action Group Object name
4660
*
@@ -53,6 +67,18 @@ public function withName($name)
5367
return $this;
5468
}
5569

70+
/**
71+
* Setter for the Action Group Object annotations
72+
*
73+
* @param array $annotations
74+
* @return ActionGroupObjectBuilder
75+
*/
76+
public function withAnnotations($annotations)
77+
{
78+
$this->annotations = $annotations;
79+
return $this;
80+
}
81+
5682
/**
5783
* Setter for the Action Group Object arguments
5884
*
@@ -89,6 +115,18 @@ public function withExtendedAction($extendedActionGroup)
89115
return $this;
90116
}
91117

118+
/**
119+
* Setter for the Action Group Object filename
120+
*
121+
* @param string $filename
122+
* @return ActionGroupObjectBuilder
123+
*/
124+
public function withFilename($filename)
125+
{
126+
$this->filename = $filename;
127+
return $this;
128+
}
129+
92130
/**
93131
* ActionGroupObjectBuilder constructor.
94132
*/
@@ -108,9 +146,11 @@ public function build()
108146
{
109147
return new ActionGroupObject(
110148
$this->name,
149+
$this->annotations,
111150
$this->arguments,
112151
$this->actionObjects,
113-
$this->extends
152+
$this->extends,
153+
$this->filename
114154
);
115155
}
116156
}

0 commit comments

Comments
 (0)