X-Git-Url: https://gerrit.akraino.org/r/gitweb?p=ta%2Fcloudtaf.git;a=blobdiff_plain;f=README.rst;fp=README.rst;h=72549f4a62ef3babc86753021a61bb5d8117bff1;hp=0000000000000000000000000000000000000000;hb=d448b9388fd9cb3732e35996b98f493a5a5921d4;hpb=07c5f13d2429236a603c867e09c4cc3b42e75826

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..72549f4
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,124 @@
+..
+    Copyright 2019 Nokia
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+Introduction
+------------
+
+Test cases are executed within a virtual environment in order to have all
+python package dependencies installed. This virtual environment creation is
+managed by tox. Furthermore tox execution can be optionally wrapped with a
+docker environment to provide required operating system packages and
+configuration to pull dependencies.
+
+Execution environment as simple diagram::
+
+  $ ./rfcli-docker <args> == [ docker [ tox [ virtualenv [ rfcli -> robotframework <args> ] ] ] ]
+
+You can find here more details about how to execute in your machine here
+(windows specific, but it contains tips also if you have linux):
+:ref:`windowsinstructions`
+
+
+Writing robot test cases
+------------------------
+Please use the following tags mentioned here:
+:ref:`taggingpolicy` and also consider our test case design guidelines:
+:ref:`designguidelines`
+
+
+Execution examples
+------------------
+
+Docker + tox::
+
+  $ ./rfcli-docker -t path/to/target.ini -s smoke-tests testcases/
+
+This is the most simple way to execute the cloudtaf2 tests. As docker is being
+used the created python virtual environment as well as the resulting files will
+be owned by the "root" and not the actual user. Additionally initial execution
+will take some time to build the image.
+
+You may also run directly *rfcli* environment with *tox*::
+
+  $ tox -e rfcli -- -t path/to/target.ini -s smoke-tests testcases
+
+
+Execution examples - tox only
+-----------------------------
+
+This is more lightweight way to execute the tests but requires certain
+operating system packages to be installed first. Please see the "Dockerfile"
+for installed packages.
+
+Tox only - more lightweight for those who know what they are doing::
+
+  $ tox -e rfcli -- -t path/to/target.ini -s smoke-tests testcases/
+
+Virtual environment
+-------------------
+
+Python virtual environment is created with requirements.txt. All python
+packages must be set to certain versions in order to execute tests the same way
+with older builds as they have been initially executed.
+
+To update the frozen versions to the latest, execute::
+
+  $ tox -e freeze
+
+To add more packages, update the requirements-minimal.txt and execute::
+
+  $ tox -e freeze
+
+You can add specific version requirements to the requirements-minimal.txt
+to make sure that they are used in the generated frozen requirements.txt.
+
+The recommendation is that the frozen requirements.txt file is not edited
+directly but always via the requirements-minimal.txt changes and via this freeze
+generation.
+
+In clear cases you can also update requirements.txt directly. However,
+in this case, please make sure that::
+
+  $ tox --recreate -e check-requirements
+
+is succesful. This tool checks that the requirements-minimal.txt
+is consistent with the requirements.txt and that all requirements in
+requirements.txt can be really installed.
+installed.
+
+
+Rebuild docker image
+--------------------
+
+Rebuild docker image manually e.g. when changing the Dockerfile contents::
+
+  $ ./rfcli-docker-build
+
+Unit testing
+------------
+
+Unit tests can be executed with::
+
+  $ tox
+
+Running Docker behind a proxy
+-----------------------------
+The 'dnf install' -command requires a proxy setting when Docker is running
+behind a proxy.
+
+The Dockerfile writes the proxy information to /etc/dnf/dnf.conf -file when
+HTTP_PROXY argument is set as a --build-arg. For example::
+
+ # docker build --build-arg HTTP_PROXY=http://10.1.2.3:8080/