Fix #131: Allow filtering in getPlans

Changes

@@ -3,6 +3,7 @@ Revision history for Perl module TestRail::API
 0.040 2017-04-27 TEODESIAN
     - Fix performance issue in TestRail::Utils::Find::FindTests
     - Fix strange testsuite bug caused by regressions in MCE
+    - Allow filtering in TestRail::API::getPlans
 
 0.039 2017-03-07 TEODESIAN
     - Fix issue where follow_post_redirect could not be passed to constructor

dist.ini

@@ -132,6 +132,7 @@ stopwords = cachefile
 stopwords = getChildSections
 stopwords = POSTs
 stopwords = perfile
+stopwords = csv
 
 [PkgVersion]
 [AutoPrereqs]

lib/TestRail/API.pm

@@ -1573,7 +1573,7 @@ sub deletePlan {
     return $self->_doRequest("index.php?/api/v2/delete_plan/$plan_id",'POST');
 }
 
-=head2 B<getPlans (project_id)>
+=head2 B<getPlans (project_id,filters)>
 
 Gets all test plans in specified project.
 Like getRuns, must make multiple HTTP requests when the number of results exceeds 250.
@@ -1582,6 +1582,8 @@ Like getRuns, must make multiple HTTP requests when the number of results exceed
 
 =item INTEGER C<PROJECT ID> - ID of parent project.
 
+=item HASHREF C<FILTERS> - (optional) dictionary of filters, with keys corresponding to the documented filters for get_plans (other than limit/offset).
+
 =back
 
 Returns ARRAYREF of all plan definition HASHREFs in a project.
@@ -1591,11 +1593,27 @@ Returns ARRAYREF of all plan definition HASHREFs in a project.
 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.
 
+Possible filters:
+
+=over 4
+
+=item created_after (UNIX timestamp)
+
+=item created_before (UNIX timestamp)
+
+=item created_by (csv of ints) IDs of users plans were created by
+
+=item is_completed (bool)
+
+=item milestone_id (csv of ints) IDs of milestone assigned to plans
+
+=back
+
 =cut
 
 sub getPlans {
-    state $check = compile(Object, Int);
-    my ($self,$project_id) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[HashRef]]);
+    my ($self,$project_id, $filters) = $check->(@_);
 
     my $initial_plans = $self->getPlansPaginated($project_id,$self->{'global_limit'},0);
     return $initial_plans unless (reftype($initial_plans) || 'undef') eq 'ARRAY';
@@ -1603,14 +1621,14 @@ sub getPlans {
     push(@$plans,@$initial_plans);
     my $offset = 1;
     while (scalar(@$initial_plans) == $self->{'global_limit'}) {
-        $initial_plans = $self->getPlansPaginated($project_id,$self->{'global_limit'},($self->{'global_limit'} * $offset));
+        $initial_plans = $self->getPlansPaginated($project_id,$self->{'global_limit'},($self->{'global_limit'} * $offset),$filters);
         push(@$plans,@$initial_plans);
         $offset++;
     }
     return $plans;
 }
 
-=head2 B<getPlansPaginated (project_id,limit,offset)>
+=head2 B<getPlansPaginated (project_id,limit,offset,filters)>
 
 Get some plans for specified project.
 
@@ -1622,6 +1640,8 @@ Get some plans for specified project.
 
 =item INTEGER C<OFFSET> - Page of plans to return.
 
+=item HASHREF C<FILTERS> - (optional) other filters to apply to the requests.  See getPlans for more information.
+
 =back
 
 Returns ARRAYREF of plan definition HASHREFs.
@@ -1631,13 +1651,17 @@ Returns ARRAYREF of plan definition HASHREFs.
 =cut
 
 sub getPlansPaginated {
-    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]]);
-    my ($self,$project_id,$limit,$offset) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]], Optional[Maybe[HashRef]]);
+    my ($self,$project_id,$limit,$offset, $filters) = $check->(@_);
+    $filters //= {};
 
     confess("Limit greater than ".$self->{'global_limit'}) if $limit > $self->{'global_limit'};
     my $apiurl = "index.php?/api/v2/get_plans/$project_id";
     $apiurl .= "&offset=$offset" if defined($offset);
     $apiurl .= "&limit=$limit" if $limit; #You have problems if you want 0 results
+    foreach my $key (keys(%$filters)) {
+        $apiurl .= "&$key=$filters->{$key}";
+    }
     return $self->_doRequest($apiurl);
 }
 

t/TestRail-API.t

@@ -7,7 +7,7 @@ use lib "$FindBin::Bin/lib";
 use TestRail::API;
 use Test::LWP::UserAgent::TestRailMock;
 
-use Test::More tests => 90;
+use Test::More tests => 91;
 use Test::Fatal;
 use Test::Deep;
 use Scalar::Util ();
@@ -149,6 +149,7 @@ my $new_plan = $tr->createPlan($new_project->{'id'},$plan_name,"Soviet 5-year ag
 is($new_plan->{'name'},$plan_name,"Can create new plan");
 
 ok($tr->getPlans($new_project->{'id'}),"Can get list of plans");
+ok($tr->getPlans($new_project->{'id'},{ is_completed => 1, milestone_id => 3}),"Can get list of plans, filtered by milestone ID & completion status");
 my $namePlan = $tr->getPlanByName($new_project->{'id'},$plan_name);
 is($namePlan->{'name'},$plan_name,"Can get plan by name");
 is($tr->getPlanByID($new_plan->{'id'})->{'id'},$new_plan->{'id'},"Can get plan by ID");