Merge "Update Configuration guide"

2 files changed, 148 insertions, 88 deletions

diff --git a/docs/configguide/configguide.rst b/docs/configguide/configguide.rst
index ea5b01ea..c03760c5 100644
--- a/docs/configguide/configguide.rst
+++ b/docs/configguide/configguide.rst
@@ -30,9 +30,9 @@ following docker command::
 
   [functester@jumphost ~]$ docker images
   REPOSITORY     TAG             IMAGE ID      CREATED      SIZE
-  opnfv/functest latest          8cd6683c32ae  2 weeks ago  1.611 GB
-  opnfv/functest colorado.1.0    94b78faa94f7  4 weeks ago  874.9 MB
-  hello-world    latest          94df4f0ce8a4  7 weeks ago    967 B
+  opnfv/functest latest          8cd6683c32ae  2 weeks ago  1.321 GB
+  opnfv/functest danube.1.0    13fa54a1b238  4 weeks ago  1.29 GB
+  opnfv/functest colorado.1.0    94b78faa94f7  9 weeks ago  968 MB
 
 The Functest docker container environment can -in principle- be also
 used with non-OPNFV official installers (e.g. 'devstack'), with the
@@ -104,10 +104,14 @@ recommended parameters for invoking docker container
        -e "INSTALLER_TYPE=<type>"
        # Use one of following apex, compass, fuel or joid
 
-  #. Functest needs to know the IP of the installer::
+  #. Functest needs to know the IP of some installers::
 
        -e "INSTALLER_IP=<Specific IP Address>"
 
+       This IP is needed to fetch RC file from deployment, fetch logs, ...
+       If not provided, there is no way to fetch the RC file. It must be
+       provided manually as a volume
+
   #. Credentials for accessing the Openstack.
      Most convenient way of passing them to container is by having a
      local copy of the credentials file in Jumphost and then using the
@@ -138,13 +142,24 @@ recommended parameters for invoking docker container
                 If several features are pertinent then use the underscore
                 character '_' to separate each feature (e.g. ovs_kvm)
                 'nofeature' indicates no NFV feature is deployed
-       ha_mode is one of ( ha | noha )
+       ha_mode (high availability) is one of ( ha | noha )
 
      **NOTE:** Not all possible combinations of "DEPLOY_SCENARIO" are
      supported. The name passed in to the Functest Docker container
      must match the scenario used when the actual OPNFV platform was
      deployed. See release note to see the list of supported scenarios.
 
+     **NOTE:** The scenario name is mainly used to automatically detect
+     if a test suite is runnable or not (e.g. it will prevent ONOS test suite
+     to be run on ODL scenarios). If not set, Functest will try to run the
+     default test cases that might not include SDN controller or a specific
+     feature
+
+     **NOTE:** A HA scenario means that 3 OpenStack controller nodes are
+     deployed. It does not necessarily mean that the whole system is HA. See
+     installer release notes for details.
+
+
 Putting all above together, when using installer 'fuel' and an invented
 INSTALLER_IP of '10.20.0.2', the recommended command to create the
 Functest Docker container is as follows::
@@ -311,14 +326,25 @@ should now be in place::
         |   `-- results
         `-- repos
             |-- bgpvpn
+            |-- copper
             |-- doctor
+            |-- domino
             |-- functest
-            |-- odl_integration
+            |-- kingbird
+            |-- moon
+            |-- odl_test
             |-- onos
+            |-- ovno
+            |-- parser
             |-- promise
             |-- rally
             |-- releng
-            `-- vims-test
+            |-- sdnvpn
+            |-- securityscanning
+            |-- sfc
+            |-- tempest
+            |-- vims_test
+            `-- vnfs
 
 Underneath the '/home/opnfv/' directory, the Functest docker container
 includes two main directories:
@@ -339,24 +365,10 @@ follows::
 
   . |-- INFO
     |-- LICENSE
-    |-- __init__.py
-    |-- ci
-    |   |-- __init__.py
-    |   |-- check_os.sh
-    |   |-- config_functest.yaml
-    |   |-- generate_report.py
-    |   |-- exec_test.sh
-    |   |-- prepare_env.py
-    |   |-- run_tests.py
-    |   |-- testcases.yaml
-    |   |-- tier_builder.py
-    |   `-- tier_handler.py
-    |-- cli
-    |   |-- __init__.py
-    |   |-- cli_base.py
-    |   |-- commands
-    |   |-- functest-complete.sh
-    |   `-- setup.py
+    |-- requirements.txt
+    |-- run_unit_tests.sh
+    |-- setup.py
+    |-- test-requirements.txt
     |-- commons
     |   |-- ims
     |   |-- mobile
