On Mon, Feb 21, 2011 at 06:18:58PM +0100, Dejan Muhamedagic wrote: > Hi Florian, > > On Wed, Feb 16, 2011 at 09:11:21AM +0100, Florian Haas wrote: > > Hello, > > > > I have taken John Shi's original ocft README and turned it into a > > section in the RA dev guide. It's not on the web site yet as I've not > > had time to polish the contents (it shows a bit that the original author > > is a non-native speaker). So if anyone can make some time and send a > > patch, I'd much appreciate it. > > > > The Mercurial repo is at http://hg.linux-ha.org/doc, the AsciiDoc source > > is in dev-guides/ra-dev-guide.txt. You don't need to know any syntax to > > send a patch, all you have to be able to do is use a text editor. Look > > for "Testing with +ocft+". Thanks! > > I started working on it.
Here's the patch. Didn't try to run it through asciidoc. There are some things regarding remote shell unclear. I'll ask John to take a look. Cheers, Dejan > Thanks, > > Dejan > > > Cheers, > > Florian > > > > > > > _______________________________________________________ > > Linux-HA-Dev: [email protected] > > http://lists.linux-ha.org/mailman/listinfo/linux-ha-dev > > Home Page: http://linux-ha.org/ > > _______________________________________________________ > Linux-HA-Dev: [email protected] > http://lists.linux-ha.org/mailman/listinfo/linux-ha-dev > Home Page: http://linux-ha.org/
# HG changeset patch # User Dejan Muhamedagic <[email protected]> # Date 1298464366 -3600 # Node ID 4ca30294296300a8f2c9ae781bc2c69d441b0c64 # Parent 3c629792fa9536aa473ed28441583cd1d2b29e34 RA dev guide: edit ocft description diff -r 3c629792fa95 -r 4ca302942963 dev-guides/ra-dev-guide.txt --- a/dev-guides/ra-dev-guide.txt Tue Feb 15 22:42:42 2011 +0100 +++ b/dev-guides/ra-dev-guide.txt Wed Feb 23 13:32:46 2011 +0100 @@ -1595,57 +1595,52 @@ Beginning tests for /home/johndoe/ra-dev === Testing with +ocft+ -+octf+ is a testing tool for resource agents. Instead of the policy of -HA, it mainly concerns whether resource agents run correct locally. It -can design types of complicated environments to test the reliability -of resource agents. Precisely, it is to display whether resource -agents can return to correct or expected value. The advantage of the -tool provides us with competence to design conditions which can be -recorded or reproduced. Hence it is useful to debuggers. ++octf+ is a testing tool for resource agents. The main difference +to +ocf-tester+ is that +ocft+ can automate creating complex +testing environments. That includes package installation and +arbitrary shell scripting. ==== +ocft+ components +ocft+ consists of the following components: -* A test case generator (+/usr/sbin/ocft+) -- Turning configuration - files of test case to executable scripts. +* A test case generator (+/usr/sbin/ocft+) -- generates shell + scripts from test case configuration files * Configuration files (+/usr/share/resource-agents/ocft/configs/+) -- - every configuration file directs only one resource agent and share - the same name with resource agent but contains more test cases. + a configuration file contains environment setup and test cases + for one resource agent -* The testing scripts (+/var/lib/resource-agents/ocft/cases/+) -- - after the generator reads configuration files and generates many - testing scripts and the script is underway, the test begins. +* The testing scripts are stored in +/var/lib/resource-agents/ocft/cases/+, + but normally there is no need to inspect them ==== Customizing the testing environment -+ocft+ designs the running conditions through two ways, one is -changing the environment variables of resource agents (it is the -interface left by OCF itself), the other is modifying the OS -environment of resource agents, such as altering the permission of -some key file or IP address of the machine. ++ocft+ modifies the runtime environment of the resource agent +either by changing environment variables (through the interface +defined by OCF) or by running ad-hoc shell scripts which can for +instance change permissions of a file or unmount a file system. ==== How to test -Firstly, you need to sketch the all complex and uncommon environments -against a certain resource agent and keep in mind what consequences -may be caused by these uncommon environments. +You need to know the software (resource) you want to test. Draw a +sketch of all interesting scenarios, with all expected and +unexpected conditions and how the resource agent should react to +them. Then you need to encode these conditions and the expected +outcomes as +ocft+ test cases. Running ocft is then simple: -Secondly, write the designed conditions and foreknown consequences -into configuration files, and then run the generator to translate the -test case to executable scripts. +--------------------------------------- +# ocft make <RA> +# ocft test <RA> +--------------------------------------- -Finally, you need running these scripts to observe the output and -learn the running status of each test case, which will compares the -predicated result with the actual one. If they differ, you will be -able to find the bugs of the resource agent. +The first subcommand generates the scripts for your test cases +whereas the second runs them and checks the outcome. ==== +ocft+ configuration file syntax -There are only 4 top level options that are all spelled by capital -letters and "-". Every top level option contains sub-options that -they are initials. +There are four top level options each of which can contain +one or more sub-options. ===== +CONFIG+ (top level option) @@ -1656,64 +1651,47 @@ This option is global and influences eve AgentRoot /usr/lib/ocf/resource.d/xxx --------------------------------------- -A few agents will go to "linbit" or "pacemaker" directory, if you -define this option, ocft will use it to replace the default directory -"heartbeat". +Normally, we assume that the resource agent lives under the ++heartbeat+ provider. Use `AgentRoot` to test agent which is +distributed by another vendor. ** +InstallPackage+ (sub-option) --------------------------------------- InstallPackage package [package2 [...]] --------------------------------------- -It will test whether the system have installed the service of the -resource agent. If not, it will download from Internet and have it -installed automatically. +Install packages necessary for testing. The installation is +skipped if the packages have already been installed. ** 'HangTimeout' (sub-option) --------------------------------------- HangTimeout secs --------------------------------------- -If you alter some key options, some resource agents will get puzzled -and stop, which will influence the running of the following test case. -Hence timeout setting is needed, if the resource agent stops timeout, -the scripts will kill this resource agent. +The maximum time allowed for a single RA action. If this timer +expires, the action is considered as failed. ===== +SETUP-AGENT+ (top level option) --------------------------------------- SETUP-AGENT - bash scripts... - ... + bash commands --------------------------------------- -Some of Agents may need to be initialized before testing, you can do -it here with bash script. The initialization will only be executed -once, if you want to reinitialize it, you can manually delete the flag -file at /tmp/.[AGENT_NAME]_set. +If the RA needs to be initialized before testing, you can put +bash code here for that purpose. The initialization is done only +once. If you need to reinitialize then delete the ++/tmp/.[AGENT_NAME]_set+ stamp file. -===== +CASE+ & +CASE-BLOCK+ (top level options) +===== +CASE+ (top level option) --------------------------------------- CASE "description" --------------------------------------- ---------------------------------------- -CASE-BLOCK macro_name ---------------------------------------- -Usually, the conditions you designed are more than one and a few 'CASE -"..."' will appear in configuration file. It is worth noting that the -following sub-options have 2 spellings: +This is the main building block of the test suite. Each test +case is to be described in one +CASE+ top level option. -One is general, where shell affects the local environment; the other -is special, where each options added "@ipaddr". It can remotely -execute shell codes. In other words, it is to execute the shell codes -from a remote host, which is meaningful when a resource agent needs 2 -hosts. This remote shell is not a remote execution only through "ssh", -but running a remote shell in the background while the test case is -running. The remote shell runs in the background till the end and -saves the results during the process. That is to say, you can -alternatively carry out local and remote shell code segments. The -"CASE-BLOCK" option is a macro definer, the statements in "CASE-BLOCK" -will be inserted into "CASE" if you "Include" the "macro_name". +One case consists of several suboptions typically followed by the ++RunAgent+ suboption. ** +Var+ (sub-option) --------------------------------------- @@ -1736,8 +1714,8 @@ Remove the environment variable. Include macro_name --------------------------------------- -It will be replaced by statements in 'macro_name', of course, you -should define the content of 'macro_name' with 'CASE-BLOCK' first. +Include statements in 'macro_name'. See below for description of ++CASE-BLOCK+. ** +Bash+ (sub-option) --------------------------------------- @@ -1771,6 +1749,34 @@ parameter is optional. It will compare t the expected value when the script has run recourse agent. If differs, bugs will be found. +It is also possible to execute a suboption on a remote host +instead of locally. The protocol used is ssh and the command is +run in the background. Just add the +@<ipaddr>+ suffix to the +suboption name. For instance: + +--------------------------------------- [email protected] date +--------------------------------------- + +would run the date program. Remote commands are run in +background. + +NB: Not clear how can ssh be automated as we don't know in +advance the environment. Perhaps use "well-known" host names such +as "node2"? Also, if the command runs in the background, it's not +clear how is the exit code checked. Finally, does Var@node make +sense? Or is the current environment somehow copied over? We +probably need an example here. + +Need examples in general. + +===== +CASE-BLOCK+ (top level option) +--------------------------------------- +CASE-BLOCK macro_name +--------------------------------------- + +The +CASE-BLOCK+ option defines a macro which can be +Include+d +in any +CASE+. All +CASE+ suboptions are valid in +CASE-BLOCK+. == Installing and packaging resource agents
_______________________________________________________ Linux-HA-Dev: [email protected] http://lists.linux-ha.org/mailman/listinfo/linux-ha-dev Home Page: http://linux-ha.org/
