Add missing filter support to more methods

Add filter support to the remaining methods that support filtering.
Add helper method to handle transforming the filters hashref, used
by methods that support filtering, to url parameters.

lib/TestRail/API.pm

@@ -457,21 +457,33 @@ sub deleteProject {
     return $self->_doRequest('index.php?/api/v2/delete_project/'.$proj,'POST');
 }
 
-=head2 B<getProjects ()>
+=head2 B<getProjects (filters)>
 
 Get all available projects
 
+=over 4
+
+=item HASHREF C<FILTERS> (optional) - HASHREF describing parameters to filter cases by.
+
+=back
+
 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.
+
 =cut
 
 sub getProjects {
-    state $check = compile(Object);
-    my ($self) = $check->(@_);
-
-    my $result = $self->_doRequest('index.php?/api/v2/get_projects');
+    state $check = compile(Object,Optional[Maybe[HashRef]]);
+    my ($self,$filters) = $check->(@_);
+    
+    my $result = $self->_doRequest('index.php?/api/v2/get_projects' . _convert_filters_to_string($filters) );
 
     #Save state for future use, if needed
     return -500 if !$result || (reftype($result) || 'undef') ne 'ARRAY';
@@ -1110,20 +1122,7 @@ sub getCases {
     my ($self,$project_id,$suite_id,$filters) = $check->(@_);
 
     my $url = "index.php?/api/v2/get_cases/$project_id&suite_id=$suite_id";
-
-    my @valid_keys = qw{section_id created_after created_before created_by milestone_id priority_id type_id updated_after updated_before updated_by};
-
-
-    # Add in filters
-    foreach my $filter (keys(%$filters)) {
-        confess("Invalid filter key '$filter' passed") unless grep {$_ eq $filter} @valid_keys;
-        if (ref $filters->{$filter} eq 'ARRAY') {
-            confess "$filter cannot be an ARRAYREF" if grep {$_ eq $filter} qw{created_after created_before updated_after updated_before};
-            $url .= "&$filter=".join(',',@{$filters->{$filter}});
-        } else {
-            $url .= "&$filter=".$filters->{$filter} if defined($filters->{$filter});
-        }
-    }
+    $url .= _convert_filters_to_string($filters);
 
     return $self->_doRequest($url);
 }
@@ -1364,7 +1363,7 @@ sub deleteRun {
     return $self->_doRequest("index.php?/api/v2/delete_run/$run_id",'POST');
 }
 
-=head2 B<getRuns (project_id)>
+=head2 B<getRuns (project_id,filters)>
 
 Get all runs for specified project.
 To do this, it must make (no. of runs/250) HTTP requests.
@@ -1421,7 +1420,7 @@ sub getRuns {
     return $runs;
 }
 
-=head2 B<getRunsPaginated (project_id,limit,offset)>
+=head2 B<getRunsPaginated (project_id,limit,offset,filters)>
 
 Get some runs for specified project.
 
@@ -1433,7 +1432,7 @@ Get some runs for specified project.
 
 =item INTEGER C<OFFSET> - Page of runs to return.
 
-=item HASHREF C<FILTERS> - (optional) other filters to apply to the requests.  See getRuns for more information.
+=item HASHREF C<FILTERS> - (optional) other filters to apply to the requests other than limit/offset.  See getRuns for more information.
 
 =back
 
@@ -1446,15 +1445,12 @@ Returns ARRAYREF of run definition HASHREFs.
 sub getRunsPaginated {
     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_runs/$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}";
-    }
+    $apiurl .= _convert_filters_to_string($filters);
     return $self->_doRequest($apiurl);
 }
 
@@ -1596,34 +1592,35 @@ you will need to use getTestResults.
 =cut
 
 sub getRunResults {
-    state $check = compile(Object, Int);
-    my ($self,$run_id) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[HashRef]]);
+    my ($self,$run_id, $filters) = $check->(@_);
 