@@ -364,50 +376,96 @@ follows::
     |-- docker
     |   |-- Dockerfile
     |   |-- config_install_env.sh
-    |   `-- requirements.pip
+    |   `-- docker_remote_api
     |-- docs
     |   |-- com
     |   |-- configguide
     |   |-- devguide
     |   |-- images
+    |   |-- internship
     |   |-- release-notes
     |   |-- results
     |   `--userguide
-    |-- testcases
-    |   |-- __init__.py
-    |   |-- Controllers
-    |   |-- OpenStack
-    |   |-- features
-    |   |-- security_scan
-    |   `-- vnf
-    `-- utils
+    |-- functest
         |-- __init__.py
-        |-- functest_logger.py
-        |-- functest_utils.py
-        |-- openstack_clean.py
-        |-- openstack_snapshot.py
-        `-- openstack_utils.py
+        |-- ci
+        |   |-- __init__.py
+        |   |-- check_os.sh
+        |   |-- config_functest.yaml
+        |   |-- config_patch.yaml
+        |   |-- exec_test.sh
+        |   |-- generate_report.py
+        |   |-- prepare_env.py
+        |   |-- run_tests.py
+        |   |-- testcases.yaml
+        |   |-- tier_builder.py
+        |   `-- tier_handler.py
+        |-- cli
+        |   |-- __init__.py
+        |   |-- cli_base.py
+        |   |-- commands
+        |   |-- functest-complete.sh
+        |   `-- setup.py
+        |-- core
+        |   |-- __init__.py
+        |   |-- feature_base.py
+        |   |-- pytest_suite_runner.py
+        |   |-- testcase_base.py
+        |   |-- vnf_base.py
+        |-- opnfv_tests
+        |   |-- __init__.py
+        |   |-- features
+        |   |-- mano
+        |   |-- openstack
+        |   |-- sdn
+        |   |-- security_scan
+        |   `-- vnf
+        |-- tests
+        |   |-- __init__.py
+        |   `-- unit
+        `-- utils
+            |-- __init__.py
+            |-- config.py
+            |-- constants.py
+            |-- env.py
+            |-- functest_constants.py
+            |-- functest_logger.py
+            |-- functest_utils.py
+            |-- openstack
+            |-- openstack_clean.py
+            |-- openstack_snapshot.py
+            |-- openstack_tacker.py
+            `-- openstack_utils.py
+
 
     (Note: All *.pyc files removed from above list for brevity...)
 
-We may distinguish 7 different directories:
+We may distinguish several directories, the first level has 4 directories:
+
+* **commons**: This directory is dedicated for storage of traffic
+  profile or any other test inputs that could be reused by any test
+  project.
+* **docker**: This directory includes the needed files and tools to
+  build the Funtest Docker image.
+* **docs**: This directory includes documentation: Release Notes,
+  User Guide, Configuration Guide and Developer Guide. Test results
+  are also located in a sub--directory called 'results'.
+* **functest**: This directory contains all the code needed to run
+  functest internal cases and OPNFV onboarded feature or VNF test cases.
 
+Functest directory has 6 directories:
   * **ci**: This directory contains test structure definition files
     (e.g <filename>.yaml) and bash shell/python scripts used to
     configure and execute Functional tests. The test execution script
     can be executed under the control of Jenkins CI jobs.
   * **cli**: This directory holds the python based Functest CLI utility
     source code, which is based on the Python 'click' framework.
-  * **commons**: This directory is dedicated for storage of traffic
-    profile or any other test inputs that could be reused by any test
-    project.
-  * **docker**: This directory includes the needed files and tools to
-    build the Funtest Docker container image.
-  * **docs**: This directory includes documentation: Release Notes,
-    User Guide, Configuration Guide and Developer Guide. Test results
-    are also located in a sub--directory called 'results'.
-  * **testcases**: This directory includes the scripts required by
+  * **core**: This directory holds the python based Functest core
+      source code. Three abstraction classes have been created to ease
+      the integration of internal, feature or vnf cases.
+  * **opnfv_tests**: This directory includes the scripts required by
     Functest internal test cases and other feature projects test cases.
