Added a note in 4.1.1.5 Running Python Unit-Test Suite (AFTH)

Added the new section 4.1.25 Custom Script full example (AFTH)
Added the new section 3.4 Custom Scripts basic test (Test Spec).

Change-Id: I729768eb72417264b1a286638372a584361a7e33
Signed-off-by: mrpa <miruna.paun@enea.com>

2 files changed, 218 insertions, 4 deletions

diff --git a/doc/book-enea-nfv-access-auto-fw-th-user-guide/doc/automation_framework_test_harness.xml b/doc/book-enea-nfv-access-auto-fw-th-user-guide/doc/automation_framework_test_harness.xml
index 4ab9cd1..fd21087 100644
--- a/doc/book-enea-nfv-access-auto-fw-th-user-guide/doc/automation_framework_test_harness.xml
+++ b/doc/book-enea-nfv-access-auto-fw-th-user-guide/doc/automation_framework_test_harness.xml
@@ -343,6 +343,12 @@ NOTSET 0</programlisting></para>
       <section id="run_ut_suite">
         <title>Running Python Unit-Test Suite</title>
 
+        <note>
+          <para>Please update all JSON configuration files to use the name of
+          your vCPE agent device. In the following chapters, intelc3850-2 is
+          used as an example.</para>
+        </note>
+
         <para>Below you'll find sample unit-test command line options for
         running the Fortigate <emphasis role="bold">deployment</emphasis>
         scenario:</para>
@@ -2407,6 +2413,126 @@ phase always-after-startup from inteld1521-6
       </section>
     </section>
 
