WebService::TestSystem - Web service for implementing a distributed testing system.
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.
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.
Establishes a new WebService::TestSystem instance. This sets up a database connection.
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.
Retrieves a hash of error messages from the last call to validate_test_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.
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.
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
Returns a list of host machines registered in the system.
This routine returns a list of distro images that are available in the system. Each image record includes its descriptor, id, and status.
Returns a list of software packages available in the system for doing testing against.
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
Returns a list of queued tests for a given host name or id, or all hosts if $host is not defined.
Returns a list of patches in the system matching the given regular expression, up to $limit (default 100) items.
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.
Returns properties for the given test (including a URL where the test code can be fetched.
Updates the info about the given test. %properties should contain the list of values to update. Properties to leave alone should be undef.
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.
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.
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.
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.
Updates information about the given software type
To install WebService::TestSystem, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::TestSystem
CPAN shell
perl -MCPAN -e shell install WebService::TestSystem
For more information on module installation, please visit the detailed CPAN module installation guide.