+  * **tests**: This directory includes the functest unit tests
   * **utils**: this directory holds Python source code for some general
     purpose helper utilities, which testers can also re-use in their
     own test code. See for an example the Openstack helper utility:
@@ -452,7 +510,7 @@ It is useful sometimes to remove a container if there are some problems::
 Use the *-f* option if the container is still running, it will force to
 destroy it::
 
-  docker -f rm <CONTAINER_ID>
+  docker rm -f <CONTAINER_ID>
 
 Check the Docker documentation dockerdocs_ for more information.
 
diff --git a/docs/configguide/index.rst b/docs/configguide/index.rst
index b61bf8ff..58e8a134 100644
--- a/docs/configguide/index.rst
+++ b/docs/configguide/index.rst
@@ -9,6 +9,21 @@ OPNFV FUNCTEST Configuration Guide
    :numbered:
    :maxdepth: 2
 
+Version history
+===============
+
++------------+----------+------------------+----------------------------------+
+| **Date**   | **Ver.** | **Author**       | **Comment**                      |
+|            |          |                  |                                  |
++------------+----------+------------------+----------------------------------+
+| 2016-08-17 | 1.0.0    | Juha Haapavirta  | Colorado release                 |
+|            |          | Column Gaynor    |                                  |
++------------+----------+------------------+----------------------------------+
+| 2017-01-19 | 1.0.1    | Morgan Richomme  | Adaptations for Danube           |
+|            |          |                  | * update testcase list           |
+|            |          |                  | * update docker command          |
++------------+----------+------------------+----------------------------------+
+
 Introduction
 ============
 This document describes how to install and configure Functest in OPNFV.
@@ -43,6 +58,7 @@ follows::
  |     |   |  -- healthcheck    |   |        |       |        |       |
  |     |   |  -- vPing_ssh      |   |        |       |        |       |
  |     |   |  -- vPing_userdata |   |        |       |        |       |
+ |     |   |  -- SNAPS_cases    |   |        |       |        |       |
  |     |   |  -- Tempest_smoke  |   |        |       |        |       |
  |     |   |  -- Rally_sanity   |   |        |       |        |       |
  |     |   |  -- Tempest_full   |   |        |       |        |       |
@@ -52,12 +68,13 @@ follows::
  |     |   |  -- odl            |   |        |       |        |       |
  |     |   |  -- onos           |   |        |       |        |       |
  |     |   |                    |   |        |       |        |       |
+ |     |   | - Features         |   |        |       |        |       |
+ |     |   |                    |   |        |       |        |       |
  |     |   | - VNF              |   |        |       |        |       |
- |     |   |  -- vIMS           |   |        |       |        |       |
  |     |   |                    |   |        |       |        |       |
  |     |   +--------------------+   |        |       |        |       |
- |     |                            +-------------------------+       |
- |     |    Functest Docker         |        |       |        |       |
+ |     |     Functest Docker        +-------------------------+       |
+ |     |                            |        |       |        |       |
  |     |                            +---------------------------------+
  |     |                            |        |       |        |       |
  |     +----------------------------+        |       |        |       |
@@ -107,7 +124,7 @@ The functional test cases are described in the Functest User Guide `[2]`_
 Prerequisites
 =============
 The OPNFV deployment is out of the scope of this document but it can be
-found in http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html.
+found in http://docs.opnfv.org.
 The OPNFV platform is considered as the System Under Test (SUT) in this
 document.
 
@@ -217,15 +234,14 @@ container from Jenkins.
 
 Docker creation in set-functest-env builder `[3]`_::
 
-    envs="INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
+    envs="-e INSTALLER_TYPE=${INSTALLER_TYPE} -e INSTALLER_IP=${INSTALLER_IP} -e NODE_NAME=${NODE_NAME}"
     [...]
-    docker pull opnfv/functest:latest_stable
-    cmd="docker run -id -e $envs ${labconfig} ${sshkey} ${res_volume} opnfv/functest:latest_stable /bin/bash"
+    docker pull opnfv/functest:$DOCKER_TAG >/dev/null
+    cmd="sudo docker run -id ${envs} ${volumes} ${custom_params} ${TESTCASE_OPTIONS} opnfv/functest:${DOCKER_TAG} /bin/bash"
     echo "Functest: Running docker run command: ${cmd}"
