MQE-1639: [DEVDOCS] Best Practices for including HTML Source in Tests

- Add content about encoding HTML for use in tests

Author: tomreece

docs/test/actions.md

@@ -179,6 +179,18 @@ The following test actions handle data entities using [metadata](../metadata.md)
 
 Learn more in [Handling a REST API response](../metadata.md#rest-response).
 
+## Actions specifying HTML values
+
+To use HTML in actions you must encode the HTML string using a tool. We recommend [CyberChef](https://gchq.github.io/CyberChef/#recipe=To_HTML_Entity(false,'Numeric%20entities')). Using CyberChef or a similar tool is easy. You just need to enter in your HTML string, copy the encoded result, and paste that value into your MFTF test.
+
+For example, we want to ensure we don't see this HTML: `<h1 class="login-header">`
+
+After passing `<h1 class="login-header">` through CyberChef we get `&#60;h1 class&#61;&#34;login-header&#34;&#62;` which can be used in a test like:
+
+```xml
+<dontSeeInSource html="&#60;h1 class&#61;&#34;login-header&#34;&#62;" stepKey="dontSeeInSource"/>
+```
+
 ## Reference
 
 The following list contains reference documentation about all action elements available in the MFTF.
@@ -868,17 +880,19 @@ See [dontSeeInSource docs on codeception.com](http://codeception.com/docs/module
 
 Attribute|Type|Use|Description
 ---|---|---|---
-`html`|string|optional| HTML code to search for within the source code.
+`html`|string|optional| HTML code to search for within the source code. The value must be encoded. See example.
 `stepKey`|string|required| A unique identifier of the action.
 `skipReadiness`|boolean|optional| A flag to skip the readiness check.
 `before`|string|optional| `stepKey` of action that must be executed next.
 `after`|string|optional| `stepKey` of preceding action.
 
 #### Example
 
+You must encode the `html` using a tool such as [CyberChef](https://gchq.github.io/CyberChef/#recipe=To_HTML_Entity(false,'Numeric%20entities')).
+
 ```xml
-<!-- Verify that the page does not contain the raw source code `<h1>Sample text</h1>`. -->
-<dontSeeInSource userInput="<h1>Sample text</h1>" stepKey="dontSeeInSource"/>
+<!-- Verify that the page does not contain the raw source code `<h1 class="login-header">`. -->
+<dontSeeInSource html="&#60;h1 class&#61;&#34;login-header&#34;&#62;" stepKey="dontSeeInSource"/>
 ```
 
 ### dontSeeInTitle
@@ -1922,17 +1936,19 @@ See [seeInPageSource docs on codeception.com](http://codeception.com/docs/module
 
 Attribute|Type|Use|Description
 ---|---|---|---
-`html`|string|optional| HTML code to be searched for within the document.
+`html`|string|optional| HTML code to be searched for within the document. The value must be encoded. See example.
 `stepKey`|string|required| A unique identifier of the action.
 `skipReadiness`|boolean|optional| A flag to skip the readiness check.
 `before`|string|optional| `stepKey` of action that must be executed next.
 `after`|string|optional| `stepKey` of preceding action.
 
 #### Example
 
+You must encode the `html` using a tool such as [CyberChef](https://gchq.github.io/CyberChef/#recipe=To_HTML_Entity(false,'Numeric%20entities')).
+
 ```xml
-<!-- Verify that the page source contains the string "Sample text". -->
-<seeInPageSource userInput="Sample text" stepKey="seeInPageSource"/>
+<!-- Verify that the page source contains the raw source code `<h1 class="login-header">`. -->
+<seeInPageSource html="&#60;h1 class&#61;&#34;login-header&#34;&#62;" stepKey="seeInPageSource"/>
 ```
 
 ### seeInPopup
@@ -1960,17 +1976,19 @@ See [seeInSource docs on codeception.com](http://codeception.com/docs/modules/We
 
 Attribute|Type|Use|Description
 ---|---|---|---
-`html`|string|optional| HTML code to be searched for within the page source.
+`html`|string|optional| HTML code to be searched for within the page source. The value must be encoded. See example.
 `stepKey`|string|required| A unique identifier of the action.
 `skipReadiness`|boolean|optional| A flag to skip the readiness check.
 `before`|string|optional| `stepKey` of action that must be executed next.
 `after`|string|optional| `stepKey` of preceding action.
 
 #### Example
 
+You must encode the `html` using a tool such as [CyberChef](https://gchq.github.io/CyberChef/#recipe=To_HTML_Entity(false,'Numeric%20entities')).
+
 ```xml
-<!-- Verify that the page does contains the raw source code `<h1>Sample text</h1>`. -->
-<seeInSource userInput="<h1>Sample text</h1>" stepKey="seeInSource"/>
+<!-- Verify that the page does contains the raw source code `<h1 class="login-header">`. -->
+<seeInSource html="&#60;h1 class&#61;&#34;login-header&#34;&#62;" stepKey="seeInSource"/>
 ```
 
 ### seeInTitle