-    my $initial_results = $self->getRunResultsPaginated($run_id,$self->{'global_limit'},undef);
+    my $initial_results = $self->getRunResultsPaginated($run_id,$self->{'global_limit'},undef,$filters);
     return $initial_results unless (reftype($initial_results) || 'undef') eq 'ARRAY';
     my $results = [];
     push(@$results,@$initial_results);
     my $offset = 1;
     while (scalar(@$initial_results) == $self->{'global_limit'}) {
-        $initial_results = $self->getRunResultsPaginated($run_id,$self->{'global_limit'},($self->{'global_limit'} * $offset));
+        $initial_results = $self->getRunResultsPaginated($run_id,$self->{'global_limit'},($self->{'global_limit'} * $offset),$filters);
         push(@$results,@$initial_results);
         $offset++;
     }
     return $results;
 }
 
-=head2 B<getRunResultsPaginated(run_id,limit,offset)>
+=head2 B<getRunResultsPaginated(run_id,limit,offset,filters)>
 
 =cut
 
 sub getRunResultsPaginated {
-    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]]);
-    my ($self,$run_id,$limit,$offset) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]], Optional[Maybe[HashRef]]);
+    my ($self,$run_id,$limit,$offset,$filters) = $check->(@_);
 
     confess("Limit greater than ".$self->{'global_limit'}) if $limit > $self->{'global_limit'};
     my $apiurl = "index.php?/api/v2/get_results_for_run/$run_id";
     $apiurl .= "&offset=$offset" if defined($offset);
     $apiurl .= "&limit=$limit" if $limit; #You have problems if you want 0 results
+    $apiurl .= _convert_filters_to_string($filters);
     return $self->_doRequest($apiurl);
 }
 
@@ -1847,7 +1844,7 @@ 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.
+=item HASHREF C<FILTERS> - (optional) other filters to apply to the requests (other than limit/offset).  See getPlans for more information.
 
 =back
 
@@ -1860,15 +1857,12 @@ Returns ARRAYREF of plan definition HASHREFs.
 sub getPlansPaginated {
     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}";
-    }
+    $apiurl .= _convert_filters_to_string($filters);
     return $self->_doRequest($apiurl);
 }
 
@@ -2106,7 +2100,7 @@ sub deleteMilestone {
     return $self->_doRequest("index.php?/api/v2/delete_milestone/$milestone_id",'POST');
 }
 
-=head2 B<getMilestones (project_id)>
+=head2 B<getMilestones (project_id,filters)>
 
 Get milestones for some project.
 
@@ -2114,20 +2108,27 @@ Get milestones for some project.
 
 =item INTEGER C<PROJECT ID> - ID of parent project.
 
+=item HASHREF C<FILTERS> (optional) - HASHREF describing parameters to filter milestones by.
+
 =back
 
+See:
+
+    L<https://www.gurock.com/testrail/docs/api/reference/milestones#getmilestones>
+
+for details as to the allowable filter keys.
+
 Returns ARRAYREF of milestone definition HASHREFs.
 
     $tr->getMilestones(8);
 
-
 =cut
 
 sub getMilestones {
-    state $check = compile(Object, Int);
-    my ($self,$project_id) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[HashRef]]);
+    my ($self,$project_id, $filters) = $check->(@_);
 
-    return $self->_doRequest("index.php?/api/v2/get_milestones/$project_id");
+    return $self->_doRequest("index.php?/api/v2/get_milestones/$project_id" . _convert_filters_to_string($filters));
 }
 
 =head2 B<getMilestoneByName (project_id,name)>
@@ -2529,7 +2530,7 @@ sub bulkAddResultsByCase {
 }
 
 
-=head2 B<getTestResults(test_id,limit,offset)>
+=head2 B<getTestResults(test_id,limit,offset,filters)>
 
 Get the recorded results for desired test, limiting output to 'limit' entries.
 
@@ -2541,23 +2542,32 @@ Get the recorded results for desired test, limiting output to 'limit' entries.
 
 =item INTEGER C<OFFSET> (OPTIONAL) - Offset to begin viewing result set at.
 
+=item HASHREF C<FILTERS> (optional) - HASHREF describing parameters to filter test results by (other than limit/offset).
+
 =back
 