+    <section id="custom_script_eg">
+      <title>Custom Script - Full Example</title>
+
+      <para>All Python API used in this example are described in detail in the following sections.</para>
+
+      <para>The list of custom scripts can be found in
+      <literal>&lt;AF-TH-install-dir&gt;/lab_config/customScripts</literal>:</para>
+
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para><filename>test_fail_after_always</filename>. Phase:
+          always-after-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_fail_after_once</filename>. Phase:
+          once-after-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_fail_before_always</filename>. Phase:
+          always-before-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_fail_before_once</filename>. Phase:
+          once-before-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_success_after_always</filename>. Phase:
+          always-after-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_success_after_once</filename>. Phase:
+          once-after-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_success_before_always</filename>. Phase:
+          always-before-startup.</para>
+        </listitem>
+
+        <listitem>
+          <para><filename>test_success_before_once</filename>. Phase:
+          once-before-startup.</para>
+        </listitem>
+      </itemizedlist>
+
+      <note>
+        <para>The following example uses the
+        <filename>test_success_after_always</filename> custom script.</para>
+      </note>
+
+      <section id="upload_customscrp_ucpemg">
+        <title>Uploading a Custom Script to the uCPE Manager</title>
+
+        <programlisting>$ python automation_framework/customScripts/upload.py \
+-f lab_config/customScripts/test_success_after_always -e always-after-startup
+2020-04-14 14:08:02,824 - DEBUG: Started logging
+2020-04-14 14:08:02,915 - INFO: Upload Custom Script
+2020-04-14 14:08:02,994 - DEBUG: Login successful on host '172.24.3.109'
+2020-04-14 14:08:02,995 - DEBUG: Session token is: 97544990-7e48-11ea-835c-02423a1c239f
+2020-04-14 14:08:02,996 - DEBUG: Upload test_success_after_always to uCPE Manager. \
+Content: #!/bin/bash
+echo test_success_after_always
+2020-04-14 14:08:03,138 - INFO: Done
+2020-04-14 14:08:03,169 - DEBUG: Logging out and exiting...</programlisting>
+      </section>
+
+      <section id="upload_customscrp_device">
+        <title>Uploading a Custom Script from the uCPE Manager to a
+        Device</title>
+
+        <programlisting>$ python automation_framework/customScripts/uploadOnDevice.py -c \
+test_success_after_always -e always-after-startup -n inteld1521-6
+2020-04-14 14:26:26,205 - DEBUG: Started logging
+2020-04-14 14:26:26,206 - INFO: Upload Custom Script on Device
+2020-04-14 14:26:26,251 - DEBUG: Login successful on host '172.24.3.109'
+2020-04-14 14:26:26,252 - DEBUG: Session token is: 28ebcb10-7e4b-11ea-835c-02423a1c239f
+2020-04-14 14:26:26,286 - DEBUG: Found device with name 'inteld1521-6'
+2020-04-14 14:26:26,287 - DEBUG: Upload test_success_after_always to inteld1521-6
+2020-04-14 14:26:26,314 - INFO: Done
+2020-04-14 14:26:26,341 - DEBUG: Logging out and exiting...</programlisting>
+      </section>
+
+      <section id="removing_customscrp_device">
+        <title>Removing a Custom Script from a Device</title>
+
+        <programlisting>$ python automation_framework/customScripts/deleteOnDevice.py -c \
+test_success_after_always -e always-after-startup -n inteld1521-6
+2020-04-14 14:33:52,288 - DEBUG: Started logging
+2020-04-14 14:33:52,288 - INFO: Delete Custom Script on Device
+2020-04-14 14:33:52,327 - DEBUG: Login successful on host '172.24.3.109'
+2020-04-14 14:33:52,327 - DEBUG: Session token is: 32cde4f0-7e4c-11ea-835c-02423a1c239f
+2020-04-14 14:33:52,349 - DEBUG: Found device with name 'inteld1521-6'
+2020-04-14 14:33:52,349 - DEBUG: Delete test_success_after_always, \
+phase always-after-startup from inteld1521-6
+2020-04-14 14:33:52,373 - INFO: Done
+2020-04-14 14:33:52,391 - DEBUG: Logging out and exiting...</programlisting>
+      </section>
+
+      <section id="remove_customscrp_ucpemg">
+        <title>Removing a Custom Script from the uCPE Manager</title>
+
+        <programlisting>$ python automation_framework/customScripts/delete.py -c \
+test_success_after_always -e always-after-startup
+2020-04-14 14:39:22,042 - DEBUG: Started logging
+2020-04-14 14:39:22,042 - INFO: Delete Custom Script on uCPE Manager
+2020-04-14 14:39:22,081 - DEBUG: Login successful on host '172.24.3.109'
+2020-04-14 14:39:22,082 - DEBUG: Session token is: f75a83a0-7e4c-11ea-835c-02423a1c239f
+2020-04-14 14:39:22,099 - DEBUG: Found custom script: 'test_success_after_always'
+2020-04-14 14:39:22,099 - DEBUG: Delete script test_success_after_always, \
+phase always-after-startup from uCPE Manager
+2020-04-14 14:39:22,118 - INFO: Done
+2020-04-14 14:39:22,135 - DEBUG: Logging out and exiting...</programlisting>
+      </section>
+    </section>
+
     <section id="add_offline_config_store">
       <title>Adding an Offline Configuration Store</title>
 
diff --git a/doc/book-enea-nfv-access-system-test-specification/doc/sample_test_cases.xml b/doc/book-enea-nfv-access-system-test-specification/doc/sample_test_cases.xml
index f4b2fc7..2fa087b 100644
--- a/doc/book-enea-nfv-access-system-test-specification/doc/sample_test_cases.xml
+++ b/doc/book-enea-nfv-access-system-test-specification/doc/sample_test_cases.xml
@@ -1502,8 +1502,8 @@ FortigateFWInstance tested successfully!</programlisting></para>
                 targetptr="fortigate_firewall_uc_1">FortiGate VNF as a
                 Firewall in the <ns:include
                 href="../../s_docbuild/olinkdb/pardoc-names.xml"
-                xpointer="element(book_enea_nfv_access_example_usecases/1)"
-                xmlns:ns="http://www.w3.org/2001/XInclude" /></olink>
+                xmlns:ns="http://www.w3.org/2001/XInclude"
+                xpointer="element(book_enea_nfv_access_example_usecases/1)" /></olink>
                 Manual.</para>
               </listitem>
 
