NAME

TestRail::API - Provides an interface to TestRail's REST api via HTTP

SYNOPSIS

    use TestRail::API;

    my $tr = TestRail::API->new($username, $password, $host);

DESCRIPTION

TestRail::API provides methods to access an existing TestRail account using API v2. You can then do things like look up tests, set statuses and create runs from lists of cases. It is by no means exhaustively implementing every TestRail API function.

CONSTRUCTOR

new (api_url, user, password)

Creates new TestRail::API object.

STRING API URL - base url for your TestRail api server.

STRING USER - Your testRail User.

STRING PASSWORD - Your TestRail password.

BOOLEAN DEBUG - Print the JSON responses from TL with your requests.

Returns TestRail::API object if login is successful.

    my $tr = TestRail::API->new('http://tr.test/testrail', 'moo','M000000!');

USER METHODS

getUsers ()

Get all the user definitions for the provided Test Rail install. Returns ARRAYREF of user definition HASHREFs.

getUserByID(id)

getUserByName(name)

getUserByEmail(email)

Get user definition hash by ID, Name or Email. Returns user def HASHREF.

PROJECT METHODS

createProject (name, [description,send_announcement])

Creates new Project (Database of testsuites/tests). Optionally specify an announcement to go out to the users. Requires TestRail admin login.

STRING NAME - Desired name of project.

STRING DESCRIPTION (optional) - Description of project. Default value is 'res ipsa loquiter'.

BOOLEAN SEND ANNOUNCEMENT (optional) - Whether to confront users with an announcement about your awesome project on next login. Default false.

Returns project definition HASHREF on success, false otherwise.

    $tl->createProject('Widgetronic 4000', 'Tests for the whiz-bang new product', true);

deleteProjectByID (id)

Deletes specified project by ID. Requires TestRail admin login.

STRING NAME - Desired name of project.

Returns BOOLEAN.

    $success = $tl->deleteProject(1);

getProjects ()

Get all available projects

Returns array of project definition HASHREFs, false otherwise.

    $projects = $tl->getProjects;

getProjectByName ($project)

Gets some project definition hash by it's name

STRING PROJECT - desired project

Returns desired project def HASHREF, 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 HASHREF, false otherwise.

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

TESTSUITE METHODS

createTestSuite (project_id, name, [description])

Creates new TestSuite (folder of tests) in the database of test specifications under given project id having given name and details.

INTEGER PROJECT ID - ID of project this test suite should be under.

STRING NAME - Desired name of test suite.

STRING DESCRIPTION (optional) - Description of test suite. Default value is 'res ipsa loquiter'.

Returns TS definition HASHREF on success, false otherwise.

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

deleteTestSuite (suite_id)

Deletes specified testsuite.

INTEGER SUITE ID - ID of testsuite to delete.

Returns BOOLEAN.

    $tl->deleteTestSuite(1);

getTestSuites (project_id)

Gets the testsuites for a project

STRING PROJECT ID - desired project's ID

Returns ARRAYREF of testsuite definition HASHREFs, 0 on error.

    $suites = $tl->getTestSuites(123);

getTestSuiteByName (project_id,testsuite_name)

Gets the testsuite that matches the given name inside of given project.

STRING PROJECT ID - ID of project holding this testsuite

STRING TESTSUITE NAME - desired parent testsuite name

Returns desired testsuite definition HASHREF, false otherwise.

    $suites = $tl->getTestSuitesByName(321, 'hugSuite');

getTestSuiteByID (testsuite_id)

Gets the testsuite with the given ID.

STRING TESTSUITE_ID - Testsuite ID.

Returns desired testsuite definition HASHREF, false otherwise.

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

SECTION METHODS

createSection(project_id,suite_id,name,[parent_id])

Creates a section.

INTEGER PROJECT ID - Parent Project ID.

INTEGER SUITE ID - Parent Testsuite ID.

STRING NAME - desired section name.

INTEGER PARENT ID (optional) - parent section id

Returns new section definition HASHREF, false otherwise.

    $section = $tr->createSection(1,1,'nugs',1);

deleteSection (section_id)

Deletes specified section.

INTEGER SECTION ID - ID of section to delete.

Returns BOOLEAN.

    $tr->deleteSection(1);

getSections (project_id,suite_id)

Gets sections for a given project and suite.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of suite to get sections for.

Returns ARRAYREF of section definition HASHREFs.

    $tr->getSections(1,2);

getSectionByID (section_id)

Gets desired section.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of suite to get sections for.