-    ${cmd}
-    docker ps -a
+    ${cmd} >${redirect}
     sleep 5
-    container_id=$(docker ps | grep 'opnfv/functest:latest_stable' | awk '{print $1}' | head -1)
+    container_id=$(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | awk '{print $1}' | head -1)
     echo "Container ID=${container_id}"
     if [ -z ${container_id} ]; then
         echo "Cannot find opnfv/functest container ID ${container_id}. Please check if it is existing."
@@ -235,43 +251,29 @@ Docker creation in set-functest-env builder `[3]`_::
     echo "Starting the container: docker start ${container_id}"
     docker start ${container_id}
     sleep 5
-    docker ps
-    if [ $(docker ps | grep 'opnfv/functest:latest_stable' | wc -l) == 0 ]; then
+    docker ps >${redirect}
+    if [ $(docker ps | grep "opnfv/functest:${DOCKER_TAG}" | wc -l) == 0 ]; then
         echo "The container opnfv/functest with ID=${container_id} has not been properly started. Exiting..."
         exit 1
     fi
-    cmd="${FUNCTEST_REPO_DIR}/docker/prepare_env.sh"
+
+    cmd="python ${FUNCTEST_REPO_DIR}/functest/ci/prepare_env.py start"
     echo "Executing command inside the docker: ${cmd}"
     docker exec ${container_id} ${cmd}
 
 
 Test execution in functest-all builder `[3]`_::
 
-  echo "Functest: run $FUNCTEST_SUITE_NAME"
-  cmd="${FUNCTEST_REPO_DIR}/docker/run_tests.sh --test $FUNCTEST_SUITE_NAME ${flag}"
-  container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
-  docker exec $container_id $cmd
-
-Docker clean in functest-cleanup builder `[3]`_::
-
-    echo "Cleaning up docker containers/images..."
-    # Remove previous running containers if exist
-    if [[ ! -z $(docker ps -a | grep opnfv/functest) ]]; then
-    echo "Removing existing opnfv/functest containers..."
-    docker ps | grep opnfv/functest | awk '{print $1}' | xargs docker stop
-    docker ps -a | grep opnfv/functest | awk '{print $1}' | xargs docker rm
+    branch=${GIT_BRANCH##*/}
+    echo "Functest: run $FUNCTEST_SUITE_NAME on branch ${branch}"
+    cmd="functest testcase run $FUNCTEST_SUITE_NAME"
     fi
+    container_id=$(docker ps -a | grep opnfv/functest | awk '{print $1}' | head -1)
+    docker exec $container_id $cmd
+    ret_value=$?
+    exit $ret_value
 
-    # Remove existing images if exist
-    if [[ ! -z $(docker images | grep opnfv/functest) ]]; then
-    echo "Docker images to remove:"
-    docker images | head -1 && docker images | grep opnfv/functest
-    image_tags=($(docker images | grep opnfv/functest | awk '{print $2}'))
-    for tag in "${image_tags[@]}"; do
-        echo "Removing docker image opnfv/functest:$tag..."
-        docker rmi opnfv/functest:$tag
-    done
-    fi
+Docker clean in functest-cleanup builder `[3]`_ calling docker rm and docker rmi
 
 
 References
@@ -279,7 +281,7 @@ References
 .. _`[1]`: https://ask.openstack.org/en/question/68144/keystone-unable-to-use-the-public-endpoint/
 .. _`[2]`: http://artifacts.opnfv.org/functest/docs/userguide/index.html
 .. _`[3]`: https://git.opnfv.org/cgit/releng/tree/jjb/functest/functest-ci-jobs.yml
-.. _`[4]`: http://artifacts.opnfv.org/opnfvdocs/colorado/docs/configguide/index.html
+.. _`[4]`: http://artifacts.opnfv.org/functest/danube/docs/configguide/index.html
 
 
 OPNFV main site: opnfvmain_.
@@ -289,4 +291,4 @@ OPNFV functional test page: opnfvfunctest_.
 IRC support channel: #opnfv-functest
 
 .. _opnfvmain: http://www.opnfv.org
-.. _opnfvfunctest: https://wiki.opnfv.org/opnfv_functional_testing
+.. _opnfvfunctest: https://wiki.opnfv.org/functest