Documentation for run integration test on local computer

[integration/test.git] / docs / run-test-locally.rst

diff --git a/docs/run-test-locally.rst b/docs/run-test-locally.rst
new file mode 100644 (file)
index 0000000..fee9834
--- /dev/null
+++ b/docs/run-test-locally.rst
@@ -0,0 +1,102 @@
+Run Integration Test Locally
+============================
+
+Overview
+========
+Sometimes you might want to run some CSIT integration tests on your VM
+instead of the sandbox, this guide contains information about pre-requisites
+that need to be installed.
+
+Operating System
+----------------
+To run the integration tests you will need a Linux-type OS, like Ubuntu or
+CentOS. Setup can be done manually, or you can download a VM image with the
+pre-installed OS.
+
+Set up the integration test framework
+-------------------------------------
+
+Install Python
+______________
+
+For Debian-based distributions
+
+.. code-block::
+
+    sudo apt-get install python3
+    sudo apt-get install python3-pip
+
+Install Robot Framework and Extended Requests Library
+_____________________________________________________
+
+.. note::
+  RobotFramework installation guide can be found `here <https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html>`_
+
+  Releng/Builder CI/CD installation options can be checked inside the `integration-install-robotframework.sh <https://github.com/opendaylight/releng-builder/blob/master/jjb/integration/integration-install-robotframework.sh>`_
+
+.. code-block::
+
+  pip3 install robotframework
+  pip3 install robotframework-extendedrequestslibrary
+
+Install Libraries needed for test suites
+________________________________________
+
+.. code-block::
+
+  pip3 install alabaster Babel docutils imagesize Jinja2 lfdocs-conf
+
+Setup SSH access
+________________
+Add new user with name `jenkins` to the linux, setup home directory for this
+user. Create and add pair of ssh keys. Put them to /home/jenkins/.ssh
+
+.. note::
+  This is only applicable if you don't change a ${DEFAULT_USER} variable.
+
+Test ssh connection:
+
+.. code-block::
+
+  ssh jenkins@localhost -i /home/jenkins/.ssh/id-rsa
+
+.. warning::
+  If *Robot* can not connect through SSH, but manually connection works ok - update paramiko library:
+
+  .. code-block::
+
+    pip3 install --upgrade robotframework-sshlibrary
+    pip3 install --upgrade paramiko
+
+Run single integration test
+---------------------------
+
+Start `Karaf` and install required features.
+
+Run test:
+
+.. code-block::
+
+  robot -L debug --variable KARAF_HOME:/home/user/workspace/netconf/karaf/target/assembly/bin --variable USER_HOME:/home/jenkins --variable DEFAULT_LINUX_PROMPT:\$ --variable ODL_SYSTEM_IP:127.0.0.1 --variable ODL_SYSTEM_1_IP:127.0.0.1 --variable RESTCONFPORT:8181 --variable IS_KARAF_APPL:True ./test.robot
+
+Where
+  * *KARAF_HOME* - path to karaf directory
+  * *USER_HOME* - path to jenkins home directotry. Used by `Robot` to read id-rsa key for ssh connection. Can be set to any directory where .ssh folder with id-rsa key located
+  * *ODL_SYSTEM_IP* - IP of ODL restconf server.
+  * *ODL_SYSTEM_1_IP* (*ODL_SYSTEM_2_IP*, *ODL_SYSTEM_3_IP*) - IP`s of ODL cluster.
+  * *RESTCONFPORT* - Restconf server port. 8181 by default.
+
+Current list of parameters used by jenkins job can be found at `integration-run-test.sh <https://github.com/opendaylight/releng-builder/blob/174e01d61a9472b0b25da8d05d7c56bfb5589809/jjb/integration/integration-run-test.sh#L40>`_ script.
+
+Full list of variables available from the CSIT is configured under the `Variables.robot <https://github.com/opendaylight/integration-test/blob/master/csit/variables/Variables.robot>`_
+
+.. note::
+  Every suite can have different options. Please check Jenkins configuration for the specific test.
+
+Getting result
+--------------
+
+On test finish, test result will be in the same folder as `Robot` test file:
+  - report.html
+  - log.html
+  - output.xml