From ec3f086c475c44baa747c1bf8d31609e76b013d9 Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Thu, 30 Apr 2020 14:42:12 -0500 Subject: [PATCH 1/4] MQE-2034: Document Custom Helper functionality --- docs/custom-helpers.md | 125 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/custom-helpers.md diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md new file mode 100644 index 000000000..a83249b2e --- /dev/null +++ b/docs/custom-helpers.md @@ -0,0 +1,125 @@ +# Custom Helpers + +
+Due to complexity, you should only write new Custom Helpers as a last resort after trying to implement your test using built-in actions. +
+ +Custom Helpers allow test writers to write custom test actions to solve for advanced requirements beyond what MFTF offers out of the box. + +In MFTF version 3.0.0, we removed the following test actions: + +* `` +* `` + +These actions were removed because they allowed custom PHP code to be written inline inside of XML files. This code was difficult to read. It had no proper syntax highlighting and no linting. It was difficult to maintain, troubleshoot, and modify. + +However, sometimes custom logic beyond what MFTF offers is necessary so we have provided an alternative solution: the `` action. + +## Example + +Custom Helpers are implemented in PHP files that must be placed in this directory: +``` +/Test/Mftf/Helper +``` + +Let's take a look at one. This Custom Helper selects text on the page by this approach: + +1. Move to a very specific X,Y starting position +2. Click and hold the mouse button down +3. Move to another specific X,Y position +4. Release the mouse button + +This functionality is used to select text on the page and cannot be accomplished using built-in test actions. + +### PHP File + +```php +getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver'); + + $contextElement = $webDriver->webDriver->findElement(\Facebook\WebDriver\WebDriverBy::xpath($context)); + $actions = new \Facebook\WebDriver\Interactions\WebDriverActions($webDriver->webDriver); + $actions->moveToElement($contextElement, $startX, $startY) + ->clickAndHold() + ->moveToElement($contextElement, $endX, $endY) + ->release() + ->perform(); + } catch (\Exception $e) { + $this->fail($e->getMessage()); + } + } +} +``` + +### Notes About The PHP File + +The following details are important about the file above: +1. The `namespace` must match the file location like `namespace Magento\PageBuilder\Test\Mftf\Helper;` +2. The class must `extends Helper` and have the corresponding `use` statement to match +3. You can get access to the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')` +4. You can implement multiple related methods in the same class. + +You should follow the same patterns in any Custom Helpers that you write yourself. But you can implement any logic or iteration that you need to solve for your use case. + +### Referencing In A Test + +Once you have implemented something like the above PHP file. You can then reference it in a test like this: + +```xml + + //div[contains(@class, 'inline-wysiwyg')]//h2 + {{TinyMCEPartialHeadingSelection.startX}} + {{TinyMCEPartialHeadingSelection.startY}} + {{TinyMCEPartialHeadingSelection.endX}} + {{TinyMCEPartialHeadingSelection.endY}} + +``` + +### Notes About The XML + +1. Specify an argument value for every argument that matches our PHP implementation. This allows us to pass other test data to the Custom Helper. +2. The `class` attribute matches the namespace we specified in the PHP file +3. You can specify the method from the class via the `method` attribute +4. If the function has a return value, it will be assigned to the stepKey variable. In this case `$selectHeadingTextInTinyMCE` would hold the return value. + +## Key Takeaways + +Custom Helpers allow you to solve for complex use cases such as conditional logic, iteration, or complex WebDriver usage. + +With access to the WebDriver object, you have a lot of flexibility available to you. See the [Codeception WebDriver](https://github.com/Codeception/module-webdriver/blob/master/src/Codeception/Module/WebDriver.php) for technical details and functionality available for use. + +A Custom Helper is written in a PHP file and then referenced in test XML like other actions. + +Due to complexity, you should only use these as a last resort after trying to implement your test using built-in actions. + +## References + +[Codeception WebDriver source code](https://github.com/Codeception/module-webdriver/blob/master/src/Codeception/Module/WebDriver.php) - Reference for using the WebDriver Object From 04bc005bb8bb9e1674caebaff9e36e539b01f94b Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Thu, 30 Apr 2020 14:48:37 -0500 Subject: [PATCH 2/4] MQE-2034: Document Custom Helper functionality --- docs/custom-helpers.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md index a83249b2e..a38be1e8d 100644 --- a/docs/custom-helpers.md +++ b/docs/custom-helpers.md @@ -86,6 +86,7 @@ The following details are important about the file above: 2. The class must `extends Helper` and have the corresponding `use` statement to match 3. You can get access to the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')` 4. You can implement multiple related methods in the same class. +5. Specify the correct function argument types to match the types of the values you want to pass in. In this case we specified `string $context, int $startX, int $startY, int $endX, int $endY` so in the XML we will match these types. You should follow the same patterns in any Custom Helpers that you write yourself. But you can implement any logic or iteration that you need to solve for your use case. @@ -109,6 +110,7 @@ Once you have implemented something like the above PHP file. You can then refere 2. The `class` attribute matches the namespace we specified in the PHP file 3. You can specify the method from the class via the `method` attribute 4. If the function has a return value, it will be assigned to the stepKey variable. In this case `$selectHeadingTextInTinyMCE` would hold the return value. +5. The types of argument values must match the PHP implementation's expected types. ## Key Takeaways From 9f710db73fe8462a96392c0b338c710dd4403633 Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Fri, 1 May 2020 12:24:36 -0500 Subject: [PATCH 3/4] Grammar and formatting --- docs/custom-helpers.md | 64 ++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md index a38be1e8d..950bccfa7 100644 --- a/docs/custom-helpers.md +++ b/docs/custom-helpers.md @@ -1,15 +1,15 @@ # Custom Helpers -
-Due to complexity, you should only write new Custom Helpers as a last resort after trying to implement your test using built-in actions. +
+Due to complexity, you should only write new custom helpers as a last resort, after trying to implement your test using built-in actions.
-Custom Helpers allow test writers to write custom test actions to solve for advanced requirements beyond what MFTF offers out of the box. +Custom Helpers allow test writers to write custom test actions to solve advanced requirements beyond what MFTF offers out of the box. -In MFTF version 3.0.0, we removed the following test actions: +In MFTF version 3.0.0, the following test actions were removed: -* `` -* `` +* `` +* `` These actions were removed because they allowed custom PHP code to be written inline inside of XML files. This code was difficult to read. It had no proper syntax highlighting and no linting. It was difficult to maintain, troubleshoot, and modify. @@ -17,17 +17,18 @@ However, sometimes custom logic beyond what MFTF offers is necessary so we have ## Example -Custom Helpers are implemented in PHP files that must be placed in this directory: -``` +Custom helpers are implemented in PHP files that must be placed in this directory: + +```text /Test/Mftf/Helper ``` -Let's take a look at one. This Custom Helper selects text on the page by this approach: +This custom helper selects text on the page with this approach: -1. Move to a very specific X,Y starting position -2. Click and hold the mouse button down -3. Move to another specific X,Y position -4. Release the mouse button +1. Move to a very specific X,Y starting position. +1. Click and hold the mouse button down. +1. Move to another specific X,Y position. +1. Release the mouse button. This functionality is used to select text on the page and cannot be accomplished using built-in test actions. @@ -79,20 +80,21 @@ class SelectText extends Helper } ``` -### Notes About The PHP File +### Notes about this PHP file + +The following details are important about the above file: -The following details are important about the file above: -1. The `namespace` must match the file location like `namespace Magento\PageBuilder\Test\Mftf\Helper;` -2. The class must `extends Helper` and have the corresponding `use` statement to match -3. You can get access to the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')` -4. You can implement multiple related methods in the same class. -5. Specify the correct function argument types to match the types of the values you want to pass in. In this case we specified `string $context, int $startX, int $startY, int $endX, int $endY` so in the XML we will match these types. +1. The `namespace` must match the file location: `namespace Magento\PageBuilder\Test\Mftf\Helper;` +2. The class must `extends Helper` and have the corresponding `use` statement to match. +3. You may access the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')`. +4. You may implement multiple related methods within the same class. +5. Specify the correct function argument types to match the type of values you want to pass in. In this case, we specified `string $context, int $startX, int $startY, int $endX, int $endY`. In the XML we will match these types. -You should follow the same patterns in any Custom Helpers that you write yourself. But you can implement any logic or iteration that you need to solve for your use case. +You should follow the same patterns in any custom helpers that you write yourself, but you may implement any logic or iteration that you need to solve for your use case. -### Referencing In A Test +### Referencing in a test -Once you have implemented something like the above PHP file. You can then reference it in a test like this: +Once you have implemented something like the above PHP file, reference it in a test: ```xml @@ -104,23 +106,23 @@ Once you have implemented something like the above PHP file. You can then refere ``` -### Notes About The XML +### Notes about the XML 1. Specify an argument value for every argument that matches our PHP implementation. This allows us to pass other test data to the Custom Helper. -2. The `class` attribute matches the namespace we specified in the PHP file -3. You can specify the method from the class via the `method` attribute -4. If the function has a return value, it will be assigned to the stepKey variable. In this case `$selectHeadingTextInTinyMCE` would hold the return value. +2. The `class` attribute matches the namespace specified in the PHP file. +3. Specify the method from the class via the `method` attribute. +4. If the function has a return value, it will be assigned to the `stepKey` variable. In this case, `$selectHeadingTextInTinyMCE` holds the return value. 5. The types of argument values must match the PHP implementation's expected types. -## Key Takeaways +## Key takeaways -Custom Helpers allow you to solve for complex use cases such as conditional logic, iteration, or complex WebDriver usage. +Custom helpers allow you to solve complex use cases such as conditional logic, iteration, or complex WebDriver usage. With access to the WebDriver object, you have a lot of flexibility available to you. See the [Codeception WebDriver](https://github.com/Codeception/module-webdriver/blob/master/src/Codeception/Module/WebDriver.php) for technical details and functionality available for use. -A Custom Helper is written in a PHP file and then referenced in test XML like other actions. +A custom helper is written in a PHP file and then referenced in test XML, like other actions. -Due to complexity, you should only use these as a last resort after trying to implement your test using built-in actions. +You should only use these as a last resort after trying to implement your test using built-in actions. ## References From c57f3694dbae6e7592349a43c1857ecabaa02e10 Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Fri, 1 May 2020 12:25:36 -0500 Subject: [PATCH 4/4] Formatting --- docs/custom-helpers.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/custom-helpers.md b/docs/custom-helpers.md index 950bccfa7..bf1ebc572 100644 --- a/docs/custom-helpers.md +++ b/docs/custom-helpers.md @@ -109,10 +109,10 @@ Once you have implemented something like the above PHP file, reference it in a t ### Notes about the XML 1. Specify an argument value for every argument that matches our PHP implementation. This allows us to pass other test data to the Custom Helper. -2. The `class` attribute matches the namespace specified in the PHP file. -3. Specify the method from the class via the `method` attribute. -4. If the function has a return value, it will be assigned to the `stepKey` variable. In this case, `$selectHeadingTextInTinyMCE` holds the return value. -5. The types of argument values must match the PHP implementation's expected types. +1. The `class` attribute matches the namespace specified in the PHP file. +1. Specify the method from the class via the `method` attribute. +1. If the function has a return value, it will be assigned to the `stepKey` variable. In this case, `$selectHeadingTextInTinyMCE` holds the return value. +1. The types of argument values must match the PHP implementation's expected types. ## Key takeaways