Returns section definition HASHREF.

    $tr->getSectionByID(344);

getSectionByName (project_id,suite_id,name)

Gets desired section.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of suite to get section for.

STRING NAME - name of section to get

Returns section definition HASHREF.

    $tr->getSectionByName(1,2,'nugs');

CASE METHODS

getCaseTypes ()

Gets possible case types.

Returns ARRAYREF of case type definition HASHREFs.

    $tr->getCaseTypes();

getCaseTypeByName (name)

Gets case type by name.

STRING NAME - Name of desired case type

Returns case type definition HASHREF.

    $tr->getCaseTypeByName();

createCase(section_id,title,type_id,options,extra_options)

Creates a test case.

INTEGER SECTION ID - Parent Project ID.

STRING TITLE - Case title.

INTEGER TYPE_ID - desired test type's ID.

HASHREF OPTIONS (optional) - Custom fields in the case are the keys, set to the values provided. See TestRail API documentation for more info.

HASHREF EXTRA OPTIONS (optional) - contains priority_id, estimate, milestone_id and refs as possible keys. See TestRail API documentation for more info.

Returns new case definition HASHREF, false otherwise.

    $custom_opts = {
        preconds => "Test harness installed",
        steps         => "Do the needful",
        expected      => "cubicle environment transforms into Dali painting"
    };

    $other_opts = {
        priority_id => 4,
        milestone_id => 666,
        estimate    => '2m 45s',
        refs => ['TRACE-22','ON-166'] #ARRAYREF of bug IDs.
    }

    $case = $tr->createCase(1,'Do some stuff',3,$custom_opts,$other_opts);

deleteCase (case_id)

Deletes specified section.

INTEGER CASE ID - ID of case to delete.

Returns BOOLEAN.

    $tr->deleteCase(1324);

getCases (project_id,suite_id,section_id)

Gets cases for provided section.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of parent suite.

INTEGER SECTION ID - ID of parent section

Returns ARRAYREF of test case definition HASHREFs.

    $tr->getCases(1,2,3);

getCaseByName (project_id,suite_id,section_id,name)

Gets case by name.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of parent suite.

INTEGER SECTION ID - ID of parent section.

STRING <NAME> - Name of desired test case.

Returns test case definition HASHREF.

    $tr->getCaseByName(1,2,3,'nugs');

getCaseByID (case_id)

Gets case by ID.

INTEGER CASE ID - ID of case.

Returns test case definition HASHREF.

    $tr->getCaseByID(1345);

RUN METHODS

createRun (project_id)

Create a run.

INTEGER PROJECT ID - ID of parent project.

INTEGER SUITE ID - ID of suite to base run on

STRING NAME - Name of run

STRING DESCRIPTION (optional) - Description of run

INTEGER MILESTONE_ID (optional) - ID of milestone

INTEGER ASSIGNED_TO_ID (optional) - User to assign the run to

ARRAYREF CASE IDS (optional) - Array of case IDs in case you don't want to use the whole testsuite when making the build.

Returns run definition HASHREF.

    $tr->createRun(1,1345,'RUN AWAY','SO FAR AWAY',22,3,[3,4,5,6]);

deleteRun (run_id)

Deletes specified run.

INTEGER RUN ID - ID of run to delete.

Returns BOOLEAN.

    $tr->deleteRun(1324);

getRunByName (project_id,name)

Gets run by name.

INTEGER PROJECT ID - ID of parent project.

STRING <NAME> - Name of desired run.

Returns run definition HASHREF.

    $tr->getRunByName(1,'gravy');

getRunByID (run_id)

Gets run by ID.

INTEGER RUN ID - ID of desired run.

Returns run definition HASHREF.

    $tr->getRunByID(7779311);

PLAN METHODS

createRun (project_id,name,description,milestone_id,entries)

Create a run.

INTEGER PROJECT ID - ID of parent project.

STRING NAME - Name of plan

STRING DESCRIPTION (optional) - Description of plan

INTEGER MILESTONE_ID (optional) - ID of milestone

ARRAYREF ENTRIES (optional) - New Runs to initially populate the plan with -- See TestLink API documentation for more advanced inputs here.

Returns test plan definition HASHREF, or false on failure.

    $entries = {
        suite_id => 345,
        include_all => Types::Serialiser::true,
        assignedto_id => 1
    }

    $tr->createPlan(1,'Gosplan','Robo-Signed Soviet 5-year plan',22,$entries);

deletePlan (plan_id)

Deletes specified plan.

