Change in vdsm[master]: vdsm: documentation for new storage functional tests

Sunday, 26 October 2014

Yoav Kleinberger has uploaded a new change for review.

Change subject: vdsm: documentation for new storage functional tests
......................................................................

vdsm: documentation for new storage functional tests

Added a markdown README file that explains the design and usage of the
new functional tests. This will help future developers who wish to
extend the tests.

Change-Id: I7858c5ce6e17f2dbf11bf7ec6d041e4dbef0457c
Signed-off-by: Yoav Kleinberger <ykleinbe(a)redhat.com&gt;
---
A tests/functional/testlib/README.md
1 file changed, 144 insertions(+), 0 deletions(-)


  git pull ssh://gerrit.ovirt.org:29418/vdsm refs/changes/78/34478/1

diff --git a/tests/functional/testlib/README.md b/tests/functional/testlib/README.md
new file mode 100644
index 0000000..3a2847c
--- /dev/null
+++ b/tests/functional/testlib/README.md
@@ -0,0 +1,144 @@
+# New Functional Tests for VDSM
+
+By Yoav Kleinberger (ykleinbe(a)redhat.com ; haarcuba(a)gmail.com)
+
+## Introduction 
+This document describes new functional tests for VDSM storage,
+intended to replace the old tests at `tests/functional/storageTests.py`.  The old
+tests need replacing, because they
+
+1. Are hard to understand.
+2. Do not really verify VDSM behaviour.
+
+The new tests *do* verify VDSM behaviour, and are, so I hope, easier to understand.
+
+## Running the Tests
+
+First thing's first: to run the new functional tests, change into the `tests`
directory and then
+
+        $ ./run_functional_storage_tests.sh
+
+You can use 
+
+        $ ./run_functional_storage_tests.sh --verbose
+
+to see verbose logging.
+
+## The Basic Test: Create Volume
+
+There is currently one basic flow we test
+
+1. Creation of a Storage Domain
+2. Creation of a Virtual Disk on that Domain
+
+We want to test this flow for various storage backends, e.g. for NFS, iSCSI and
+Fibre Channel. This requires that the test framework support different storage
+backends. The problem is solved at the price of a non-trivial design of test
+"Storage Contexts", which will now be explained. The test itself resides in
+`tests/functional/basicStorageTest.py`.
+
+## Storage Contexts
+
+### iSCSI example
+
+As explained above, our create-volume test needs to run in different contexts:
+an iSCSI context, an NFS context, and so on. These contexts are represented by
+modules residing in
+
+        functional/testlib/storagecontexts
+
+To take a concrete example, let's look at the iSCSI context, located at
+`functional/testlib/storagecontexts/iscsi.py`. This file contains two classes:
+`ISCSI` and `Verify`. The usage is as follows:
+
+        with iscsi.ISCSI() as (vdsm, verify):
+            storageServerID = vdsm.connectStorageServer()
+            verify.storageServerConnected()
+
+            domainID = vdsm.createStorageDomain()
+            verify.storageDomainCreated(domainID)
+
+            poolID = vdsm.createStoragePool()
+            verify.storagePoolCreated(poolID, masterDomainID=domainID)
+            ...
+
+Note the structure of action/verification. The `vdsm` object lets you give VDSM
+a command [just like Engine does]. The `verify` object checks for observable
+changes induced by the command, e.g. the existence of logical volumes, etc. 
+
+The ISCSI storage context makes sure that the `(vdsm, verify)` pair acts on an
+actual iSCSI storage set up for the purpose of this test. The ISCSI object will
+set up an iSCSI storage (on the host where the test runs), and will clean it up
+when the test is finished.  In the example above, `vdsm.connectStorageServer()`
+tells vdsm to connect to the iSCSI storage, and the `verify` object then checks
+inside the `sysfs` interface exposed by the linux kernel that the connection
+actually exists.
+
+### Under the Hood of the iSCSI Storage Context
+
+As a further clarification of the workings of these tests, let's look at what
+happens when the `vdsm.connectStorageServer()` call above is executed. If you
+look inside, you'll find that this gets translated into calling the VDSM API
+with something like
+
+     
+        connectStorageServer(   storage.sd.ISCSI_DOMAIN,
+                                '00000000-0000-0000-0000-000000000000',
+                                [{  'connection': '127.0.0.1',
+                                    'iqn':
'iqn.1970-01.functional.test:3243',
+                                    'user': '',
+                                    'tpgt': '1',
+                                    'password': '',
+                                    'id':
'00000000-0000-0000-0000-000000000000',
+                                    'port': '3260' }])
+
+Thus, the ISCSI storage context object translates the essence of
+`connectStorageServer` to proper iSCSI terms. 
+
+The same goes for the `verify`
+object. The `verify.storageServerConnected` call above will result in globbing
+files under `/sys/devices/platform/host*/session*/iscsi_session/*/targetname`
+and looking for the IQN inside.
+
+### Other Storage Contexts
+
+As demostrated above, the `ISCSI` class takes care of setting up iSCSI storage,
+and cleaning up afterwards. Similarly, if you want to test the same operations
+on NFS, you would use an NFS storage context (to be found in
+`functional/testlib/storagecontexts/nfs.py`) in exactly the same way:
+
+        with nfs.NFS() as (vdsm, verify):
+            storageServerID = vdsm.connectStorageServer()
+            verify.storageServerConnected()
+            ...
+
+This time, the `NFS` object will set up NFS storage, use the proper NFS
+parameters for calling VDSM and for verifying its behaviour,  and remove it
+afterwards.
+
+Currently, we have iSCSI, LocalFS and NFS support. This may be extented by
+writing new storage contexts, e.g. for Fibre Channel.
+
+## VDSM Service Shutdown and Bringup
+
+Between tests, we shutdown the VDSM service, clean up the `/rhev/data-center`
+directory, and restart the service. The class in charge of this is
+`ControlVDSM`, located in `tests/functional/testlib/controlvdsm.py`. It also
+checks that VDSM is listening for commands before returning.
+
+## Randomness
+
+The storage contexts include a fair amount of ranomizing, e.g. the `iqn` iSCSI
+parameter is different every time the test is run. This helps us avoid cases in
+which some leftovers from manual checks or previous test runs mess with our
+test results. I recommend continuing this practice.
+
+## Known Issues
+
+1. Currently, cleanup after the tests is not perfect: if you work with the
+   tests you'll see the problems. The tests work well enough that it's not an
+   immediate concern, but there is room for improvement. At this stage I wanted
+   to get the tests into wider acceptance and worry about improving this later.
+2. The storage context classes are obviously quite tailored to the
+   create volume test, and will probably require some changes when adding
+   future tests.


-- 
To view, visit http://gerrit.ovirt.org/34478
To unsubscribe, visit http://gerrit.ovirt.org/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I7858c5ce6e17f2dbf11bf7ec6d041e4dbef0457c
Gerrit-PatchSet: 1
Gerrit-Project: vdsm
Gerrit-Branch: master
Gerrit-Owner: Yoav Kleinberger <ykleinbe(a)redhat.com&gt;

    

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011