/ 
WebService-TestSystem-0.06
River stage zero No dependents
/ WebService::TestSystem

NAME

WebService::TestSystem - Web service for implementing a distributed testing system.

SYNOPSIS

my $testsys = new WebService::TestSystem;

# Getting a list of tests foreach my $test (@{$testsys->get_tests()}) { print "$test->{id} $test->{descriptor}\n"; }

# Getting a list of hosts foreach my $host (@{$testsys->get_hosts()}) { print "$host->{id} $host->{descriptor}\n"; }

# Submitting tests my %request; if (! $testsys->validate_test_request(\%request) ) { my %errors = $testsys->get_validation_errors(); } else { my $test_request_id = $testsys->request_test(%request); print "Test request #$test_request_id submitted\n"; }

# System Metrics @metrics = $testsys->metrics_test_run_time(2004, 12); @metrics = $testsys->metrics_requests_per_month(2004, 'all') @metrics = $testsys->metrics_distros_tested_per_month(2004) etc.

DESCRIPTION

WebService::TestSystem presents a programmatic interface (API) for remote interactions with a software testing service. In other words, this provides a set of remote procedure calls (RPCs) for requesting test runs, monitoring systems under test (SUT), and so forth.

FUNCTIONS

new(%args)

Establishes a new WebService::TestSystem instance. This sets up a database connection.

get_error()

Returns the most recent error message. If any of this module's routines return undef, this routine can be called to retrieve a message about what happened. If several errors have occurred, this will only return the most recently encountered one.

get_validation_errors()

Retrieves a hash of error messages from the last call to validate_test_request().

validate_test_request(\%request)

Checks the validity of a given test request. This routine also converts string values into ID's as appropriate, and updates %request in the process.

Returns a true value on successful validation, false if there is a validation error, or undef if there is a problem. Validation errors can be retrieved via the get_validation_errors() routine. General error messages can be obtained via the get_error() routine.

request_test(\%request)

Issues a test request into the system.

Returns undef on error, or the test request ID number on success. In case of error, you can retrieve the error message via the get_error() routine.

This routine calls validate_test_request() to check inputs prior to submission. If any errors are found, it will return undef, with the error message set to 'test request failed validation'. The errors themselves can be retrieved via the get_validation_errors() routine.

get_tests()

Returns a list of tests in the system. Each test object will include several fields:

id
descriptor
description
category
code_location
configuration_notes
status
environment_default
lilo_default
repeat_safe

get_hosts()

Returns a list of host machines registered in the system.

get_images()

This routine returns a list of distro images that are available in the system. Each image record includes its descriptor, id, and status.

get_software_types()

Returns a list of software packages available in the system for doing testing against.

get_requests(%args)

This routine permits searching against the test requests in the system. Arguments can be provided via the %args hash. Accepted arguments include:

limit           - the number of records to return
order_by        - the fieldname to order the records by

distro          - search condition (supports % wildcards)
test            - search condition (supports % wildcards)
host            - search condition (supports % wildcards)
host_type       - search condition (supports % wildcards)
project         - search condition (supports % wildcards)
priority        - search condition (must match exactly)
status          - search condition (must match exactly)
patch_id        - search condition (must be a valid patch id number)
patch           - search condition (must match a valid patch name)
created_by      - user id number for requestor
username        - username of requestor

Each test request record returned includes the following info:

id              - the test request's id
created_by      - user id# of the requestor
username        - username of the requestor
project         - project associated with the request
status          - the state the test request is currently in
priority        - priority

created_date    - date it was created
started_date    - datetime the test run began
completion_date - date it was completed

distro          - distro image name
test            - test name
host            - host name
host_type       - host class
patch           - patch name

distro_tag_id   - id# of distro image
test_id         - id# of test
host_id         - id# of host
host_type_id    - id# of host type
project_id      - id# of project
patch_tag_id    - id# of patch

get_request_queue([$host])

Returns a list of queued tests for a given host name or id, or all hosts if $host is not defined.

get_patches($patch_regex[, $limit])

Returns a list of patches in the system matching the given regular expression, up to $limit (default 100) items.

add_test($name, \%properties)

Adds a new test to the system. This includes all test descriptions, parameter information, default settings, etc.

If the user is a maintainer for this test, allows update directly, otherwise sends an email request to the system admins.

get_test($name)

Returns properties for the given test (including a URL where the test code can be fetched.

update_test($name, \%properties)

Updates the info about the given test. %properties should contain the list of values to update. Properties to leave alone should be undef.

If the user is a maintainer for this test, allows update directly, otherwise sends an email request to the system admins.

activate_host($host_id)

NOT YET IMPLEMENTED

Activates the given host, if it is in maintenance mode. This routine can only be called by someone with administrator priv's.

checkout_host(\%host_criteria, \%notification, \%preparation)

NOT YET IMPLEMENTED

Requests a machine be 'checked out', as indicated by the %host_criteria hash. This hash supports the following fields:

id     - a regular expression that will resolve to one or more 
         host id's
type   - a regular expression that resolves to a valid set of
         host_type's

The above criteria are ANDed together, so only hosts that matches ALL of the criteria will be selected.

If more than one host matches the criteria, then the first available system will be checked out. If multiple machines need to be checked out, call this routine that many times.

The %notification hash provides instructions regarding how the user should be notified about when the host becomes available. It supports the following fields:

email - an email address to send an email to when the system becomes
        available.
on_state_change - if set to true, will notify user of ALL changes,
        not just availability.

If no notification info is provided (the %notification hash is left undefined or empty), then no notification will be performed, and it will be up to the requestor to check back periodically to determine when the machine is available, via get_hosts().

When a machine is checked out, it is put on a time-out. After the time has expired, the machine will automatically return to the queue. This way if someone checks out a machine but isn't around to use it when it becomes available, it won't sit idly checked out forever.

The %preparation hash allows the user to specify additional custom setup work that should be completed on the machine prior to marking the machine 'available' and notifying the user. This could include waiting for another machine checkout to complete, installing some user-specific tools, initiating some instrumentation, etc.

change_host_reservation($host_id, $timeout)

NOT YET IMPLEMENTED

Allows altering the reservation time for a given host. This allows extending your checkout request beyond the default, or even to check a machine back in.

$timeout can be a period of time ("120 min"), or a cut-off time (6:00 pm Friday). To check a machine in or cancel the reservation, pass a zero value for $timeout. Invalid timeouts (negative times, non-time strings, dates in the past, etc.) result in an error.

Those with admin privs can check out machines for any length of time. Regular users will be limited as to the maximum reservation times they're allowed.

add_software_type($type, \%properties)

Registers new software for the testing system to track. This will cause the system to periodically check for new releases or snapshots of the code for running tests against. This allows automating the testing process, so that certain tests can be run regularly against the code.

The frequency may be limited by the administrator as appropriate to the resource availability.

update_software_type($type, \%properties)

Updates information about the given software type