INTEGER PLAN ID - ID of plan to delete.

Returns BOOLEAN.

    $tr->deletePlan(8675309);

getPlans (project_id)

Deletes specified plan.

INTEGER PROJECT ID - ID of parent project.

Returns ARRAYREF of plan definition HASHREFs.

    $tr->getPlans(8);

getPlanByName (project_id,name)

Gets specified plan by name.

INTEGER PROJECT ID - ID of parent project.

STRING NAME - Name of test plan.

Returns plan definition HASHREF.

    $tr->getPlanByName(8,'GosPlan');

getPlanByID (plan_id)

Gets specified plan by ID.

INTEGER PLAN ID - ID of plan.

Returns plan definition HASHREF.

    $tr->getPlanByID(2);

MILESTONE METHODS

createMilestone (project_id,name,description,due_on)

Create a milestone.

INTEGER PROJECT ID - ID of parent project.

STRING NAME - Name of milestone

STRING DESCRIPTION (optional) - Description of milestone

INTEGER DUE_ON - Date at which milestone should be completed. Unix Timestamp.

Returns milestone definition HASHREF, or false on failure.

    $tr->createMilestone(1,'Patriotic victory of world perlism','Accomplish by Robo-Signed Soviet 5-year plan',time()+157788000);

deleteMilestone (milestone_id)

Deletes specified milestone.

INTEGER MILESTONE ID - ID of milestone to delete.

Returns BOOLEAN.

    $tr->deleteMilestone(86);

getMilestones (project_id)

Get milestones for some project.

INTEGER PROJECT ID - ID of parent project.

Returns ARRAYREF of milestone definition HASHREFs.

    $tr->getMilestones(8);

getMilestoneByName (project_id,name)

Gets specified milestone by name.

INTEGER PROJECT ID - ID of parent project.

STRING NAME - Name of milestone.

Returns milestone definition HASHREF.

    $tr->getMilestoneByName(8,'whee');

getMilestoneByID (plan_id)

Gets specified milestone by ID.

INTEGER MILESTONE ID - ID of milestone.

Returns milestione definition HASHREF.

    $tr->getMilestoneByID(2);

TEST METHODS

getTests (run_id)

Get tests for some run.

INTEGER RUN ID - ID of parent run.

Returns ARRAYREF of test definition HASHREFs.

    $tr->getTests(8);

getTestByName (run_id,name)

Gets specified test by name.

INTEGER RUN ID - ID of parent run.

STRING NAME - Name of milestone.

Returns test definition HASHREF.

    $tr->getTestByName(36,'wheeTest');

getTestByID (test_id)

Gets specified test by ID.

INTEGER TEST ID - ID of test.

Returns test definition HASHREF.

    $tr->getTestByID(222222);

getTestResultFields()

Gets custom fields that can be set for tests.

Returns ARRAYREF of result definition HASHREFs.

getPossibleTestStatuses()

Gets all possible statuses a test can be set to.

Returns ARRAYREF of status definition HASHREFs.

createTestResults(test_id,status_id,comment,options,custom_options)

Creates a result entry for a test.

Returns result definition HASHREF.

    $options = {
        elapsed => '30m 22s',
        defects => ['TSR-3','BOOM-44'],
        version => '6969'
    };

    $custom_options = {
        step_results => [
            {
                content   => 'Step 1',
                expected  => "Bought Groceries",
                actual    => "No Dinero!",
                status_id => 2
            },
            {
                content   => 'Step 2',
                expected  => 'Ate Dinner',
                actual    => 'Went Hungry',
                status_id => 2
            }
        ]
    };

    $res = $tr->createTestResults(1,2,'Test failed because it was all like WAAAAAAA when I poked it',$options,$custom_options);

getTestResults(test_id,limit)

Get the recorded results for desired test, limiting output to 'limit' entries.

INTEGER TEST_ID - ID of desired test

POSITIVE INTEGER LIMIT - provide no more than this number of results.

Returns ARRAYREF of result definition HASHREFs.

buildStepResults(content,expected,actual,status_id)

Convenience method to build the stepResult hashes seen in the custom options for getTestResults.

SEE ALSO

Test::More

HTTP::Request

LWP::UserAgent

JSON::XS

http://docs.gurock.com/testrail-api2/start

AUTHOR

George Baugh <teodesian@cpan.org>

SPECIAL THANKS

Thanks to cPanel Inc, for graciously funding the creation of this module.

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.

cpanm TestRail::API

perl -MCPAN -e shell
install TestRail::API