[libvirt] [test-API] add docs files TESTCASE.py and TESTCASES.conf

[Guannan Ren]

    *docs/TESTCASE.py: an template of testcase.py
    *docs/TESTCASES.conf: an template of testcase config file with
                          simple explanation
---
 docs/TESTCASE.py    |   45 ++++++++++++++++++++++++++++++++
 docs/TESTCASES.conf |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 115 insertions(+), 0 deletions(-)
 create mode 100644 docs/TESTCASE.py
 create mode 100644 docs/TESTCASES.conf

diff --git a/docs/TESTCASE.py b/docs/TESTCASE.py
new file mode 100644
index 0000000..48adb56
--- /dev/null
+++ b/docs/TESTCASE.py
@@ -0,0 +1,45 @@
+#! /usr/bin/env python
+# How to write a new testcase
+
+# If testcase wants to use the connection object offered
+# by the framework or share variables between testcases
+# import sharedmod module.
+import sharedmod
+
+# List parameters supported by the testcase in the two
+# global tuple variables with a ',' at the end of last element.
+# Both of them are mandatory.
+required_params = ('option1', 'option2',)
+optional_params = ()
+
+# The check function is optional. This is for some testcases that
+# need to check whether specific hardware is present on box or
+# testing environment is good before testing.
+# Return value 0 means check pass, 1 means to skip the
+# testcase during running.
+def TESTCASE_check(params):
+    logger = params['logger']
+    ...
+    return 0
+
+# This is the main testing function, The function name must be
+# the same as the file name of the testcase. params['logger'] is
+# provided by framework for logging.
+# Return value 0 means the success of testing, 1 means testing failure.
+# It is mandatory.
+def TESTCASE(params):
+    logger = params['logger']
+    ...
+    return 0
+
+# The clean function is optional. This is for testcases that dirtied
+# testing environment after executed. If keyword 'clean' is set
+# just below the testcase in testcase config file, the clean function
+# defined in the testcase.py will be invoked by framework to do the
+# cleaning job.
+# Return value is optional too, 1 means clean failure, but will not
+# stop the run of testing.
+def TESTCASE_clean(params):
+    logger = params['logger']
+    ...
+    return 0
diff --git a/docs/TESTCASES.conf b/docs/TESTCASES.conf
new file mode 100644
index 0000000..1ca351b
--- /dev/null
+++ b/docs/TESTCASES.conf
@@ -0,0 +1,70 @@
+# single line comments looks like this
+
+/*
+  Multiline comments look like this.
+  The lines enclosed by the C style comments will
+  be skipped by parser.py
+*/
+
+###############################################################
+# Indentation:
+# An indent level is four spaces, do not use tabs to indent.
+#
+
+# .----------- testcase: The first line contains the module name and the test case name separated by a colon and is not indented.
+# |
+domain:undefine
+
+#     .-------- options: Indent options by an indent level(four spaces)
+#     |
+    guestname
+
+#           .---- value: Indent Values by two indent levels(eight spaces)
+#          |
+        fedoraVM
+
+################################################################
+#
+# Keywords:  'clean', 'times', 'sleep', '{start_loop, end_loop}'
+#
+
+# 'clean': invoke the clean function in previous testcase
+clean
+
+# 'times': repeat testcase 'repos/domain/install_linux_cdrom.py' N times
+domain:install_linux_cdrom times 2
+    guestname
+       fedoraVM
+    memory
+       1024
+    vcpu
+       1
+
+# 'sleep 5': pause the run of testing for N seconds.
+sleep 5
+
+# The pair of 'start_loop' and 'end_loop' will
+# run the testcases between them N loops
+domain:start start_loop
+    guestname
+        fedoraVM
+
+domain:destroy end_loop 3
+    guestname
+        fedoraVM
+
+################################################################
+#
+# Options: 'times', 'cleanup'
+# always be the last line of testcase config file
+#
+
+#         .---------------------- repeat the above testcases n more times.
+#         |       .-------------- invoke the clean function in all of above testcases
+#         |       |
+options times=2 cleanup=enable
+
+# python libvirt-test-api.py -t repos/domain/undefine.py repos/domain/install_linux_cdrom.py \
+#                                repos/domain/start.py repos/domain/destroy.py
+#
+# The command generates a template of tescase file like above
-- 
1.7.7.5