== Beah - Test Harness == Offspring of Beaker project [http://fedoraproject.org/beaker] === Installation === To install, simply run: python setup.py install NOTE: This does not handle requirements! Use egg or rpm. Build/installation requires setuptools package. These python packages are required: * twisted.core and twisted.web * zope.interface * simplejson Additional modules required for Python 2.3: * hashlib * uuid NOTE: When using Python eggs, there is no Twisted egg on PyPI, one has to use Twisted_Web and Twisted_Core eggs. ==== Obvious (or not?) ==== If installing for non-default python instance simple use that interpreter e.g.: /usr/local/bin/python26 setup.py install For installing into non-standard directory use --prefix option e.g.: python setup.py install --prefix=/usr/local/share/beah To build RPMs, use python setup.py bdist_rpm --requires "python python-hashlib python-setuptools python-simplejson python-twisted-core python-twisted-web python-uuid python-zope-interface" Tito is used for version-release management. Use: tito tag # push to git... To build RPMs one can use tito build --rpm === Usage === ==== Installation ==== To install the package: yum install beah To run all services: chkconfig --level 345 beah-srv on chkconfig --level 345 beah-beaker-backend on chkconfig --level 345 beah-fwd-backend on To run a fake Lab Controller: chkconfig --level 345 beah-fakelc on === Development Environment === ==== Set-up ==== To set-up development environment source dev-env.sh. Type . dev-env.sh in BASH, which will set required environment variables (PATH and PYTHONPATH). This is not required when package is installed. ==== Run ==== After set-up, run launcher a in the same shell, which will start server and backends in separate terminals. Or launch components yourself. Development environment provides these shell functions: * beah-srv - controller server * beah-cmd-backend - backend to issue commands to controller. Enter `help' when "beah>" prompt is displayed. * beah-out-backend - backend to display messages from controller * beah - command line tool. Use `beah help' to display help. This uses the same command set as beah-cmd-backend * launcher - wrapper to start these programms in new terminal windows. beah-out-backend, beah-cmd-backend and beah will wait for controller. Few auxiliary binaries are provided in bin directory: * mtail_srv - run srv and beah-out-backend in single window (using multitail tool.) * beat_tap_filter - a filter taking a Perl's Test::Harness::TAP format on stdin and producing stream of Events on stdout. There are few test tasks in examples/tasks directory: * a_task - a very simple task in python. * a_task.sh - the same, in bash, with some delays introduced. * env - a binary displaying environment variables of interest. * flood - flooding Controller with messges. This task will not finish and has to be killed (in a `pkill flood' manner.) * socket - a task using TCP/IP socket to talk to Controller. Actually a_task and a_task.sh are a simple demonstration of how the test might look like, though it is not definite and more comfortable API will be provided. In default configuration server is listenning on localhost:12432 for backends and localhost:12434 for tasks. On POSIX compatible systems unix domain sockets are used for local connections by default. beah-cmd-backend does not offer history or command line editing features (it is on TODO list) thus it is more convenient to use beah command line tool. The commands supported are: ping [MESSAGE] ping a controller, response is sent to issuer only. PING [MESSAGE] ping a controller, response is broadcasted to all backends. run TASK r TASK run a task. TASK must be an executable file. kill kill a controller. dump instruct controller to print a diagnostics message on stdout. quit q close this backend. help h print this help message. Controller's log is written to: [/tmp]/var/log/beah.log === Development and Usage in a Lab === lm-install.sh script can be used to install harness from working copy on a lab machine. This requires either LABM env.variable to be defined or passing lab machine's FQDN as an argument To change settings, change lm-install-env.sh file. As this file is tracked by VCS, if lm-install-env.sh.tmp exists in current directory it is used with higher priority. Usage: On a lab machine: 1. $ mkdir -p /tmp/lm-install - This is the default. Change LM_INSTALL_ROOT in lm-install-env.sh. On the machine where beaker/Harness tree exists: 2. edit lm-install-env.sh (or eventually lm-install-env.sh.tmp) file. 3. $ export LABM=x.ample.com 4. $ ./lm-install.sh - 'LABM=x.ample.com ./lm-install.sh' or './lm-install.sh x.ample.com' can be used instead of [3, 4]. On a lab machine: 5. $ cd /tmp/lm-install 6. $ . lm-package-*.sh - Be careful to choose the correct one to be used. '. /tmp/lm-install/main.sh' can be used anytime to read environment and load functions. Run lm_main_help and lm_help for more help on available functions. === Glossary === _Controller_ is a center piece of harness. It is used to process Commands from Backends, spawn Tasks and process Events from Tasks, and eventually forwarding these to Backends. _Backend_ is a client which connects to Controller and which can issue Commands (read from console or socket) and is processing Events (writing to console or to file, to internet socket etc.) Multiple Backends can be connected to a single Controller. _Task_ is an executable, which runs a test and is generating Events as a result, sending these to the Controller server. It can use either stdout or socket to send events to Controller. stderr is captured as well, but is considered a raw-data (creating lose_item events.) _Event_ is a piece of information generated by running Task (e.g. log-event, result-event) or Controller (e.g. pong-event, bye-event) and sent to Backend. _Command_ is a piece of information instructing Controller (and eventually Task) to perform an operation (e.g. run-command to spawn a new Task or kill-command killing a Controller server) _Test_ is an executable performing testing producing output in known format. Task adaptor has to be written to translate this output to sequence of Events. -------------------------------------------------------------------------------- # vim:et:sw=8:ts=8