/ 
TestLink-API-0.011
River stage zero No dependents
/ TestLink::API

NAME

TestLink::API - Provides an interface to TestLink's XMLRPC api via HTTP

VERSION

version 0.011

SYNOPSIS

use TestLink::API;

my $tl = TestLink::API->new('http://tl.test/testlink/lib/api/xmlrpc/v1/xmlrpc.php', 'gobbledygook123');

#Look up test definitions
my $projects = $tl->getProjects();
my $suites = $tl->getTLDTestSuitesForProject($projects->[0]->{'id'});
my $childsuites = $tl->getTestSuitesForTestSuite($suites->[0]->{'id'});
my $tests = $tl->getTestCasesForTestSuite($childsuites->[0]->{'id'});

#Look up test plans/builds
my $plans = $tl->getTestPlansForProject($projects->[0]->{'id'});
my $tests2 = $tl->getTestCasesForTestPlan($plans->[0]->{'id'});
my $builds = $tl->getBuildsForTestPlan($plans->[0]->{'id'});

#Set results
my $testResults = doSomethingReturningBoolean();
my $results = $tl->reportTCResult($tests2->[0]->{'id'},$plans->[0]->{'id'},$builds->[0]->{'id'}, $testResults ? 'p' : 'f');
$tl->uploadExecutionAttachment($results->{'id'},'test.txt','text/plain',encode_base64('MOO MOO MOOOOOO'),'bovine emissions','whee')

DESCRIPTION

TestLink::API provides methods to access an existing TestLink account. You can then do things like look up tests, set statuses and create builds from lists of tests. The getter methods cache the test tree up to whatever depth is required by your getter calls. This is to speed up automated creation/reading/setting of the test db based on existing automated tests. Cache expires at the end of script execution. (TODO use memcached controlled by constructor, with create methods invalidating cache?) Getter/setter methods that take args assume that the relevant project/testsuite/test/plan/build provided exists (TODO: use cache to check exists, provide more verbose error reason...), and returns false if not. Create methods assume desired entry provided is not already in the DB (TODO (again): use cache to check exists, provide more verbose error reason...), and returns false if not. It is by no means exhaustively implementing every TestLink API function. Designed with TestLink 1.9.9, but will likely work on (some) other versions.

CONSTRUCTOR

new (api_url, key)

Creates new TestLink::API object.

Returns TestLink::API object if login is successful.

my $tl = TestLink::API->new('http://tl.test/testlink/lib/api/xmlrpc/v1/xmlrpc.php', 'gobbledygook123');

PROPERTIES

    apiurl and apikey can be accessed/set:

    $url = $tl->apiurl; $tl = $tl->apiurl('http//some.new.url/foo.php');

CREATE METHODS

createTestPlan (name, project, [notes, active, public])

Creates new Test plan with given name in the given project.

STRING NAME - Desired test plan name.
STRING PROJECT - The name of some project existing in TestLink.
STRING NOTES (optional) - Additional description of test plan. Default value is 'res ipsa loquiter'
BOOLEAN ACTIVE (optional) - Whether or not the test plan is active. Default value is true.
BOOLEAN PUBLIC (optional) - Whether or not the test plan is public. Default is true.

Returns (integer) test plan ID if creation is successful.

my $tpid = $tl->createTestPlan('shock&awe', 'enduringfreedom');

createBuild (test_plan_id, name, [notes])

Creates new 'Build' (test run in common parlance) from given test plan having given name and notes.

INTEGER TEST PLAN ID - ID of test plan to base test run on.
STRING NAME - Desired name for test run.
STRING NOTES (optional) - Additional description of run. Default value is 'res ipsa loquiter'.

Returns true if case addition is successful, false otherwise.

$tl->createBuild(1234, "Bossin' up", 'Crushing our enemies, seeing them driven before us and hearing the lamentations of their support engineers.');

createTestSuite (project_id, name, [details, parent_testsuite_id, order])

Creates new TestSuite (folder of tests) in the database of test specifications under given project id having given name and details. Optionally, can have a parent test suite (this is an analog to a hierarchical file tree after all) and what order to have this suite be amongst it's peers.

INTEGER PROJECT ID - ID of project this test suite should be under.
STRING NAME - Desired name of test suite.
STRING DETAILS (optional) - Description of test suite. Default value is 'res ipsa loquiter'.
INTEGER PARENT TESTSUITE ID (optional) - Parent test suite ID. Defaults to top level of project.
INTEGER ORDER (optional) - Desired order amongst peer testsuites. Defaults to last in list.

Returns (integer) build ID on success, false otherwise.

$tl->createTestSuite(1, 'broken tests', 'Tests that should be reviewed', 2345, -1);

