Writing AutoQA Events and Watchers

Overview
The directory in the   source tree contains the events that AutoQA knows about. Watchers for these events are stored within directory.

An event has these parts:
 * 1) * describes the event itself and the required (and optional) arguments that will be passed along to the tests.
 * 2) * python code that is used to parse the test arguments, as described in the file. This is the formal definition of the test arguments.
 * 1) * python code that is used to parse the test arguments, as described in the file. This is the formal definition of the test arguments.
 * 1) * python code that is used to parse the test arguments, as described in the file. This is the formal definition of the test arguments.

A watcher consists of:
 * 1) * describes the general area that the watcher monitors and lists all events that are triggered by it.
 * 2) * Is the code that watches for the event and launches the  harness with the arguments described in the event's.
 * 3) * Currently, most of the existing watchers are scripts that get run periodically by  to check to see if the event has occurred since the last time it was run. If so, it launches.
 * 4) * In the future this will change to a daemon that waits for notifications about the event - see the Messaging SIG's Publish Subscribe Notification Proposal for further info about that.
 * 1) * Currently, most of the existing watchers are scripts that get run periodically by  to check to see if the event has occurred since the last time it was run. If so, it launches.
 * 2) * In the future this will change to a daemon that waits for notifications about the event - see the Messaging SIG's Publish Subscribe Notification Proposal for further info about that.

README
This is the human-readable description for this event. It describes its purpose, the required and optional arguments that will be passed to autoqa and the tests, and any special argument processing or test filtering that might happen.

Here's an example, the  README: This event is for tests that run after a repo has changed. A repo is considered "changed" if its package contents and metadata have been changed in some way.

The required argument for autoqa is a yum-compatible URL (probably http) that points to the changed repo.

Optional arguments: --name: human readable name for the repo under test --parent: a repo URL that is "parent" to the the repo under test; may be             specified multiple times

AutoQA tests can expect the following variables from post-repo-update event: baseurl: url of repo that changed parents: list of urls for 'parent' repos of the given repo (may be empty) name: name for repo that changed (may be empty)

Every event has at least one required argument - usually a URL that points to the new package/tree/repo/whatever. It can also define one or more optional arguments, which will be handled by autoqa commandline arguments. Those get defined in event.py.

event.py
This contains python code that will be loaded by autoqa when it is launched by the watcher. This code handles parsing the autoqa arguments and generating the data to be passed to the test. It must contain two methods:  and.

extend_parser
This function adds event-specific options to the given OptionParser object, so autoqa can properly parse the arguments given by the watcher. Here's the  from  :

import optparse

def extend_parser(parser): Extend the given OptionParser object with settings for this event. parser.set_usage('%%prog %s [options] REPOURL' % name) group = optparse.OptionGroup(parser, '%s options' % name) group.add_option('-n', '--name', default='',       help='Short, human-readable name for the repo under test') group.add_option('-p', '--parent', action='append', default=[],       help='URL of a "parent" repo that this repo depends on for closure') parser.add_option_group(group) return parser

The new options are generally used to handle the optional arguments to the test. This is where we've defined the  argument that the README mentioned.

The arguments are then handled in.

process_testdata
This function generates and returns a dict of testdata - the key=value data that will be passed along to the test.

It uses the results of  -   contains the options, and   contains the list of unhandled (usually required) args. (In the future it may get some extra keyword arguments, so it is usually defined with an **extra parameter.)

Here's the one from :

def process_testdata(parser, opts, args, **extra): '''Given an optparse.Values object and a list of args (as returned from   OptionParser.parse_args), return a dict containing the appropriate key=val pairs required by test's control files and test object. The event can also call parser.error here if it find out that not all options are correctly populated.'''

if not args: parser.error('No repo URL was specified as a test argument!')

testdata = {'baseurl': args[0], 'parents': opts.parent, 'name': opts.name or ''} return testdata

As you can see, it sets three values - The required argument is a URL, so we set  to the first non-option argument. is set to a list of the given  items. And  is set to the   argument if given - otherwise we just use empty string.

Watcher
The watcher is a program that actually watches for the event and triggers autoqa when it happens.

The watcher is responsible for constructing the correct  commandline (as defined in event, above) and executing. The rest of the design depends on the nature of the event.

The current watchers for  and   are run at regular intervals by. They check a certain file in each known repo ( or, respectively) to see if it's different from the cached copy. If it's changed, they save the new file and launch  for the repo/tree that has updated.

Yours could work that way, or it could be a daemon that waits for a signal, or any other design that makes sense. When writing a new watcher you might get some inspiration by looking at the current watchers:


 * yum-repo watcher.py
 * compose watcher.py
 * koji-bodhi watcher.py