@@ -1512,8 +1512,8 @@ FortigateFWInstance tested successfully!</programlisting></para>
                 targetdoc="book_enea_nfv_access_auto_fw_th_user_guide"
                 targetptr="python_testsuite">Python Unit-Test Suite in
                 <ns:include href="../../s_docbuild/olinkdb/pardoc-names.xml"
-                xpointer="element(book_enea_nfv_access_auto_fw_th_user_guide/1)"
-                xmlns:ns="http://www.w3.org/2001/XInclude" /></olink>.</para>
+                xmlns:ns="http://www.w3.org/2001/XInclude"
+                xpointer="element(book_enea_nfv_access_auto_fw_th_user_guide/1)" /></olink>.</para>
               </listitem>
             </itemizedlist>
           </listitem>
@@ -1714,4 +1714,92 @@ LAN-to-LAN connectivity (through VPN tunnel)tested successfully!</programlisting
 -e "site1=inteld1521-1 site2=inteld1521-2 arch=XeonD"</programlisting></para>
     </section>
   </section>
+
+  <section id="custom_scripts_bt">
+    <title>Custom Scripts - Basic Test</title>
+
+    <para>The basic test script can be found in
+    <literal>&lt;AF-TH-install-dir&gt;/playbooks/customScripts/basicTest.yml</literal>.</para>
+
+    <para>The <filename>basicTest.yml</filename> script requires the following
+    steps:</para>
+
+    <orderedlist spacing="compact">
+      <listitem>
+        <para>Upload a Custom Script onto the uCPE Manager.</para>
+      </listitem>
+
+      <listitem>
+        <para>Upload the Custom Script onto a Device.</para>
+      </listitem>
+
+      <listitem>
+        <para>Reboot the Device.</para>
+      </listitem>
+
+      <listitem>
+        <para>Wait for the Device to be up and running.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remove the Custom Script from the Device.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remove the Custom Script from the uCPE Manager.</para>
+      </listitem>
+    </orderedlist>
+
+    <para><emphasis role="bold">Preconditions:</emphasis></para>
+
+    <itemizedlist>
+      <listitem>
+        <para>A device must have been previously added and connected to the
+        uCPE Manager.</para>
+      </listitem>
+
+      <listitem>
+        <para>The device JSON configuration file must have been created:
+        <filename>&lt;AF-TH-install-dir&gt;/lab_config/&lt;Device-name&gt;/&lt;Device-name&gt;.json</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <para>The custom script should have been previously saved in 
+          <literal>&lt;AF-TH-install-dir&gt;/lab_config/customScripts</literal>.</para>
+      </listitem>
+      
+      <listitem>
+        <para>Add device settings in the <literal>hosts</literal> Ansible inventory file under 
+          <literal>[customScriptDevice]</literal> and remove the <literal>inteld1521-1</literal>
+          example.</para>
+      </listitem>
+    </itemizedlist>
+    
+    <para><emphasis role="bold">Example:</emphasis></para>
+    
+    <programlisting>[customScriptDevice]
+inteld1521-1 ansible_host=172.24.12.73 ansible_port=22 ansible_user=root \
+      ansible_pass=root</programlisting>
+    
+    <para><emphasis role="bold">Action:</emphasis> Run
+    <filename>basicTest.yml</filename> (example data for
+    <filename>test_success_after_always</filename>):</para>
+
+    <programlisting>ansible-playbook playbooks/customScripts/basicTest.yml -e "device=&lt;Device-name&gt;" \
+-e "scriptName=test_success_after_always" -e "phase=always-after-startup" \
+-e "expectedStatus=success"</programlisting>
+
+    <para><emphasis role="bold">Result:</emphasis> Output of
+    <filename>basicTest.yml</filename>:</para>
+
+    <programlisting>test_success_after_always was uploaded to uCPE Manager!
+test_success_after_always was uploaded to &lt;Device-name&gt;!
+
+&lt;Device-name&gt; device is connected!
+test_success_after_always from phase always-after-startup was removed \
+from &lt;Device-name&gt;!
+
+test_success_after_always from phase always-after-startup was removed \
+from uCPE Manager!</programlisting>
+  </section>
 </chapter>
\ No newline at end of file