TestRail::API - Provides an interface to TestRail's REST api via HTTP
version 0.052
use TestRail::API; my ($username,$password,$host) = ('foo','bar','http://testrail.baz.foo'); my $tr = TestRail::API->new($host, $username, $password);
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.
TestRail::API
All the methods aside from the constructor should not die, but return a false value upon failure (see exceptions below). When the server is not responsive, expect a -500 response, and retry accordingly by setting the num_tries parameter in the constructor.
Also, all *ByName methods are vulnerable to duplicate naming issues. Try not to use the same name for:
* projects * testsuites within the same project * sections within the same testsuite that are peers * test cases * test plans and runs outside of plans which are not completed * configurations
To do so will result in the first of said item found being returned rather than an array of possibilities to choose from.
There are two exceptions to this, in the case of 401 and 403 responses, as these failing generally mean your program has no chance of success anyways.
Creates new TestRail::API object.
API URL
USER
PASSWORD
ENCODING
DEBUG
DO_POST_REDIRECT
MAX_TRIES
USER_FETCH_OPTS
skip_userfetch
This will save you some time on servers with quite a few users, especially if you don't particularly have a need to know about things related to TR users themselves. If you do need this info, you don't really save any time, however, as it will fetch them in the relevant subroutines that need this information.
Also, on newer versions of TestRail, user fetching is not possible unless you either: * Are an administrator on the server * Provide the project_id (https://www.gurock.com/testrail/docs/api/reference/users)
project_id
Returns TestRail::API object if login is successful.
my $tr = TestRail::API->new('http://tr.test/testrail', 'moo','M000000!');
Dies on all communication errors with the TestRail server. Does not do above checks if debug is passed.
Accessors for these parameters you pass into the constructor, in case you forget.
There is no getter/setter for this parameter, but it is worth mentioning. This is the number of seconds to wait between failed request retries when max_retries > 1.
#Do something other than the default of 5s, like spam the server mercilessly $tr->{retry_delay} = 0; ...
Get all the user definitions for the provided Test Rail install. Returns ARRAYREF of user definition HASHREFs.
Get user definition hash by ID, Name or Email. Returns user definition HASHREF.
For efficiency's sake, these methods cache the result of getUsers until you explicitly run it again.
Convenience method to translate a list of user names to TestRail user IDs.
NAMES
Returns ARRAY of user IDs.
Throws an exception in the case of one (or more) of the names not corresponding to a valid username.
Creates new Project (Database of testsuites/tests). Optionally specify an announcement to go out to the users. Requires TestRail admin login.
NAME
DESCRIPTION
SEND ANNOUNCEMENT
Returns project definition HASHREF on success, false otherwise.
$tl->createProject('Widgetronic 4000', 'Tests for the whiz-bang new product', true);
Deletes specified project by ID. Requires TestRail admin login.
Returns BOOLEAN.
$success = $tl->deleteProject(1);
Get all available projects
FILTERS
Returns array of project definition HASHREFs, false otherwise.
$projects = $tl->getProjects;
See:
L<https://www.gurock.com/testrail/docs/api/reference/projects#getprojects>
for details as to the allowable filter keys.
Gets some project definition hash by it's name
PROJECT
Returns desired project definition HASHREF, false otherwise.
$project = $tl->getProjectByName('FunProject');
Gets some project definition hash by it's ID
$projects = $tl->getProjectByID(222);
Creates new TestSuite (folder of tests) in the database of test specifications under given project id having given name and details.
PROJECT ID
Returns TS definition HASHREF on success, false otherwise.
$tl->createTestSuite(1, 'broken tests', 'Tests that should be reviewed');
Deletes specified testsuite.
SUITE ID
$tl->deleteTestSuite(1);
Gets the testsuites for a project
Returns ARRAYREF of testsuite definition HASHREFs, 0 on error.
$suites = $tl->getTestSuites(123);
Gets the testsuite that matches the given name inside of given project.
TESTSUITE NAME
Returns desired testsuite definition HASHREF, false otherwise.
$suites = $tl->getTestSuitesByName(321, 'hugSuite');
Gets the testsuite with the given ID.
TESTSUITE_ID
$tests = $tl->getTestSuiteByID(123);
Creates a section.
PARENT ID
Returns new section definition HASHREF, false otherwise.
$section = $tr->createSection(1,1,'nugs',1);
Deletes specified section.
SECTION ID
$tr->deleteSection(1);
Gets sections for a given project and suite.
Returns ARRAYREF of section definition HASHREFs.
$tr->getSections(1,2);
Gets desired section.
Returns section definition HASHREF.
$tr->getSectionByID(344);
$tr->getSectionByName(1,2,'nugs');
Gets desired section's child sections.
PROJECT_ID
SECTION
Returns ARRAYREF of section definition HASHREF. ARRAYREF is empty if there are none.
Recursively searches for children, so the children of child sections will be returned as well.
$tr->getChildSections($section);
Convenience method to translate a list of section names to TestRail section IDs.
Returns ARRAY of section IDs.
Throws an exception in the case of one (or more) of the names not corresponding to a valid section name.
Gets possible case types.
Returns ARRAYREF of case type definition HASHREFs.
$tr->getCaseTypes();
Gets case type by name.
Returns case type definition HASHREF. Dies if named case type does not exist.
$tr->getCaseTypeByName();
Convenience method to translate a list of case type names to TestRail case type IDs.
Returns ARRAY of type IDs in the same order as the type names passed.
Throws an exception in the case of one (or more) of the names not corresponding to a valid case type.
Creates a test case.
TITLE
TYPE_ID
OPTIONS
EXTRA OPTIONS
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);
Updates a test case.
CASE ID
Deletes specified test case.
$tr->deleteCase(1324);
Gets cases for provided section.
L<http://docs.gurock.com/testrail-api2/reference-cases#get_cases>
If the section ID is omitted, all cases for the suite will be returned. Returns ARRAYREF of test case definition HASHREFs.
$tr->getCases(1,2, {'section_id' => 3} );
Gets case by name.
Returns test case definition HASHREF.
$tr->getCaseByName(1,2,'nugs', {'section_id' => 3});
Gets case by ID.
$tr->getCaseByID(1345);
Returns ARRAYREF of available test case custom fields.
$tr->getCaseFields();
Output is cached in the case_fields parameter. Cache is invalidated when addCaseField is called.
Returns HASHREF describing the case field you just added.
$tr->addCaseField(%options)
Gets possible priorities.
Returns ARRAYREF of priority definition HASHREFs.
$tr->getPriorities();
Gets priority by name.
Returns priority definition HASHREF. Dies if named priority does not exist.
$tr->getPriorityByName();
Convenience method to translate a list of priority names to TestRail priority IDs.
Returns ARRAY of priority IDs in the same order as the priority names passed.
Throws an exception in the case of one (or more) of the names not corresponding to a valid priority.
Create a run.
MILESTONE ID
ASSIGNED TO ID
CASE IDS
Returns run definition HASHREF.
$tr->createRun(1,1345,'RUN AWAY','SO FAR AWAY',22,3,[3,4,5,6]);
Deletes specified run.
RUN ID
$tr->deleteRun(1324);
Get all runs for specified project. To do this, it must make (no. of runs/250) HTTP requests. This is due to the maximum result set limit enforced by testrail.
Returns ARRAYREF of run definition HASHREFs.
$allRuns = $tr->getRuns(6969);
Possible filters:
Get some runs for specified project.
LIMIT
OFFSET
$someRuns = $tr->getRunsPaginated(6969,22,4);
Gets run by name.
$tr->getRunByName(1,'R2');
Gets run by ID.
$tr->getRunByID(7779311);
Close the specified run.
Returns run definition HASHREF on success, false on failure.
$tr->closeRun(90210);
Returns array of hashrefs describing the # of tests in the run(s) with the available statuses. Translates custom_statuses into their system names for you.
RUNS
Returns ARRAY of run HASHREFs with the added key 'run_status' holding a hashref where status_name => count.
$tr->getRunSummary($run,$run2);
Returns array of hashrefs describing the results of the run.
Warning: This only returns the most recent results of a run. If you want to know about the tortured journey a test may have taken to get to it's final status, you will need to use getTestResults.
RUN_ID
Extract the child runs from a plan. Convenient, as the structure of this hash is deep, and correct error handling can be tedious.
PLAN
Returns ARRAYREF of run definition HASHREFs. Returns 0 upon failure to extract the data.
CONFIGURATIONS
Returns run definition HASHREF, or false if no such run is found. Convenience method using getChildRuns.
Will throw a fatal error if one or more of the configurations passed does not exist in the project.
Create a test plan.
MILESTONE_ID
ENTRIES
Returns test plan definition HASHREF, or false on failure.
$entries = [{ suite_id => 345, include_all => 1, assignedto_id => 1 }]; $tr->createPlan(1,'Gosplan','Robo-Signed Soviet 5-year plan',22,$entries);
Deletes specified plan.
PLAN ID
$tr->deletePlan(8675309);
Gets all test plans in specified project. Like getRuns, must make multiple HTTP requests when the number of results exceeds 250.
Returns ARRAYREF of all plan definition HASHREFs in a project.
$tr->getPlans(8);
Does not contain any information about child test runs. Use getPlanByID or getPlanByName if you want that, in particular if you are interested in using getChildRunByName.
Get some plans for specified project.
Returns ARRAYREF of plan definition HASHREFs.
$someRuns = $tr->getPlansPaginated(6969,222,44);
Gets specified plan by name.
Returns plan definition HASHREF.
$tr->getPlanByName(8,'GosPlan');
Gets specified plan by ID.
$tr->getPlanByID(2);
Returns hashref describing the various pass, fail, etc. percentages for tests in the plan. The 'totals' key has total cases in each status ('status' => count) The 'percentages' key has the same, but as a percentage of the total.
plan_ID
$tr->getPlanSummary($plan_id);
Create a run in a plan.
CONFIG IDS
$tr->createRun(1,1345,'PlannedRun',3,[1,4,77],[3,4,5,6]);
Close the specified plan.
Returns plan definition HASHREF on success, false on failure.
$tr->closePlan(75020);
Create a milestone.
DUE_ON
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);
Deletes specified milestone.
$tr->deleteMilestone(86);
Get milestones for some project.
L<https://www.gurock.com/testrail/docs/api/reference/milestones#getmilestones>
Returns ARRAYREF of milestone definition HASHREFs.
$tr->getMilestones(8);
Gets specified milestone by name.
Returns milestone definition HASHREF.
$tr->getMilestoneByName(8,'whee');
Gets specified milestone by ID.
$tr->getMilestoneByID(2);
Get tests for some run. Optionally filter by provided status_ids and assigned_to ids.
STATUS IDS
ASSIGNEDTO IDS
Returns ARRAYREF of test definition HASHREFs.
$tr->getTests(8,[1,2,3],[2]);
Gets specified test by name.
This is done by getting the list of all tests in the run and then picking out the relevant test. As such, for efficiency the list of tests is cached. The cache may be refreshed, or restricted by running getTests (with optional restrictions, such as assignedto_ids, etc).
Returns test definition HASHREF.
$tr->getTestByName(36,'wheeTest');
Gets specified test by ID.
TEST ID
$tr->getTestByID(222222);
Gets custom fields that can be set for tests.
Returns ARRAYREF of result definition HASHREFs.
Gets a test result field by it's system name. Optionally filter by project ID.
Returns a value less than 0 if unsuccessful.
Gets all possible statuses a test can be set to.
Returns ARRAYREF of status definition HASHREFs.
Caches the result for the lifetime of the TestRail::API object.
Convenience method to translate a list of statuses to TestRail status IDs. The names referred to here are 'internal names' rather than the labels shown in TestRail.
Returns ARRAY of status IDs in the same order as the status names passed.
Throws an exception in the case of one (or more) of the names not corresponding to a valid test status.
Convenience method to translate a list of statuses to TestRail status labels (the 'nice' form of status names). This is useful when interacting with getRunSummary or getPlanSummary, which uses these labels as hash keys.
Returns ARRAY of status labels in the same order as the status names passed.
Creates a result entry for a test.
TEST_ID
STATUS_ID
COMMENT
CUSTOM OPTIONS
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);
Add multiple results to a run, where each result is a HASHREF with keys as outlined in the get_results API call documentation.
RESULTS
Basically the same as bulkAddResults, but instead of a test_id for each entry you use a case_id.
Get the recorded results for desired test, limiting output to 'limit' entries.
L<https://www.gurock.com/testrail/docs/api/reference/results#getresults>
Get the recorded results for a test run and case combination., limiting output to 'limit' entries.
CASE_ID
L<https://www.gurock.com/testrail/docs/api/reference/results#getresultsforcase>
Gets the available configuration groups for a project, with their configurations as children.
Returns ARRAYREF of configuration group definition HASHREFs.
Get the provided configuration group by name.
Returns false if the configuration group could not be found.
New in TestRail 5.2.
Add a configuration group to the specified project.
Returns HASHREF with new configuration group.
Change the name of a configuration group.
CONFIG_GROUP_ID
Delete a configuration group.
Returns BOOL.
Gets the available configurations for a project. Mostly for convenience (no need to write a boilerplate loop over the groups).
Returns ARRAYREF of configuration definition HASHREFs. Returns result of getConfigurationGroups (likely -500) in the event that call fails.
Add a configuration to the specified configuration group.
CONFIGURATION_GROUP_ID
Returns HASHREF with new configuration.
Change the name of a configuration.
CONFIG_ID
Delete a configuration.
Transforms a list of configuration names into a list of config IDs.
CONFIGS
Returns ARRAY of configuration names, with undef values for unknown configuration names.
Return the ARRAYREF of reports available for the provided project.
Requires you to mark a particular report as accessible in the API via the TestRail report interface.
Compute the provided report using currently available data.
Returns HASHREF describing URLs to access completed reports.
REPORT_ID
Convenience method to build the stepResult hashes seen in the custom options for getTestResults.
CONTENT
EXPECTED
ACTUAL
STATUS ID
HTTP::Request
LWP::UserAgent
JSON::MaybeXS
http://docs.gurock.com/testrail-api2/start
Thanks to cPanel Inc, for graciously funding the creation of this module.
George S. Baugh <teodesian@cpan.org>
Andy Baugh <thomas.baugh@cpanel.net>
George S. Baugh <doge@teodesian.net>
George S. Baugh <george.b@cpanel.net>
J. Nick Koston <nick@cpanel.net>
Matthew Spahr <matthew.spahr@cpanel.net>
Matthew Spahr <mpspahr@gmail.com>
Mohammad S Anwar <mohammad.anwar@yahoo.com>
Neil Bowers <neil@bowers.com>
Ryan Sherer <ryan.sherer@cpanel.net>
Todd Rinaldo <toddr@cpan.org>
The development version is on github at https://github.com/teodesian/TestRail-Perl and may be cloned from git://github.com/teodesian/TestRail-Perl.git
This software is copyright (c) 2022 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.
To install TestRail::API, copy and paste the appropriate command in to your terminal.
cpanm
cpanm TestRail::API
CPAN shell
perl -MCPAN -e shell install TestRail::API
For more information on module installation, please visit the detailed CPAN module installation guide.