createTestProject (name, case_prefix, [notes, options, active, public])

Creates new Project (Database of testsuites/tests) with given name and case prefix. Optionally, can have notes, options, set the project as active/inactive and public/private.

STRING NAME - Desired name of project.
STRING CASE PREFIX - Desired prefix of project's external test case IDs.
STRING NOTES (optional) - Description of project. Default value is 'res ipsa loquiter'.
HASHREF{BOOLEAN} OPTIONS (optional) - Hash with keys: requirementsEnabled,testPriorityEnabled,automationEnabled,inventoryEnabled.
BOOLEAN ACTIVE (optional) - Whether to mark the project active or not. Default True.
BOOLEAN PUBLIC (optional) - Whether the project is public or not. Default true.

Returns (integer) project ID on success, false otherwise.

$tl->createTestProject('Widgetronic 4000', 'Tests for the whiz-bang new product', {'inventoryEnabled=>true}, true, true);

createTestCase (name, test_suite_id, test_project_id, author, summary, steps, preconditions, execution, order)

Creates new test case with given test suite id and project id. Author, Summary and Steps are mandatory for reasons that should be obvious to any experienced QA professional. Execution type and Test order is optional.

STRING NAME - Desired name of test case.
INTEGER TEST SUITE ID - ID of parent test suite.
INTEGER TEST PROJECT ID - ID of parent project
STRING AUTHOR - Author of test case.
STRING SUMMARY - Summary of test case.
STRING STEPS - Test steps.
STRING PRECONDITIONS - Prereqs for running the test, if any.
STRING EXECUTION (optional) - Execution type. Defaults to 'manual'.
INTEGER ORDER (optional) - Order of test amongst peers.

Returns (HASHREF) with Test Case ID and Test Case External ID on success, false otherwise.

$tl->createTestCase('Verify Whatsit Throbs at correct frequency', 123, 456, 'Gnaeus Pompieus Maximus', 'Make sure throbber on Whatsit doesn't work out of harmony with other throbbers', '1. Connect measurement harness. 2. ??? 3. PROFIT!', 'automated', 2);

SETTER METHODS

reportTCResult (case_id, test_plan_id, build_id, status, [platform, notes, bug id])

Report results of a test case with a given ID, plan and build ID. Set case results to status given. Platform is mandatory if available, otherwise optional. Notes and Bug Ids for whatever tracker you use are optional.

INTEGER CASE ID - Desired test case.
INTEGER TEST PLAN ID - ID of relevant test plan.
INTEGER BUILD ID - ID of relevant build.
STRING PLATFORM (semi-optional) - Relevant platform tested on. Accepts both platform name and ID, if it looks_like_number, uses platform_id
STRING NOTES (optional) - Relevant information gleaned during testing process.
STRING BUG ID (optional) - Relevant bug ID for regression tests, or if you auto-open bugs based on failures.

Returns project ID on success, false otherwise.

$tl->reportTCResult('T-1000', 7779311, 8675309, 'Tool Failure', 'Skynet Infiltration Model 1000', 'Catastrophic systems failure due to falling into vat of molten metal' 'TERMINATOR-2');

addTestCaseToTestPlan (test_plan_id, test_case_id, project_id, test_version, [sut_platform])

Creates new Test plan with given name in the given project.

INTEGER TEST PLAN ID - Desired test plan.
STRING TEST CASE ID - The 'external' name of some existing test in TestLink, e.g. TP-12.
INTEGER TEST VERSION - The desired version of the test to add.
STRING SUT PLATFORM (semi-optional) - The name of the desired platform to run on for this test (if any).
INTEGER EXECUTION ORDER (optional) - The order in which to execute this test amongst it's peers.
INTEGER URGENCY (optional) - The priority of the case in the plan.

Returns true if case addition is successful.

$tl->addTestCaseToTestPlan(666, 'cp-90210', 121, '3.11', 'OS2/WARP', 3, 1);

uploadExecutionAttachment (execution_id,filename,mimetype,content,[title,description])

Uploads the provided file and associates it with the given execution.

INTEGER EXECUTION ID - ID of a successful execution, such as the id key from the hash that is returned by reportTCResult.
STRING FILENAME - The name you want this file to appear as.
INTEGER MIMETYPE - The mimetype of the file uploaded, so we can tell the browser what to do with it when downloaded
INTEGER CONTENT - The base64 encoded content of the file you want to upload.
STRING TITLE (optional) - A title for this attachment.
INTEGER DESCRIPTION (optional) - A short description of who/what/why this was attached.

Returns true if attachment addition is successful.

$tl->uploadExecutionAttachment(1234, 'moo.txt', 'text/cow', APR::Base64::encode('MOO MOO MOOOOOO'), 'MOO', 'Test observed deranged bleatings of domestic ungulates, please investigate.');

uploadTestCaseAttachment (case_id,filename,mimetype,content,[title,description])

Uploads the provided file and associates it with the given execution.

INTEGER CASE ID - ID of desired test case
STRING FILENAME - The name you want this file to appear as.
INTEGER MIMETYPE - The mimetype of the file uploaded, so we can tell the browser what to do with it when downloaded
INTEGER CONTENT - The base64 encoded content of the file you want to upload.
STRING TITLE (optional) - A title for this attachment.
INTEGER DESCRIPTION (optional) - A short description of who/what/why this was attached.

Returns true if attachment addition is successful.

$tl->uploadTestCaseAttachment(1234, 'doStuff.t', 'text/perl', APR::Base64::encode($slurped_file_content), 'doStuff.t', 'Test File.');

GETTER METHODS

getProjects ()

Get all available projects

Returns array of project definition hashes, false otherwise.

$projects = $tl->getProjects;

getProjectByName ($project)

Gets some project definition hash by it's name

STRING PROJECT - desired project

Returns desired project def hash, false otherwise.

$projects = $tl->getProjectByName('FunProject');

getProjectByID ($project)

Gets some project definition hash by it's ID

INTEGER PROJECT - desired project

Returns desired project def hash, false otherwise.

$projects = $tl->getProjectByID(222);

getTLDTestSuitesForProject (project_id,get_tests)

Gets the testsuites in the top level of a project

STRING PROJECT ID - desired project's ID =item BOOLEAN GET TESTS - Get tests for suites returned, set them as 'tests' key in hash

Returns desired testsuites' definition hashes, 0 on error and -1 when there is no such project.

$projects = $tl->getTLDTestSuitesForProject(123);

getTestSuitesForTestSuite (testsuite_id,get_tests)

Gets the testsuites that are children of the provided testsuite.

STRING TESTSUITE ID - desired parent testsuite ID =item STRING GET TESTS - whether to get child tests as well

Returns desired testsuites' definition hashes, false otherwise.

$suites = $tl->getTestSuitesForTestSuite(123);
$suitesWithCases = $tl->getTestSuitesForTestSuite(123,1);

getTestSuitesByName (project_id,testsuite_name,do_regex)

Gets the testsuite(s) that match given name inside of given project name. WARNING: this will slurp the entire testsuite tree. This can take a while on large projects, but the results are cached so that subsequent calls are not as onerous.

STRING PROJECT ID - ID of project holding this testsuite
STRING TESTSUITE NAME - desired parent testsuite name
BOOLEAN DO REGEX (optional) - whether or not PROJECT NAME is a regex (default false, uses 'eq' to compare).

Returns desired testsuites' definition hashes, false otherwise.

$suites = $tl->getTestSuitesByName(321, 'hugSuite');
$suitesr = $tl->getTestSuitesByName(123, qr/^hug/, 1);

getTestSuiteByID (testsuite_id)

Gets the testsuite with the given ID.

STRING TESTSUITE_ID - TestSuite ID.

Returns desired testsuite definition hash, false otherwise.

$tests = $tl->getTestSuiteByID(123);

getTestCasesForTestSuite (testsuite_id,recurse,details)

Gets the testsuites that match given name inside of given project name.

STRING TESTSUITE_ID - TestSuite ID.
BOOLEAN RECURSE - Search testsuite tree recursively for tests below the provided testsuite
BOOLEAN RETURNMODE (optional) - whether or not to return more detailed test info (steps,summary,expected results). Defaults to false.

Returns desired case definition hashes, false otherwise.

$tests = $tl->getTestCasesForTestSuite(123,1,1);

getTestCaseByExternalId (case_id,version)

Gets the test case with the given external ID (e.g. projprefix-123) at provided version.

STRING CASE ID - desired external case ID
STRING VERSION - desired test case version. Defaults to most recent version.

Returns desired case definition hash, false otherwise.

$case = $tl->getTestCaseByExternalId('eee-123');

getTestCaseById (case_id,version)

Gets the test case with the given internal ID at provided version.

STRING CASE ID - desired internal case ID
STRING VERSION - desired test case version. Defaults to most recent version.

Returns desired case definition hash, false otherwise.

$case = $tl->getTestCaseById(28474,5);

getTestCaseByName (case_name,suite_name,project_name,tc_path_nameversion)

Gets the test case with the given internal ID at provided version.

STRING CASE NAME - desired internal case ID
STRING SUITE NAME - parent suite's name
STRING PROJECT NAME - parent project's name
STRING TC_PATH_NAME (optional)- Full path to TC. Please see documentation for more info: http://jetmore.org/john/misc/phpdoc-testlink193-api/TestlinkAPI/TestlinkXMLRPCServer.html#getTestCaseIDByName
STRING VERSION (optional)- desired test case version. Defaults to most recent version.

Returns desired case definition hash, false otherwise.

$case = $tl->getTestCaseByName('nugCase','gravySuite','chickenProject');

getTestCaseAttachments (case_ext_id)

Gets the attachments for some case.

STRING CASE ID - desired external case ID

Returns desired attachment definition hash, false otherwise. Content key is the file base64 encoded.

$att = $tl->getTestCaseAttachments('CP-222');

getTestPlansForProject (project_id)

Gets the test plans within given project id

STRING PROJECT ID - project ID

Returns desired test plan definition hashes, false otherwise.

$plans = $tl->getTestPlansForProject(23);

getTestPlanByName (plan_name,project_name)

Gets the test plan within given project name

STRING PLAN NAME - desired test plan name
STRING PROJECT NAME - project name

Returns desired test plan definition hash, false otherwise.

$suites = $tl->getTestPlanByName('nugs','gravy');

getBuildsForTestPlan (plan_id)

Gets the builds for given test plan

STRING PLAN ID - desired test plan ID

Returns desired builds' definition hashes, false otherwise.

$builds = $tl->getBuildsForTestPlan(1234);

getTestCasesForTestPlan (plan_id)

Gets the cases in provided test plan

STRING PLAN ID - desired test plan ID

Returns desired tests' definition hashes sorted by parent test plan ID, false otherwise.

Example output:
{ 1234 => [{case1},{case2},...], 33212 => [cases...]}

Example usage:
$builds = $tl->getTestCasesForTestPlan(1234);

getLatestBuildForTestPlan (plan_id)

Gets the latest build for the provided test plan

STRING PLAN ID - desired test plan ID

Returns desired build definition hash, false otherwise.

$build = $tl->getLatestBuildForTestPlan(1234);

getBuildByName (build_name,project_id)

Gets the desired build in project id by name

STRING BUILD NAME - desired build's name
INTEGER PROJECT ID - desired test project ID

Returns desired build definition hash, false otherwise.

$build = $tl->getBuildByName('foo',1234);

REPORTING METHODS

getTotalsForTestPlan (plan_id)

Gets the results summary for a test plan, even though what you really want is results by build/platform

INTEGER PLAN ID - desired test plan

Returns Hash describing test results.

$res = $tl->getTotalsForTestPlan(2322);

EXPORT/IMPORT METHODS

dump([project,get_attachments,flatten])

Return all info for all (or only the specified) projects. It will have the entire testsuite hierarchy and it's tests/attachments in an array of HASHREFs. The idea would be that you then could encode as JSON/XML as a backup, or to facilitate migration to other systems.

The project hashes will be what you would expect from getProjectByName calls. Those will have a key 'testsuites' with a list of it's child testsuites. These testsuites will themselves have 'testsuites' and 'test' keys describing their children. Both the test and testsuite hashes will have an 'attachment' parameter with the base64 encoded attachment as a string if the get_attachments option is passed.

WARNING: I have observed some locking related issues with cases/suites etc. Sometimes calls to get tests/suites during dumps fails, sometimes subsequent calls to getTestSuites/getTestCasesForTestSuite fail. If you are experiencing issues, try to put some wait() in there until it starts behaving right. Alternatively, just XML dump the whole project and use XML::Simple or your tool of choice to get the project tree.

ALSO: Attachment getting is not enabled due to the underlying XMLRPC calls appearing not to work. This option will be ignored until a workaround can be found.

INTEGER PROJECT NAME (optional) - desired project =item BOOLEAN GET ATTACHMENTS (optional) - whether or not to get attachments. Default false. UNIMPLEMENTED. =item BOOLEAN FLATTEN (optional) - Whether to return a flattened structure (you will need to correlate parent to child yourself, but this is faster due to not walking the tree). Preferred output for those not comfortable with doing tail recursion.

Returns ARRAYREF describing everything.

$ultradump = $tl->dump();
$dumpWithAtts = $tl->dump('TestProject',1);
$flatDump = $tl->dump('testProj',0,1);

SEE ALSO

XMLRPC::Lite

SPECIAL THANKS

cPanel, Inc. graciously funded the initial work on this project.

AUTHOR

George S. Baugh <teodesian@cpan.org>

CONTRIBUTOR

Neil Bowers <neil@bowers.com>

SOURCE

The development version is on github at http://github.com/teodesian/TestLink-Perl and may be cloned from git://github.com/teodesian/TestLink-Perl.git

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by George S. Baugh.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.