summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--tests/distaf/README.md66
1 files changed, 66 insertions, 0 deletions
diff --git a/tests/distaf/README.md b/tests/distaf/README.md
new file mode 100644
index 00000000000..8e6cd54f46d
--- /dev/null
+++ b/tests/distaf/README.md
@@ -0,0 +1,66 @@
+# DiSTAF
+
+DiSTAF (or distaf) is a test framework for distributed systems like glusterfs.
+
+This file contains information about how to contribute automated test cases to gluster. For information about overview and architecture, please refer to [README](https://github.com/gluster/distaf/blob/master/README.md). To know more about how to write tests and more about the distaf APIs please refer [HOWTO](https://github.com/gluster/distaf/blob/master/docs/HOWTO.md).
+
+## Before contributing tests to gluster
+
+This doc assumes that you are familiar with distaf and know how to write a test case in distaf. These tests are meant for running perodically in a CI environment. So avoid assuming any test environment and make sure you are aware of the environment where the tests are being run. For example do not assume that some non-standard packages will be present in the test environment.
+
+### Installing distaf and distaflibs packages
+DiSTAF is devided into packages. The core part of distaf (the framework which provides connection manager and core APIs) are part of [distaf.git](https://github.com/gluster/distaf) and are available through distaf package. The gluster libraries are part of [glusterfs.git](https://github.com/gluster/glusterfs/tree/master/tests/distaf) and are available through distaflibs namespace packages. Please note that, to install these packages you need to have [python-setuptools](https://pypi.python.org/pypi/setuptools) (Most likely will be available through yum/apt-get) and should be run with root privilages.
+
+The distaf core package can be installed through below command. It will install the distaf core package from the git HEAD available from distaf.git.
+```bash
+pip install git+https://github.com/gluster/distaf@master
+```
+
+The libraries related to gluster, which enables to write gluster tests are available through the namespace package distaflibs. And as part of namespace package distaflibs, We have 2 sub-packages (and provision to add more sub-packages in future if need arises) `distaflibs-gluster` and `distaflibs-io`. These libraries and the tests are part of [glusterfs.git](https://github.com/gluster/glusterfs). If you have cloned the glusterfs.git, please follow the below steps to install both sub-packages of distaflibs.
+```bash
+cd <glusterfs.git>/tests/distaf/distaf_libs/distaflibs-gluster
+python setup.py install # Installs distaflibs.gluster package
+cd <glusterfs.git>/tests/distaf/distaf_libs/io_libs
+python setup.py install # Installs distaflibs.iolibs package
+```
+
+## Writing the gluster tests
+
+DiSTAF supports both python function and python class as the testcase. But for gluster, each test case should be a python class and should be a sub class of `GlusterBaseClass`. This base class takes care of few of the basic things like creating volume based on the `global_mode` flag in configuration file etc. So the test case should implement the `run()` method with the test case logic. Any extra setup part done in `run()` should be cleaned up in `teardown()` method, which also should be implemented by test, if necessary.
+
+Also `GlusterBaseClass` exposes few of the variable which are accesible from the connection manager object `tc`. Please consider below example.
+```python
+from distaf.util import tc, testcase
+from distaflibs.gluster.gluster_base_class import GlusterBaseClass
+from distaflibs.gluster.mount_ops import mount_volume, umount_volume
+
+@testcase("nfs-test-01")
+class nfs_test_01(GlusterBaseClass):
+ """
+ runs_on_volumes: ALL
+ run_on_protocol: [ nfs ]
+ reuse_setup: True
+ """
+ def run(self):
+ tc.logger.debug("The volume name is %s and is of the type %s", self.volname,
+ self.voltype)
+ tc.logger.debug("This test mounts the volume at %s with %s mount protocol",
+ self.mountpoint, self.mount_proto)
+ client = self.clients[0]
+ ret, out, err = mount_volume(self.volname, self.mount_proto, self.mountpoint,
+ mclient=client)
+ if ret!= 0:
+ tc.logger.error("The mount failed")
+ return False
+ return True
+
+ def teardown(self):
+ umount_volume(self.clients[0], self.mountpoint)
+ return True
+```
+
+So the volume name and volume type are accessible with the variables `self.volname` and `self.voltype` respectively. Since the test calls the `mount_volume()` in `run()`, it is the responsibility of the test to call `umount_volume()` in `teardown()`.
+
+NOTE: The `setup()` only creats the volume. All other test logic has to be built inside the `run()` method.
+
+For any more questions/comments please send a mail to [gluster-devel](https://www.gluster.org/mailman/listinfo/gluster-devel)