v5 - better POD, require perl 5.10

Makefile.PL

@@ -1,8 +1,10 @@
+use 5.010; #Perl 5.10 minimum due to usage of undef or (//)
 use ExtUtils::MakeMaker;
 
 WriteMakefile(
     NAME              => "TestRail::API",
     VERSION_FROM      => "lib/TestRail/API.pm",
+    MIN_PERL_VERSION  => '5.010',
     TEST_REQUIRES     => {
         "Test::More"      => 0,
         "Scalar::Util"    => 0,

lib/TestRail/API.pm

@@ -1,11 +1,11 @@
 package TestRail::API;
 {
-    $TestRail::API::VERSION = '0.004';
+    $TestRail::API::VERSION = '0.005';
 }
 
 =head1 NAME
 
-TestLink::API - Provides an interface to TestLink's XMLRPC api via HTTP
+TestRail::API - Provides an interface to TestRail's REST api via HTTP
 
 =head1 SYNOPSIS
 
@@ -34,21 +34,19 @@ use LWP::UserAgent;
 
 =head1 CONSTRUCTOR
 
-=over 4
-
-=item B<new (api_url, user, password)>
+=head2 B<new (api_url, user, password)>
 
 Creates new C<TestRail::API> object.
 
 =over 4
 
-=item C<API URL> - base url for your TestRail api server.
+=item STRING C<API URL> - base url for your TestRail api server.
 
-=item C<USER> - Your testRail User.
+=item STRING C<USER> - Your testRail User.
 
-=item C<PASSWORD> - Your TestRail password.
+=item STRING C<PASSWORD> - Your TestRail password.
 
-=item C<DEBUG> - Print the JSON responses from TL with your requests.
+=item BOOLEAN C<DEBUG> - Print the JSON responses from TL with your requests.
 
 =back
 
@@ -56,8 +54,6 @@ Returns C<TestRail::API> object if login is successful.
 
     my $tr = TestRail::API->new('http://tr.test/testrail', 'moo','M000000!');
 
-=back
-
 =cut
 
 sub new {
@@ -139,15 +135,11 @@ sub _doRequest {
 
 =head1 USER METHODS
 
-=over 4
-
-=item B<getUsers ()>
+=head2 B<getUsers ()>
 
 Get all the user definitions for the provided Test Rail install.
 Returns ARRAYREF of user definition HASHREFs.
 
-=back
-
 =cut
 
 sub getUsers {
@@ -156,19 +148,15 @@ sub getUsers {
     return $self->{'user_cache'};
 }
 
-=over 4
-
-=item B<getUserByID(id)>
+=head2 B<getUserByID(id)>
 =cut
-=item B<getUserByName(name)>
+=head2 B<getUserByName(name)>
 =cut
-=item B<getUserByEmail(email)>
+=head2 B<getUserByEmail(email)>
 
 Get user definition hash by ID, Name or Email.
 Returns user def HASHREF.
 
-=back
-
 =cut
 
 
@@ -203,9 +191,7 @@ sub getUserByEmail {
 
 =head1 PROJECT METHODS
 
-=over 4
-
-=item B<createProject (name, [description,send_announcement])>
+=head2 B<createProject (name, [description,send_announcement])>
 
 Creates new Project (Database of testsuites/tests).
 Optionally specify an announcement to go out to the users.
@@ -225,8 +211,6 @@ Returns project definition HASHREF on success, false otherwise.
 
     $tl->createProject('Widgetronic 4000', 'Tests for the whiz-bang new product', true);
 
-=back
-
 =cut
 
 sub createProject {
@@ -245,9 +229,7 @@ sub createProject {
 
 }
 
-=over 4
-
-=item B<deleteProjectByID (id)>
+=head2 B<deleteProjectByID (id)>
 
 Deletes specified project by ID.
 Requires TestRail admin login.
@@ -262,8 +244,6 @@ Returns BOOLEAN.
 
     $success = $tl->deleteProject(1);
 
-=back
-
 =cut
 
 sub deleteProject {
@@ -272,9 +252,7 @@ sub deleteProject {
     return $result;
 }
 
-=over 4
-
-=item B<getProjects ()>
+=head2 B<getProjects ()>
 
 Get all available projects
 
@@ -282,8 +260,6 @@ Returns array of project definition HASHREFs, false otherwise.
 
     $projects = $tl->getProjects;
 
-=back
-
 =cut
 
 sub getProjects {
@@ -306,9 +282,7 @@ sub getProjects {
     return $result;
 }
 
-=over 4
-
-=item B<getProjectByName ($project)>
+=head2 B<getProjectByName ($project)>
 
 Gets some project definition hash by it's name
 
@@ -322,8 +296,6 @@ Returns desired project def HASHREF, false otherwise.
 
     $projects = $tl->getProjectByName('FunProject');
 
-=back
-
 =cut
 
 sub getProjectByName {
@@ -342,9 +314,7 @@ sub getProjectByName {
     return 0;
 }
 
-=over 4
-
-=item B<getProjectByID ($project)>
+=head2 B<getProjectByID ($project)>
 
 Gets some project definition hash by it's ID
 
@@ -358,8 +328,6 @@ Returns desired project def HASHREF, false otherwise.
 
     $projects = $tl->getProjectByID(222);
 
-=back
-
 =cut
 
 sub getProjectByID {
@@ -379,9 +347,7 @@ sub getProjectByID {
 }
 =head1 TESTSUITE METHODS
 
-=over 4
-
-=item B<createTestSuite (project_id, name, [description])>
+=head2 B<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.
 
@@ -399,8 +365,6 @@ Returns TS definition HASHREF on success, false otherwise.
 
     $tl->createTestSuite(1, 'broken tests', 'Tests that should be reviewed');
 
-=back
-
 =cut
 
 sub createTestSuite {
@@ -416,9 +380,8 @@ sub createTestSuite {
     return $result;
 
 }
-=over 4
 
-=item B<deleteTestSuite (suite_id)>
+=head2 B<deleteTestSuite (suite_id)>
 
 Deletes specified testsuite.
 
@@ -432,8 +395,6 @@ Returns BOOLEAN.
 
     $tl->deleteTestSuite(1);
 
-=back
-
 =cut
 
 sub deleteTestSuite {
@@ -444,9 +405,7 @@ sub deleteTestSuite {
 
 }
 
-=over 4
-
-=item B<getTestSuites (project_id,get_tests)>
+=head2 B<getTestSuites (project_id)>
 
 Gets the testsuites for a project
 
@@ -460,8 +419,6 @@ Returns ARRAYREF of testsuite definition HASHREFs, 0 on error.
 
     $suites = $tl->getTestSuites(123);
 
-=back
-
 =cut
 
 sub getTestSuites {
@@ -469,9 +426,7 @@ sub getTestSuites {
     return $self->_doRequest('index.php?/api/v2/get_suites/'.$proj);
 }
 
-=over 4
-
-=item B<getTestSuiteByName (project_id,testsuite_name)>
+=head2 B<getTestSuiteByName (project_id,testsuite_name)>
 
 Gets the testsuite that matches the given name inside of given project.
 
@@ -487,8 +442,6 @@ Returns desired testsuite definition HASHREF, false otherwise.
 
     $suites = $tl->getTestSuitesByName(321, 'hugSuite');
 
-=back
-
 =cut
 
 sub getTestSuiteByName {
@@ -504,9 +457,7 @@ sub getTestSuiteByName {
     return 0; #Couldn't find it
 }
 
-=over 4
-
-=item B<getTestSuiteByID (testsuite_id)>
+=head2 B<getTestSuiteByID (testsuite_id)>
 
 Gets the testsuite with the given ID.
 
@@ -520,8 +471,6 @@ Returns desired testsuite definition HASHREF, false otherwise.
 
     $tests = $tl->getTestSuiteByID(123);
 
-=back
-
 =cut
 
 sub getTestSuiteByID {
@@ -533,9 +482,7 @@ sub getTestSuiteByID {
 
 =head1 SECTION METHODS
 
-=over 4
-
-=item B<createSection(project_id,suite_id,name,[parent_id])>
+=head2 B<createSection(project_id,suite_id,name,[parent_id])>
 
 Creates a section.
 
@@ -555,7 +502,6 @@ Returns new section definition HASHREF, false otherwise.
 
     $section = $tr->createSection(1,1,'nugs',1);
 
-=back
 =cut
 
 sub createSection {
@@ -572,9 +518,7 @@ sub createSection {
 
 }
 
-=over 4
-
-=item B<deleteSection (section_id)>
+=head2 B<deleteSection (section_id)>
 
 Deletes specified section.
 
@@ -588,8 +532,6 @@ Returns BOOLEAN.
 
     $tr->deleteSection(1);
 
-=back
-
 =cut
 
 sub deleteSection {
@@ -600,9 +542,7 @@ sub deleteSection {
 
 }
 
-=over 4
-
-=item B<getSections (project_id,suite_id)>
+=head2 B<getSections (project_id,suite_id)>
 
 Gets sections for a given project and suite.
 
@@ -618,8 +558,6 @@ Returns ARRAYREF of section definition HASHREFs.
 
     $tr->getSections(1,2);
 
-=back
-
 =cut
 
 sub getSections {
@@ -627,9 +565,7 @@ sub getSections {
     return $self->_doRequest("index.php?/api/v2/get_sections/$project_id&suite_id=$suite_id");
 }
 
-=over 4
-
-=item B<getSectionByID (section_id)>
+=head2 B<getSectionByID (section_id)>
 
 Gets desired section.
 
@@ -645,8 +581,6 @@ Returns section definition HASHREF.
 
     $tr->getSectionByID(344);
 
-=back
-
 =cut
 
 sub getSectionByID {
@@ -654,9 +588,7 @@ sub getSectionByID {
     return $self->_doRequest("index.php?/api/v2/get_section/$section_id");
 }
 
-=over 4
-
-=item B<getSectionByName (project_id,suite_id,name)>
+=head2 B<getSectionByName (project_id,suite_id,name)>
 
 Gets desired section.
 
@@ -674,8 +606,6 @@ Returns section definition HASHREF.
 
     $tr->getSectionByName(1,2,'nugs');
 
-=back
-
 =cut
 
 sub getSectionByName {
@@ -689,9 +619,7 @@ sub getSectionByName {
 
 =head1 CASE METHODS
 
-=over 4
-
-=item B<getCaseTypes ()>
+=head2 B<getCaseTypes ()>
 
 Gets possible case types.
 
@@ -699,8 +627,6 @@ Returns ARRAYREF of case type definition HASHREFs.
 
     $tr->getCaseTypes();
 
-=back
-
 =cut
 
 sub getCaseTypes {
@@ -709,20 +635,20 @@ sub getCaseTypes {
     return $self->{'type_cache'};
 }
 
-=over 4
-
-=item B<getCaseTypeByName (name)>
+=head2 B<getCaseTypeByName (name)>
 
 Gets case type by name.
 
-=item C<NAME> STRING - Name of desired case type
+=over 4
+
+=item STRING C<NAME> - Name of desired case type
+
+=back
 
 Returns case type definition HASHREF.
 
     $tr->getCaseTypeByName();
 
-=back
-
 =cut
 
 sub getCaseTypeByName {
@@ -735,9 +661,7 @@ sub getCaseTypeByName {
     return 0;
 }
 
-=over 4
-
-=item B<createCase(section_id,title,type_id,options,extra_options)>
+=head2 B<createCase(section_id,title,type_id,options,extra_options)>
 
 Creates a test case.
 
@@ -772,8 +696,6 @@ Returns new case definition HASHREF, false otherwise.
 
     $case = $tr->createCase(1,'Do some stuff',3,$custom_opts,$other_opts);
 
-=back
-
 =cut
 
 sub createCase {
@@ -803,9 +725,7 @@ sub createCase {
     return $result;
 }
 
-=over 4
-
-=item B<deleteCase (case_id)>
+=head2 B<deleteCase (case_id)>
 
 Deletes specified section.
 
@@ -819,8 +739,6 @@ Returns BOOLEAN.
 
     $tr->deleteCase(1324);
 
-=back
-
 =cut
 
 sub deleteCase {
@@ -829,9 +747,7 @@ sub deleteCase {
     return $result;
 }
 
-=over 4
-
-=item B<getCases (project_id,suite_id,section_id)>
+=head2 B<getCases (project_id,suite_id,section_id)>
 
 Gets cases for provided section.
 
@@ -849,8 +765,6 @@ Returns ARRAYREF of test case definition HASHREFs.
 
     $tr->getCases(1,2,3);
 
-=back
-
 =cut
 
 sub getCases {
@@ -860,9 +774,7 @@ sub getCases {
     return $self->_doRequest($url);
 }
 
-=over 4
-
-=item B<getCaseByName (project_id,suite_id,section_id,name)>
+=head2 B<getCaseByName (project_id,suite_id,section_id,name)>
 
 Gets case by name.
 
@@ -882,8 +794,6 @@ Returns test case definition HASHREF.
 
     $tr->getCaseByName(1,2,3,'nugs');
 
-=back
-
 =cut
 
 sub getCaseByName {
@@ -895,9 +805,7 @@ sub getCaseByName {
     return 0;
 }
 
-=over 4
-
-=item B<getCaseByID (case_id)>
+=head2 B<getCaseByID (case_id)>
 
 Gets case by ID.
 
@@ -911,8 +819,6 @@ Returns test case definition HASHREF.
 
     $tr->getCaseByID(1345);
 
-=back
-
 =cut
 
 sub getCaseByID {
@@ -922,9 +828,7 @@ sub getCaseByID {
 
 =head1 RUN METHODS
 
-=over 4
-
-=item B<createRun (project_id)>
+=head2 B<createRun (project_id)>
 
 Create a run.
 
@@ -950,8 +854,6 @@ Returns run definition HASHREF.
 
     $tr->createRun(1,1345,'RUN AWAY','SO FAR AWAY',22,3,[3,4,5,6]);
 
-=back
-
 =cut
 
 #If you pass an array of case ids, it implies include_all is false
@@ -972,9 +874,7 @@ sub createRun {
     return $result;
 }
 
-=over 4
-
-=item B<deleteRun (run_id)>
+=head2 B<deleteRun (run_id)>
 
 Deletes specified run.
 
@@ -988,8 +888,6 @@ Returns BOOLEAN.
 
     $tr->deleteRun(1324);
 
-=back
-
 =cut
 
 sub deleteRun {
@@ -998,9 +896,7 @@ sub deleteRun {
     return $result;
 }
 
-=over 4
-
-=item B<getRunByName (project_id,name)>
+=head2 B<getRunByName (project_id,name)>
 
 Gets run by name.
 
@@ -1016,8 +912,6 @@ Returns run definition HASHREF.
 
     $tr->getRunByName(1,'gravy');
 
-=back
-
 =cut
 
 sub getRuns {
@@ -1034,9 +928,7 @@ sub getRunByName {
     return 0;
 }
 
-=over 4
-
-=item B<getRunByID (run_id)>
+=head2 B<getRunByID (run_id)>
 
 Gets run by ID.
 
@@ -1050,8 +942,6 @@ Returns run definition HASHREF.
 
     $tr->getRunByID(7779311);
 
-=back
-
 =cut
 
 sub getRunByID {
@@ -1061,9 +951,7 @@ sub getRunByID {
 
 =head1 PLAN METHODS
 
-=over 4
-
-=item B<createRun (project_id,name,description,milestone_id,entries)>
+=head2 B<createRun (project_id,name,description,milestone_id,entries)>
 
 Create a run.
 
@@ -1091,8 +979,6 @@ Returns test plan definition HASHREF, or false on failure.
 
     $tr->createPlan(1,'Gosplan','Robo-Signed Soviet 5-year plan',22,$entries);
 
-=back
-
 =cut
 
 sub createPlan {
@@ -1109,9 +995,7 @@ sub createPlan {
     return $result;
 }
 
-=over 4
-
-=item B<deletePlan (plan_id)>
+=head2 B<deletePlan (plan_id)>
 
 Deletes specified plan.
 
@@ -1125,8 +1009,6 @@ Returns BOOLEAN.
 
     $tr->deletePlan(8675309);
 
-=back
-
 =cut
 
 sub deletePlan {
@@ -1135,9 +1017,7 @@ sub deletePlan {
     return $result;
 }
 
-=over 4
-
-=item B<getPlans (project_id)>
+=head2 B<getPlans (project_id)>
 
 Deletes specified plan.
 
@@ -1151,8 +1031,6 @@ Returns ARRAYREF of plan definition HASHREFs.
 
     $tr->getPlans(8);
 
-=back
-
 =cut
 
 sub getPlans {
@@ -1160,9 +1038,7 @@ sub getPlans {
     return $self->_doRequest("index.php?/api/v2/get_plans/$project_id");
 }
 
-=over 4
-
-=item B<getPlanByName (project_id,name)>
+=head2 B<getPlanByName (project_id,name)>
 
 Gets specified plan by name.
 
@@ -1178,8 +1054,6 @@ Returns plan definition HASHREF.
 
     $tr->getPlanByName(8,'GosPlan');
 
-=back
-
 =cut
 
 sub getPlanByName {
@@ -1191,9 +1065,7 @@ sub getPlanByName {
     return 0;
 }
 
-=over 4
-
-=item B<getPlanByID (plan_id)>
+=head2 B<getPlanByID (plan_id)>
 
 Gets specified plan by ID.
 
@@ -1207,8 +1079,6 @@ Returns plan definition HASHREF.
 
     $tr->getPlanByID(2);
 
-=back
-
 =cut
 
 sub getPlanByID {
@@ -1218,9 +1088,7 @@ sub getPlanByID {
 
 =head1 MILESTONE METHODS
 
-=over 4
-
-=item B<createMilestone (project_id,name,description,due_on)>
+=head2 B<createMilestone (project_id,name,description,due_on)>
 
 Create a milestone.
 
@@ -1240,8 +1108,6 @@ 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);
 
-=back
-
 =cut
 
 sub createMilestone {
@@ -1257,9 +1123,7 @@ sub createMilestone {
     return $result;
 }
 
-=over 4
-
-=item B<deleteMilestone (milestone_id)>
+=head2 B<deleteMilestone (milestone_id)>
 
 Deletes specified milestone.
 
@@ -1273,8 +1137,6 @@ Returns BOOLEAN.
 
     $tr->deleteMilestone(86);
 
-=back
-
 =cut
 
 sub deleteMilestone {
@@ -1283,9 +1145,7 @@ sub deleteMilestone {
     return $result;
 }
 
-=over 4
-
-=item B<getMilestones (project_id)>
+=head2 B<getMilestones (project_id)>
 
 Get milestones for some project.
 
@@ -1299,8 +1159,6 @@ Returns ARRAYREF of milestone definition HASHREFs.
 
     $tr->getMilestones(8);
 
-=back
-
 =cut
 
 sub getMilestones {
@@ -1308,9 +1166,7 @@ sub getMilestones {
     return $self->_doRequest("index.php?/api/v2/get_milestones/$project_id");
 }
 
-=over 4
-
-=item B<getMilestoneByName (project_id,name)>
+=head2 B<getMilestoneByName (project_id,name)>
 
 Gets specified milestone by name.
 
@@ -1326,8 +1182,6 @@ Returns milestone definition HASHREF.
 
     $tr->getMilestoneByName(8,'whee');
 
-=back
-
 =cut
 
 sub getMilestoneByName {
@@ -1339,9 +1193,7 @@ sub getMilestoneByName {
     return 0;
 }
 
-=over 4
-
-=item B<getMilestoneByID (plan_id)>
+=head2 B<getMilestoneByID (plan_id)>
 
 Gets specified milestone by ID.
 
@@ -1355,8 +1207,6 @@ Returns milestione definition HASHREF.
 
     $tr->getMilestoneByID(2);
 
-=back
-
 =cut
 
 sub getMilestoneByID {
@@ -1366,9 +1216,7 @@ sub getMilestoneByID {
 
 =head1 TEST METHODS
 
-=over 4
-
-=item B<getTests (run_id)>
+=head2 B<getTests (run_id)>
 
 Get tests for some run.
 
@@ -1382,8 +1230,6 @@ Returns ARRAYREF of test definition HASHREFs.
 
     $tr->getTests(8);
 
-=back
-
 =cut
 
 sub getTests {
@@ -1391,9 +1237,7 @@ sub getTests {
     return $self->_doRequest("index.php?/api/v2/get_tests/$run_id");
 }
 
-=over 4
-
-=item B<getTestByName (run_id,name)>
+=head2 B<getTestByName (run_id,name)>
 
 Gets specified test by name.
 
@@ -1409,8 +1253,6 @@ Returns test definition HASHREF.
 
     $tr->getTestByName(36,'wheeTest');
 
-=back
-
 =cut
 
 sub getTestByName {
@@ -1422,9 +1264,7 @@ sub getTestByName {
     return 0;
 }
 
-=over 4
-
-=item B<getTestByID (test_id)>
+=head2 B<getTestByID (test_id)>
 
 Gets specified test by ID.
 
@@ -1438,8 +1278,6 @@ Returns test definition HASHREF.
 
     $tr->getTestByID(222222);
 
-=back
-
 =cut
 
 sub getTestByID {
@@ -1447,16 +1285,12 @@ sub getTestByID {
     return $self->_doRequest("index.php?/api/v2/get_test/$test_id");
 }
 
-=over 4
-
-=item B<getTestResultFields()>
+=head2 B<getTestResultFields()>
 
 Gets custom fields that can be set for tests.
 
 Returns ARRAYREF of result definition HASHREFs.
 
-=back
-
 =cut
 
 sub getTestResultFields {
@@ -1464,16 +1298,12 @@ sub getTestResultFields {
     return $self->_doRequest('index.php?/api/v2/get_result_fields');
 }
 
-=over 4
-
-=item B<getPossibleTestStatuses()>
+=head2 B<getPossibleTestStatuses()>
 
 Gets all possible statuses a test can be set to.
 
 Returns ARRAYREF of status definition HASHREFs.
 
-=back
-
 =cut
 
 sub getPossibleTestStatuses {
@@ -1481,9 +1311,7 @@ sub getPossibleTestStatuses {
     return $self->_doRequest('index.php?/api/v2/get_statuses');
 }
 
-=over 4
-
-=item B<createTestResults(test_id,status_id,comment,options,custom_options)>
+=head2 B<createTestResults(test_id,status_id,comment,options,custom_options)>
 
 Creates a result entry for a test.
 
@@ -1514,8 +1342,6 @@ Returns result definition HASHREF.
 
     $res = $tr->createTestResults(1,2,'Test failed because it was all like WAAAAAAA when I poked it',$options,$custom_options);
 
-=back
-
 =cut
 
 sub createTestResults {
@@ -1543,9 +1369,7 @@ sub createTestResults {
     return $self->_doRequest("index.php?/api/v2/add_result/$test_id",'POST',$stuff);
 }
 
-=over 4
-
-=item B<getTestResults(test_id,limit)>
+=head2 B<getTestResults(test_id,limit)>
 
 Get the recorded results for desired test, limiting output to 'limit' entries.
 
@@ -1568,16 +1392,10 @@ sub getTestResults {
     return $self->_doRequest($url);
 }
 
-=over 4
-
-=item B<buildStepResults(content,expected,actual,status_id)>
+=head2 B<buildStepResults(content,expected,actual,status_id)>
 
 Convenience method to build the stepResult hashes seen in the custom options for getTestResults.
 
-=back
-
-=back
-
 =cut
 
 #Convenience method for building stepResults
@@ -1598,12 +1416,19 @@ __END__
 =head1 SEE ALSO
 
 L<Test::More>
+
 L<HTTP::Request>
+
 L<LWP::UserAgent>
+
 L<JSON::XS>
 
 http://docs.gurock.com/testrail-api2/start
 
 =head1 AUTHOR
 
-George Baugh (gbaugh@cpanel.net)
+George Baugh (george@troglodyne.net)
+
+=head1 SPECIAL THANKS
+
+Thanks to cPanel Inc, for graciously funding the creation of this module.