+See:
+
+    L<https://www.gurock.com/testrail/docs/api/reference/results#getresults>
+
+for details as to the allowable filter keys.
+
 Returns ARRAYREF of result definition HASHREFs.
 
 =cut
 
 sub getTestResults {
-    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]]);
-    my ($self,$test_id,$limit,$offset) = $check->(@_);
+    state $check = compile(Object, Int, Optional[Maybe[Int]], Optional[Maybe[Int]], Optional[Maybe[HashRef]]);
+    my ($self,$test_id,$limit,$offset,$filters) = $check->(@_);
 
     my $url = "index.php?/api/v2/get_results/$test_id";
     $url .= "&limit=$limit" if $limit;
     $url .= "&offset=$offset" if defined($offset);
+    $url .= _convert_filters_to_string($filters);
     return $self->_doRequest($url);
 }
 
-=head2 B<getResultsForCase(run_id,case_id,limit,offset)>
+=head2 B<getResultsForCase(run_id,case_id,limit,offset,filters)>
 
 Get the recorded results for a test run and case combination., limiting output to 'limit' entries.
 
@@ -2571,19 +2581,28 @@ Get the recorded results for a test run and case combination., limiting output t
 
 =item INTEGER C<OFFSET> (OPTIONAL) - Offset to begin viewing result set at.
 
+=item HASHREF C<FILTERS> (optional) - HASHREF describing parameters to filter by (other than limit/offset).
+
 =back
 
+See:
+
+    L<https://www.gurock.com/testrail/docs/api/reference/results#getresultsforcase>
+
+for details as to the allowable filter keys.
+
 Returns ARRAYREF of result definition HASHREFs.
 
 =cut
 
 sub getResultsForCase {
-    state $check = compile(Object, Int, Int, Optional[Maybe[Int]], Optional[Maybe[Int]]);
-    my ($self,$run_id,$case_id,$limit,$offset) = $check->(@_);
+    state $check = compile(Object, Int, Int, Optional[Maybe[Int]], Optional[Maybe[Int]], Optional[Maybe[HashRef]]);
+    my ($self,$run_id,$case_id,$limit,$offset,$filters) = $check->(@_);
 
     my $url = "index.php?/api/v2/get_results_for_case/$run_id/$case_id";
     $url .= "&limit=$limit" if $limit;
     $url .= "&offset=$offset" if defined($offset);
+    $url .= _convert_filters_to_string($filters);
     return $self->_doRequest($url);
 }
 
@@ -2911,6 +2930,28 @@ sub buildStepResults {
     };
 }
 
+# Convenience method for building filter string from filters Hashref
+sub _convert_filters_to_string {
+    state $check = compile(Maybe[HashRef]);
+    my ($filters) = $check->(@_);
+
+    $filters //= {};
+
+    my @valid_keys = qw{ is_completed limit offset created_after created_before filter refs section_id updated_after updated_before refs_filter defects_filter };
+    my @valid_arrayref_keys = qw{ created_by milestone_id priority_id template_id type_id updated_by suite_id status_id };
+
+    my $filter_string = '';
+    foreach my $filter (keys(%$filters)) {
+        confess("Invalid filter key '$filter' passed") unless grep {$_ eq $filter} (@valid_keys, @valid_arrayref_keys);
+        if (ref $filters->{$filter} eq 'ARRAY') {
+            confess "$filter cannot be an ARRAYREF" if grep {$_ eq $filter} @valid_keys;
+            $filter_string .= "&$filter=".join(',',@{$filters->{$filter}});
+        } else {
+            $filter_string .= "&$filter=".$filters->{$filter} if defined($filters->{$filter});
+        }
+    }
+    return $filter_string;
+}
 
 1;
 

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 => 95;
+use Test::More tests => 96;
 use Test::Fatal;
 use Test::Deep;
 use Scalar::Util ();
@@ -88,6 +88,7 @@ my $new_project = $tr->createProject($project_name,'Robo-Signed Soviet 5 Year Pr
 is($new_project->{'name'},$project_name,"Can create new project");
 
 ok($tr->getProjects(),"Get Projects returns list");
+ok($tr->getProjects({ is_completed => 1 }),"Get Projects returns a filtered list");
 is($tr->getProjectByName($project_name)->{'name'},$project_name,"Can get project by name");
 my $pjid = $tr->getProjectByID($new_project->{'id'});
 is(Scalar::Util::reftype($pjid) eq 'HASH' ? $pjid->{'id'} : $pjid,$new_project->{'id'},"Can get project by id");