README
== Beah - Beaker Harness ==

WARNING: This is a (mostly working) prototype. Things may be broken.

=== 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

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"

=== Usage ===

==== Set-up ====

To set-up development environment source dev-env.sh. Type

        . dev-env.sh

in shell, 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 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.

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
TCP/IP 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 Beah's language.

--------------------------------------------------------------------------------
# vim:et:sw=8:ts=8