File Coverage

blib/lib/TestRail/API.pm

Criterion	Covered	Total	%
statement	661	713	92.7
branch	216	286	75.5
condition	111	157	70.7
subroutine	110	112	98.2
pod	91	91	100.0
total	1189	1359	87.4

# ABSTRACT: Provides an interface to TestRail's REST api via HTTP
# PODNAME: TestRail::API

package TestRail::API;
$TestRail::API::VERSION = '0.050';

use 5.010;

use strict;
use warnings;

use Carp qw{cluck confess};
use Scalar::Util qw{reftype looks_like_number};
use Clone 'clone';
use Try::Tiny;

use Types::Standard
  qw( slurpy ClassName Object Str Int Bool HashRef ArrayRef Maybe Optional);
use Type::Params qw( compile );

use JSON::MaybeXS 1.001000 ();
use HTTP::Request;
use LWP::UserAgent;
use HTTP::CookieJar::LWP;
use Data::Validate::URI qw{is_uri};
use List::Util 1.33;
use Encode ();

sub new {
    state $check = compile( ClassName,
        Str,
        Str,
        Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [Bool] ],
        Optional [ Maybe [Bool] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [HashRef] ]
    );
    my (
        $class,            $apiurl,    $user,
        $pass,             $encoding,  $debug,
        $do_post_redirect, $max_tries, $userfetch_opts
    ) = $check->(@_);

    die("Invalid URI passed to constructor") if !is_uri($apiurl);
    $debug //= 0;

    my $self = {
        user            => $user,
        pass            => $pass,
        apiurl          => $apiurl,
        debug           => $debug,
        encoding        => $encoding || 'UTF-8',
        testtree        => [],
        flattree        => [],
        user_cache      => [],
        configurations  => {},
        tr_fields       => undef,
        tr_project_id   => $userfetch_opts->{'project_id'},
        default_request => undef,
        global_limit    => 250,                   #Discovered by experimentation
        browser         => LWP::UserAgent->new(
            keep_alive => 10,
            cookie_jar => HTTP::CookieJar::LWP->new(),
        ),
        do_post_redirect => $do_post_redirect,
        max_tries        => $max_tries // 1,
        retry_delay      => 5,
    };

    #Allow POST redirects
    if ( $self->{do_post_redirect} ) {
        push @{ $self->{'browser'}->requests_redirectable }, 'POST';
    }

    #Check chara encoding
    $self->{'encoding-nonaliased'} =
      Encode::resolve_alias( $self->{'encoding'} );
    die(    "Invalid encoding alias '"
          . $self->{'encoding'}
          . "' passed, see Encoding::Supported for a list of allowed encodings"
    ) unless $self->{'encoding-nonaliased'};

    die(    "Invalid encoding '"
          . $self->{'encoding-nonaliased'}
          . "' passed, see Encoding::Supported for a list of allowed encodings"
      )
      unless grep { $_ eq $self->{'encoding-nonaliased'} }
      ( Encode->encodings(":all") );

    #Create default request to pass on to LWP::UserAgent
    $self->{'default_request'} = HTTP::Request->new();
    $self->{'default_request'}->authorization_basic( $user, $pass );

    bless( $self, $class );
    return $self if $self->debug;    #For easy class testing without mocks

    # Manually do the get_users call to check HTTP status...
    # Allow users to skip the check if you have a zillion users etc,
    # as apparently that is fairly taxing on TR itself.
    if ( !$userfetch_opts->{skip_usercache} ) {
        my $res = $self->getUsers( $userfetch_opts->{project_id} );
        confess "Error: network unreachable" if !defined($res);
        if ( ( reftype($res) || 'undef' ) ne 'ARRAY' ) {
            confess "Unexpected return from _doRequest: $res"
              if !looks_like_number($res);
            confess
              "Could not communicate with TestRail Server! Check that your URI is correct, and your TestRail installation is functioning correctly."
              if $res == -500;
            confess
              "Could not list testRail users! Check that your TestRail installation has it's API enabled, and your credentials are correct"
              if $res == -403;
            confess "Bad user credentials!" if $res == -401;
            confess
              "HTTP error $res encountered while communicating with TestRail server.  Resolve issue and try again."
              if $res < 0;
            confess "Unknown error occurred: $res";
        }
        confess
          "No users detected on TestRail Install!  Check that your API is functioning correctly."
          if !scalar(@$res);
    }

    return $self;
}

sub apiurl {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return $self->{'apiurl'};
}

sub debug {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return $self->{'debug'};
}

#Convenient JSON-HTTP fetcher
sub _doRequest {
    state $check = compile( Object, Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [HashRef] ]
    );
    my ( $self, $path, $method, $data ) = $check->(@_);

    $self->{num_tries}++;

    my $req = clone $self->{'default_request'};
    $method //= 'GET';

    $req->method($method);
    $req->url( $self->apiurl . '/' . $path );

    warn "$method " . $self->apiurl . "/$path" if $self->debug;

    my $coder = JSON::MaybeXS->new;

    #Data sent is JSON, and encoded per user preference
    my $content =
      $data
      ? Encode::encode( $self->{'encoding-nonaliased'}, $coder->encode($data) )
      : '';

    $req->content($content);
    $req->header(
        "Content-Type" => "application/json; charset=" . $self->{'encoding'} );

    my $response = eval { $self->{'browser'}->request($req) };

    #Uncomment to generate mocks
    #use Data::Dumper;
    #open(my $fh, '>>', 'mock.out');
    #print $fh "{\n\n";
    #print $fh Dumper($path,'200','OK',$response->headers,$response->content);
    #print $fh '$mockObject->map_response(qr/\Q$VAR1\E/,HTTP::Response->new($VAR2, $VAR3, $VAR4, $VAR5));';
    #print $fh "\n\n}\n\n";
    #close $fh;

    if ($@) {

        #LWP threw an ex, probably a timeout
        if ( $self->{num_tries} >= $self->{max_tries} ) {
            $self->{num_tries} = 0;
            confess "Failed to satisfy request after $self->{num_tries} tries!";
        }
        cluck
          "WARNING: TestRail API request failed due to timeout, or other LWP fatal condition, re-trying request...\n";
        sleep $self->{retry_delay} if $self->{retry_delay};
        goto &_doRequest;
    }

    return $response if !defined($response);    #worst case

    if ( $response->code == 403 ) {
        confess "ERROR 403: Access Denied: " . $response->content;
    }
    if ( $response->code == 401 ) {
        confess "ERROR 401: Authentication failed: " . $response->content;
    }

    if ( $response->code != 200 ) {

        #LWP threw an ex, probably a timeout
        if ( $self->{num_tries} >= $self->{max_tries} ) {
            $self->{num_tries} = 0;
            cluck "ERROR: Arguments Bad? (got code "
              . $response->code . "): "
              . $response->content;
            return -int( $response->code );
        }
        cluck "WARNING: TestRail API request failed (got code "
          . $response->code
          . "), re-trying request...\n";
        sleep $self->{retry_delay} if $self->{retry_delay};
        goto &_doRequest;

    }
    $self->{num_tries} = 0;

    try {
        return $coder->decode( $response->content );
    }
    catch {
        if ( $response->code == 200 && !$response->content ) {
            return 1;    #This function probably just returns no data
        }
        else {
            cluck "ERROR: Malformed JSON returned by API.";
            cluck $@;
            if ( !$self->debug )
            { #Otherwise we've already printed this, but we need to know if we encounter this
                cluck "RAW CONTENT:";
                cluck $response->content;
            }
            return 0;
        }
    }
}

sub getUsers {
    state $check = compile( Object, Optional [ Maybe [Str] ] );
    my ( $self, $project_id ) = $check->(@_);

    # Return shallow clone of user_cache if set.
    return [ @{ $self->{'user_cache'} } ]
      if ref $self->{'user_cache'} eq 'ARRAY'
      && scalar( @{ $self->{'user_cache'} } );
    my $maybe_project = $project_id ? "/$project_id" : '';
    my $res = $self->_doRequest("index.php?/api/v2/get_users$maybe_project");
    return -500 if !$res || ( reftype($res) || 'undef' ) ne 'ARRAY';
    $self->{'user_cache'} = $res;
    return clone($res);
}

sub getUserByID {
    state $check = compile( Object, Int );
    my ( $self, $user ) = $check->(@_);

    my $users = $self->getUsers();
    return $users if ref $users ne 'ARRAY';
    foreach my $usr (@$users) {
        return $usr if $usr->{'id'} == $user;
    }
    return 0;
}

sub getUserByName {
    state $check = compile( Object, Str );
    my ( $self, $user ) = $check->(@_);

    my $users = $self->getUsers();
    return $users if ref $users ne 'ARRAY';
    foreach my $usr (@$users) {
        return $usr if $usr->{'name'} eq $user;
    }
    return 0;
}

sub getUserByEmail {
    state $check = compile( Object, Str );
    my ( $self, $email ) = $check->(@_);

    my $users = $self->getUsers();
    return $users if ref $users ne 'ARRAY';
    foreach my $usr (@$users) {
        return $usr if $usr->{'email'} eq $email;
    }
    return 0;
}

sub userNamesToIds {
    state $check = compile( Object, slurpy ArrayRef [Str] );
    my ( $self, $names ) = $check->(@_);

    confess("At least one user name must be provided") if !scalar(@$names);
    my @ret = grep { defined $_ } map {
        my $user = $_;
        my @list = grep { $user->{'name'} eq $_ } @$names;
        scalar(@list) ? $user->{'id'} : undef
    } @{ $self->getUsers() };
    confess("One or more user names provided does not exist in TestRail.")
      unless scalar(@$names) == scalar(@ret);
    return @ret;
}

sub createProject {
    state $check = compile( Object, Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [Bool] ]
    );
    my ( $self, $name, $desc, $announce ) = $check->(@_);

    $desc     //= 'res ipsa loquiter';
    $announce //= 0;

    my $input = {
        name              => $name,
        announcement      => $desc,
        show_announcement => $announce
    };

    return $self->_doRequest( 'index.php?/api/v2/add_project', 'POST', $input );
}

sub deleteProject {
    state $check = compile( Object, Int );
    my ( $self, $proj ) = $check->(@_);

    return $self->_doRequest( 'index.php?/api/v2/delete_project/' . $proj,
        'POST' );
}

sub getProjects {
    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';
    $self->{'testtree'} = $result;

    #Note that it's a project for future reference by recursive tree search
    return -500 if !$result || ( reftype($result) || 'undef' ) ne 'ARRAY';
    foreach my $pj ( @{$result} ) {
        $pj->{'type'} = 'project';
    }

    return $result;
}

sub getProjectByName {
    state $check = compile( Object, Str );
    my ( $self, $project ) = $check->(@_);

    #See if we already have the project list...
    my $projects = $self->{'testtree'};
    return -500 if !$projects || ( reftype($projects) || 'undef' ) ne 'ARRAY';
    $projects = $self->getProjects() unless scalar(@$projects);

    #Search project list for project
    return -500 if !$projects || ( reftype($projects) || 'undef' ) ne 'ARRAY';
    for my $candidate (@$projects) {
        return $candidate if ( $candidate->{'name'} eq $project );
    }

    return 0;
}

sub getProjectByID {
    state $check = compile( Object, Int );
    my ( $self, $project ) = $check->(@_);

    #See if we already have the project list...
    my $projects = $self->{'testtree'};
    $projects = $self->getProjects() unless scalar(@$projects);

    #Search project list for project
    return -500 if !$projects || ( reftype($projects) || 'undef' ) ne 'ARRAY';
    for my $candidate (@$projects) {
        return $candidate if ( $candidate->{'id'} eq $project );
    }

    return 0;
}

sub createTestSuite {
    state $check = compile( Object, Int, Str, Optional [ Maybe [Str] ] );
    my ( $self, $project_id, $name, $details ) = $check->(@_);

    $details //= 'res ipsa loquiter';
    my $input = {
        name        => $name,
        description => $details
    };

    return $self->_doRequest( 'index.php?/api/v2/add_suite/' . $project_id,
        'POST', $input );
}

sub deleteTestSuite {
    state $check = compile( Object, Int );
    my ( $self, $suite_id ) = $check->(@_);

    return $self->_doRequest( 'index.php?/api/v2/delete_suite/' . $suite_id,
        'POST' );
}

sub getTestSuites {
    state $check = compile( Object, Int );
    my ( $self, $proj ) = $check->(@_);

    return $self->_doRequest( 'index.php?/api/v2/get_suites/' . $proj );
}

sub getTestSuiteByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $testsuite_name ) = $check->(@_);

    #TODO cache
    my $suites = $self->getTestSuites($project_id);
    return -500
      if !$suites
      || ( reftype($suites) || 'undef' ) ne
      'ARRAY';    #No suites for project, or no project
    foreach my $suite (@$suites) {
        return $suite if $suite->{'name'} eq $testsuite_name;
    }
    return 0;     #Couldn't find it
}

sub getTestSuiteByID {
    state $check = compile( Object, Int );
    my ( $self, $testsuite_id ) = $check->(@_);

    return $self->_doRequest( 'index.php?/api/v2/get_suite/' . $testsuite_id );
}

sub createSection {
    state $check = compile( Object, Int, Int, Str, Optional [ Maybe [Int] ] );
    my ( $self, $project_id, $suite_id, $name, $parent_id ) = $check->(@_);

    my $input = {
        name     => $name,
        suite_id => $suite_id
    };
    $input->{'parent_id'} = $parent_id if $parent_id;

    return $self->_doRequest( 'index.php?/api/v2/add_section/' . $project_id,
        'POST', $input );
}

sub deleteSection {
    state $check = compile( Object, Int );
    my ( $self, $section_id ) = $check->(@_);

    return $self->_doRequest( 'index.php?/api/v2/delete_section/' . $section_id,
        'POST' );
}

sub getSections {
    state $check = compile( Object, Int, Int );
    my ( $self, $project_id, $suite_id ) = $check->(@_);

    #Cache sections to reduce requests in tight loops
    return $self->{'sections'}->{$suite_id} if $self->{'sections'}->{$suite_id};
    $self->{'sections'}->{$suite_id} = $self->_doRequest(
        "index.php?/api/v2/get_sections/$project_id&suite_id=$suite_id");

    return $self->{'sections'}->{$suite_id};
}

sub getSectionByID {
    state $check = compile( Object, Int );
    my ( $self, $section_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_section/$section_id");
}

sub getSectionByName {
    state $check = compile( Object, Int, Int, Str );
    my ( $self, $project_id, $suite_id, $section_name ) = $check->(@_);

    my $sections = $self->getSections( $project_id, $suite_id );
    return -500 if !$sections || ( reftype($sections) || 'undef' ) ne 'ARRAY';
    foreach my $sec (@$sections) {
        return $sec if $sec->{'name'} eq $section_name;
    }
    return 0;
}

sub getChildSections {
    state $check = compile( Object, Int, HashRef );
    my ( $self, $project_id, $section ) = $check->(@_);

    my $sections_orig = $self->getSections( $project_id, $section->{suite_id} );
    return []
      if !$sections_orig || ( reftype($sections_orig) || 'undef' ) ne 'ARRAY';
    my @sections =
      grep { $_->{'parent_id'} ? $_->{'parent_id'} == $section->{'id'} : 0 }
      @$sections_orig;
    foreach my $sec (@sections) {
        push( @sections,
            grep { $_->{'parent_id'} ? $_->{'parent_id'} == $sec->{'id'} : 0 }
              @$sections_orig );
    }
    return \@sections;
}

sub sectionNamesToIds {
    my ( $self, $project_id, $suite_id, @names ) = @_;
    my $sections = $self->getSections( $project_id, $suite_id )
      or confess("Could not find sections in provided project/suite.");
    return _X_in_my_Y( $self, $sections, 'id', @names );
}

sub getCaseTypes {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return clone( $self->{'type_cache'} ) if defined( $self->{'type_cache'} );

    my $types = $self->_doRequest("index.php?/api/v2/get_case_types");
    return -500 if !$types || ( reftype($types) || 'undef' ) ne 'ARRAY';
    $self->{'type_cache'} = $types;

    return clone $types;
}

sub getCaseTypeByName {
    state $check = compile( Object, Str );
    my ( $self, $name ) = $check->(@_);

    my $types = $self->getCaseTypes();
    return -500 if !$types || ( reftype($types) || 'undef' ) ne 'ARRAY';
    foreach my $type (@$types) {
        return $type if $type->{'name'} eq $name;
    }
    confess("No such case type '$name'!");
}

sub typeNamesToIds {
    my ( $self, @names ) = @_;
    return _X_in_my_Y( $self, $self->getCaseTypes(), 'id', @names );
}

sub createCase {
    state $check = compile( Object, Int, Str,
        Optional [ Maybe [Int] ],
        Optional [ Maybe [HashRef] ],
        Optional [ Maybe [HashRef] ]
    );
    my ( $self, $section_id, $title, $type_id, $opts, $extras ) = $check->(@_);

    my $stuff = {
        title   => $title,
        type_id => $type_id
    };

    #Handle sort of optional but baked in options
    if ( defined($extras) && reftype($extras) eq 'HASH' ) {
        $stuff->{'priority_id'} = $extras->{'priority_id'}
          if defined( $extras->{'priority_id'} );
        $stuff->{'estimate'} = $extras->{'estimate'}
          if defined( $extras->{'estimate'} );
        $stuff->{'milestone_id'} = $extras->{'milestone_id'}
          if defined( $extras->{'milestone_id'} );
        $stuff->{'refs'} = join( ',', @{ $extras->{'refs'} } )
          if defined( $extras->{'refs'} );
    }

    #Handle custom fields
    if ( defined($opts) && reftype($opts) eq 'HASH' ) {
        foreach my $key ( keys(%$opts) ) {
            $stuff->{"custom_$key"} = $opts->{$key};
        }
    }

    return $self->_doRequest( "index.php?/api/v2/add_case/$section_id",
        'POST', $stuff );
}

sub updateCase {
    state $check = compile( Object, Int, Optional [ Maybe [HashRef] ] );
    my ( $self, $case_id, $options ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/update_case/$case_id",
        'POST', $options );
}

sub deleteCase {
    state $check = compile( Object, Int );
    my ( $self, $case_id ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/delete_case/$case_id",
        'POST' );
}

sub getCases {
    state $check = compile( Object, Int, Int, Optional [ Maybe [HashRef] ] );
    my ( $self, $project_id, $suite_id, $filters ) = $check->(@_);

    my $url = "index.php?/api/v2/get_cases/$project_id&suite_id=$suite_id";
    $url .= _convert_filters_to_string($filters);

    return $self->_doRequest($url);
}

sub getCaseByName {
    state $check =
      compile( Object, Int, Int, Str, Optional [ Maybe [HashRef] ] );
    my ( $self, $project_id, $suite_id, $name, $filters ) = $check->(@_);

    my $cases = $self->getCases( $project_id, $suite_id, $filters );
    return -500 if !$cases || ( reftype($cases) || 'undef' ) ne 'ARRAY';
    foreach my $case (@$cases) {
        return $case if $case->{'title'} eq $name;
    }
    return 0;
}

sub getCaseByID {
    state $check = compile( Object, Int );
    my ( $self, $case_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_case/$case_id");
}

sub getCaseFields {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return $self->{case_fields} if $self->{case_fields};

    $self->{case_fields} =
      $self->_doRequest("index.php?/api/v2/get_case_fields");
    return $self->{case_fields};
}

sub addCaseField {
    state $check = compile( Object, slurpy HashRef );
    my ( $self, $options ) = $check->(@_);
    $self->{case_fields} = undef;
    return $self->_doRequest( "index.php?/api/v2/add_case_field", 'POST',
        $options );
}

sub getPriorities {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return clone( $self->{'priority_cache'} )
      if defined( $self->{'priority_cache'} );

    my $priorities = $self->_doRequest("index.php?/api/v2/get_priorities");
    return -500
      if !$priorities || ( reftype($priorities) || 'undef' ) ne 'ARRAY';
    $self->{'priority_cache'} = $priorities;

    return clone $priorities;
}

sub getPriorityByName {
    state $check = compile( Object, Str );
    my ( $self, $name ) = $check->(@_);

    my $priorities = $self->getPriorities();
    return -500
      if !$priorities || ( reftype($priorities) || 'undef' ) ne 'ARRAY';
    foreach my $priority (@$priorities) {
        return $priority if $priority->{'name'} eq $name;
    }
    confess("No such priority '$name'!");
}

sub priorityNamesToIds {
    my ( $self, @names ) = @_;
    return _X_in_my_Y( $self, $self->getPriorities(), 'id', @names );
}

#If you pass an array of case ids, it implies include_all is false
sub createRun {
    state $check = compile( Object, Int, Int, Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [ ArrayRef [Int] ] ]
    );
    my ( $self, $project_id, $suite_id, $name, $desc, $milestone_id,
        $assignedto_id, $case_ids )
      = $check->(@_);

    my $stuff = {
        suite_id      => $suite_id,
        name          => $name,
        description   => $desc,
        milestone_id  => $milestone_id,
        assignedto_id => $assignedto_id,
        include_all   => defined($case_ids) ? 0 : 1,
        case_ids      => $case_ids
    };

    return $self->_doRequest( "index.php?/api/v2/add_run/$project_id",
        'POST', $stuff );
}

sub deleteRun {
    state $check = compile( Object, Int );
    my ( $self, $run_id ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/delete_run/$run_id", 'POST' );
}

sub getRuns {
    state $check = compile( Object, Int, Optional [ Maybe [HashRef] ] );
    my ( $self, $project_id, $filters ) = $check->(@_);

    my $initial_runs =
      $self->getRunsPaginated( $project_id, $self->{'global_limit'},
        0, $filters );
    return $initial_runs
      unless ( reftype($initial_runs) || 'undef' ) eq 'ARRAY';
    my $runs = [];
    push( @$runs, @$initial_runs );
    my $offset = 1;
    while ( scalar(@$initial_runs) == $self->{'global_limit'} ) {
        $initial_runs = $self->getRunsPaginated(
            $project_id,
            $self->{'global_limit'},
            ( $self->{'global_limit'} * $offset ), $filters
        );
        push( @$runs, @$initial_runs );
        $offset++;
    }
    return $runs;
}

sub getRunsPaginated {
    state $check = compile( Object,
        Int,
        Optional [ Maybe [Int] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [HashRef] ]
    );
    my ( $self, $project_id, $limit, $offset, $filters ) = $check->(@_);

    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
    $apiurl .= _convert_filters_to_string($filters);
    return $self->_doRequest($apiurl);
}

sub getRunByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $name ) = $check->(@_);

    my $runs = $self->getRuns($project_id);
    return -500 if !$runs || ( reftype($runs) || 'undef' ) ne 'ARRAY';
    foreach my $run (@$runs) {
        return $run if $run->{'name'} eq $name;
    }
    return 0;
}

sub getRunByID {
    state $check = compile( Object, Int );
    my ( $self, $run_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_run/$run_id");
}

sub closeRun {
    state $check = compile( Object, Int );
    my ( $self, $run_id ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/close_run/$run_id", 'POST' );
}

sub getRunSummary {
    state $check = compile( Object, slurpy ArrayRef [HashRef] );
    my ( $self, $runs ) = $check->(@_);
    confess("At least one run must be passed!") unless scalar(@$runs);

    #Translate custom statuses
    my $statuses = $self->getPossibleTestStatuses();
    my %shash;

    #XXX so, they do these tricks with the status names, see...so map the counts to their relevant status ids.
    @shash{
        map {
            ( $_->{'id'} < 6 )
              ? $_->{'name'} . "_count"
              : "custom_status"
              . ( $_->{'id'} - 5 )
              . "_count"
        } @$statuses
    } = map { $_->{'id'} } @$statuses;

    my @sname;

    #Create listing of keys/values
    @$runs = map {
        my $run = $_;
        @{ $run->{statuses} }{ grep { $_ =~ m/_count$/ } keys(%$run) } =
          grep { $_ =~ m/_count$/ } keys(%$run);
        foreach my $status ( keys( %{ $run->{'statuses'} } ) ) {
            next if !exists( $shash{$status} );
            @sname = grep {
                exists( $shash{$status} )
                  && $_->{'id'} == $shash{$status}
            } @$statuses;
            $run->{'statuses_clean'}->{ $sname[0]->{'label'} } =
              $run->{$status};
        }
        $run;
    } @$runs;

    return map {
        {
            'id'         => $_->{'id'},
            'name'       => $_->{'name'},
            'run_status' => $_->{'statuses_clean'},
            'config_ids' => $_->{'config_ids'}
        }
    } @$runs;

}

sub getRunResults {
    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, $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 ), $filters
        );
        push( @$results, @$initial_results );
        $offset++;
    }
    return $results;
}

sub getRunResultsPaginated {
    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);
}

sub getChildRuns {
    state $check = compile( Object, HashRef );
    my ( $self, $plan ) = $check->(@_);

    return 0
      unless defined( $plan->{'entries'} )
      && ( reftype( $plan->{'entries'} ) || 'undef' ) eq 'ARRAY';
    my $entries = $plan->{'entries'};
    my $plans   = [];
    foreach my $entry (@$entries) {
        push( @$plans, @{ $entry->{'runs'} } )
          if defined( $entry->{'runs'} )
          && ( ( reftype( $entry->{'runs'} ) || 'undef' ) eq 'ARRAY' );
    }
    return $plans;
}

sub getChildRunByName {
    state $check = compile( Object, HashRef, Str,
        Optional [ Maybe [ ArrayRef [Str] ] ],
        Optional [ Maybe [Int] ]
    );
    my ( $self, $plan, $name, $configurations, $testsuite_id ) = $check->(@_);

    my $runs = $self->getChildRuns($plan);
    @$runs = grep { $_->{suite_id} == $testsuite_id } @$runs if $testsuite_id;
    return 0 if !$runs;

    my @pconfigs = ();

    #Figure out desired config IDs
    if ( defined $configurations ) {
        my $avail_configs = $self->getConfigurations( $plan->{'project_id'} );
        my ($cname);
        @pconfigs = map { $_->{'id'} } grep {
            $cname = $_->{'name'};
            grep { $_ eq $cname } @$configurations
        } @$avail_configs;    #Get a list of IDs from the names passed
    }
    confess("One or more configurations passed does not exist in your project!")
      if defined($configurations)
      && ( scalar(@pconfigs) != scalar(@$configurations) );

    my $found;
    foreach my $run (@$runs) {
        next if $run->{name} ne $name;
        next if scalar(@pconfigs) != scalar( @{ $run->{'config_ids'} } );

        #Compare run config IDs against desired, invalidate run if all conditions not satisfied
        $found = 0;
        foreach my $cid ( @{ $run->{'config_ids'} } ) {
            $found++ if grep { $_ == $cid } @pconfigs;
        }

        return $run if $found == scalar( @{ $run->{'config_ids'} } );
    }
    return 0;
}

sub createPlan {
    state $check = compile( Object, Int, Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [ ArrayRef [HashRef] ] ]
    );
    my ( $self, $project_id, $name, $desc, $milestone_id, $entries ) =
      $check->(@_);

    my $stuff = {
        name         => $name,
        description  => $desc,
        milestone_id => $milestone_id,
        entries      => $entries
    };

    return $self->_doRequest( "index.php?/api/v2/add_plan/$project_id",
        'POST', $stuff );
}

sub deletePlan {
    state $check = compile( Object, Int );
    my ( $self, $plan_id ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/delete_plan/$plan_id",
        'POST' );
}

sub getPlans {
    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, $filters );
    return $initial_plans
      unless ( reftype($initial_plans) || 'undef' ) eq 'ARRAY';
    my $plans = [];
    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 ), $filters
        );
        push( @$plans, @$initial_plans );
        $offset++;
    }
    return $plans;
}

sub getPlansPaginated {
    state $check = compile( Object,
        Int,
        Optional [ Maybe [Int] ],
        Optional [ Maybe [Int] ],
        Optional [ Maybe [HashRef] ]
    );
    my ( $self, $project_id, $limit, $offset, $filters ) = $check->(@_);

    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
    $apiurl .= _convert_filters_to_string($filters);
    return $self->_doRequest($apiurl);
}

sub getPlanByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $name ) = $check->(@_);

    my $plans = $self->getPlans($project_id);
    return -500 if !$plans || ( reftype($plans) || 'undef' ) ne 'ARRAY';
    foreach my $plan (@$plans) {
        if ( $plan->{'name'} eq $name ) {
            return $self->getPlanByID( $plan->{'id'} );
        }
    }
    return 0;
}

sub getPlanByID {
    state $check = compile( Object, Int );
    my ( $self, $plan_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_plan/$plan_id");
}

sub getPlanSummary {
    state $check = compile( Object, Int );
    my ( $self, $plan_id ) = $check->(@_);

    my $runs = $self->getPlanByID($plan_id);
    $runs  = $self->getChildRuns($runs);
    @$runs = $self->getRunSummary( @{$runs} );
    my $total_sum = 0;
    my $ret       = { plan => $plan_id };

    #Compile totals
    foreach my $summary (@$runs) {
        my @elems = keys( %{ $summary->{'run_status'} } );
        foreach my $key (@elems) {
            $ret->{'totals'}->{$key} = 0 if !defined $ret->{'totals'}->{$key};
            $ret->{'totals'}->{$key} += $summary->{'run_status'}->{$key};
            $total_sum += $summary->{'run_status'}->{$key};
        }
    }

    #Compile percentages
    foreach my $key ( keys( %{ $ret->{'totals'} } ) ) {
        next if grep { $_ eq $key } qw{plan configs percentages};
        $ret->{"percentages"}->{$key} =
          sprintf( "%.2f%%", ( $ret->{'totals'}->{$key} / $total_sum ) * 100 );
    }

    return $ret;
}

#If you pass an array of case ids, it implies include_all is false
sub createRunInPlan {
    state $check = compile( Object, Int, Int, Str,
        Optional [ Maybe [Int] ],
        Optional [ Maybe [ ArrayRef [Int] ] ],
        Optional [ Maybe [ ArrayRef [Int] ] ]
    );
    my ( $self, $plan_id, $suite_id, $name, $assignedto_id, $config_ids,
        $case_ids )
      = $check->(@_);

    my $runs = [
        {
            config_ids  => $config_ids,
            include_all => defined($case_ids) ? 0 : 1,
            case_ids    => $case_ids
        }
    ];

    my $stuff = {
        suite_id      => $suite_id,
        name          => $name,
        assignedto_id => $assignedto_id,
        include_all   => defined($case_ids) ? 0 : 1,
        case_ids      => $case_ids,
        config_ids    => $config_ids,
        runs          => $runs
    };
    return $self->_doRequest( "index.php?/api/v2/add_plan_entry/$plan_id",
        'POST', $stuff );
}

sub closePlan {
    state $check = compile( Object, Int );
    my ( $self, $plan_id ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/close_plan/$plan_id", 'POST' );
}

sub createMilestone {
    state $check = compile( Object, Int, Str,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [Int] ]
    );
    my ( $self, $project_id, $name, $desc, $due_on ) = $check->(@_);

    my $stuff = {
        name        => $name,
        description => $desc,
        due_on      => $due_on    # unix timestamp
    };

    return $self->_doRequest( "index.php?/api/v2/add_milestone/$project_id",
        'POST', $stuff );
}

sub deleteMilestone {
    state $check = compile( Object, Int );
    my ( $self, $milestone_id ) = $check->(@_);

    return $self->_doRequest(
        "index.php?/api/v2/delete_milestone/$milestone_id", 'POST' );
}

sub getMilestones {
    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"
          . _convert_filters_to_string($filters) );
}

sub getMilestoneByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $name ) = $check->(@_);

    my $milestones = $self->getMilestones($project_id);
    return -500
      if !$milestones || ( reftype($milestones) || 'undef' ) ne 'ARRAY';
    foreach my $milestone (@$milestones) {
        return $milestone if $milestone->{'name'} eq $name;
    }
    return 0;
}

sub getMilestoneByID {
    state $check = compile( Object, Int );
    my ( $self, $milestone_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_milestone/$milestone_id");
}

sub getTests {
    state $check = compile( Object, Int,
        Optional [ Maybe [ ArrayRef [Int] ] ],
        Optional [ Maybe [ ArrayRef [Int] ] ]
    );
    my ( $self, $run_id, $status_ids, $assignedto_ids ) = $check->(@_);

    my $query_string = '';
    $query_string = '&status_id=' . join( ',', @$status_ids )
      if defined($status_ids) && scalar(@$status_ids);
    my $results =
      $self->_doRequest("index.php?/api/v2/get_tests/$run_id$query_string");
    @$results = grep {
        my $aid = $_->{'assignedto_id'};
        grep { defined($aid) && $aid == $_ } @$assignedto_ids
    } @$results if defined($assignedto_ids) && scalar(@$assignedto_ids);

    #Cache stuff for getTestByName
    $self->{tests_cache} //= {};
    $self->{tests_cache}->{$run_id} = $results;

    return clone($results);
}

sub getTestByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $run_id, $name ) = $check->(@_);

    $self->{tests_cache} //= {};
    my $tests = $self->{tests_cache}->{$run_id};

    $tests = $self->getTests($run_id) if !$tests;
    return -500 if !$tests || ( reftype($tests) || 'undef' ) ne 'ARRAY';
    foreach my $test (@$tests) {
        return $test if $test->{'title'} eq $name;
    }
    return 0;
}

sub getTestByID {
    state $check = compile( Object, Int );
    my ( $self, $test_id ) = $check->(@_);

    return $self->_doRequest("index.php?/api/v2/get_test/$test_id");
}

sub getTestResultFields {
    state $check = compile(Object);
    my ($self) = $check->(@_);

    return $self->{'tr_fields'} if defined( $self->{'tr_fields'} );    #cache
    $self->{'tr_fields'} =
      $self->_doRequest('index.php?/api/v2/get_result_fields');
    return $self->{'tr_fields'};
}

sub getTestResultFieldByName {
    state $check = compile( Object, Str, Optional [ Maybe [Int] ] );
    my ( $self, $system_name, $project_id ) = $check->(@_);

    my @candidates =
      grep { $_->{'name'} eq $system_name } @{ $self->getTestResultFields() };
    return 0  if !scalar(@candidates);              #No such name
    return -1 if ref( $candidates[0] ) ne 'HASH';
    return -2
      if ref( $candidates[0]->{'configs'} ) ne 'ARRAY'
      && !scalar( @{ $candidates[0]->{'configs'} } );    #bogofilter

    #Give it to the user
    my $ret = $candidates[0];                            #copy/save for later
    return $ret if !defined($project_id);

    #Filter by project ID
    foreach my $config ( @{ $candidates[0]->{'configs'} } ) {
        return $ret
          if ( grep { $_ == $project_id }
            @{ $config->{'context'}->{'project_ids'} } );
    }

    return -3;
}

sub getPossibleTestStatuses {
    state $check = compile(Object);
    my ($self) = $check->(@_);
    return $self->{'status_cache'} if $self->{'status_cache'};

    $self->{'status_cache'} =
      $self->_doRequest('index.php?/api/v2/get_statuses');
    return clone $self->{'status_cache'};
}

sub statusNamesToIds {
    my ( $self, @names ) = @_;
    return _X_in_my_Y( $self, $self->getPossibleTestStatuses(), 'id', @names );
}

sub statusNamesToLabels {
    my ( $self, @names ) = @_;
    return _X_in_my_Y( $self, $self->getPossibleTestStatuses(), 'label',
        @names );
}

# Reduce code duplication with internal methods?
# It's more likely than you think
# Free PC check @ cpan.org
sub _X_in_my_Y {
    state $check = compile( Object, ArrayRef, Str, slurpy ArrayRef [Str] );
    my ( $self, $search_arr, $key, $names ) = $check->(@_);

    my @ret;
    foreach my $name (@$names) {
        foreach my $member (@$search_arr) {
            if ( $member->{'name'} eq $name ) {
                push @ret, $member->{$key};
                last;
            }
        }
    }
    confess("One or more names provided does not exist in TestRail.")
      unless scalar(@$names) == scalar(@ret);
    return @ret;
}

sub createTestResults {
    state $check = compile( Object, Int, Int,
        Optional [ Maybe [Str] ],
        Optional [ Maybe [HashRef] ],
        Optional [ Maybe [HashRef] ]
    );
    my ( $self, $test_id, $status_id, $comment, $opts, $custom_fields ) =
      $check->(@_);

    my $stuff = {
        status_id => $status_id,
        comment   => $comment
    };

    #Handle options
    if ( defined($opts) && reftype($opts) eq 'HASH' ) {
        $stuff->{'version'} =
          defined( $opts->{'version'} ) ? $opts->{'version'} : undef;
        $stuff->{'elapsed'} =
          defined( $opts->{'elapsed'} ) ? $opts->{'elapsed'} : undef;
        $stuff->{'defects'} =
          defined( $opts->{'defects'} )
          ? join( ',', @{ $opts->{'defects'} } )
          : undef;
        $stuff->{'assignedto_id'} =
          defined( $opts->{'assignedto_id'} )
          ? $opts->{'assignedto_id'}
          : undef;
    }

    #Handle custom fields
    if ( defined($custom_fields) && reftype($custom_fields) eq 'HASH' ) {
        foreach my $field ( keys(%$custom_fields) ) {
            $stuff->{"custom_$field"} = $custom_fields->{$field};
        }
    }

    return $self->_doRequest( "index.php?/api/v2/add_result/$test_id",
        'POST', $stuff );
}

sub bulkAddResults {
    state $check = compile( Object, Int, ArrayRef [HashRef] );
    my ( $self, $run_id, $results ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/add_results/$run_id",
        'POST', { 'results' => $results } );
}

sub bulkAddResultsByCase {
    state $check = compile( Object, Int, ArrayRef [HashRef] );
    my ( $self, $run_id, $results ) = $check->(@_);

    return $self->_doRequest( "index.php?/api/v2/add_results_for_cases/$run_id",
        'POST', { 'results' => $results } );
}

sub getTestResults {
    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);
}

sub getResultsForCase {
    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);
}

sub getConfigurationGroups {
    state $check = compile( Object, Int );
    my ( $self, $project_id ) = $check->(@_);

    my $url = "index.php?/api/v2/get_configs/$project_id";
    return $self->_doRequest($url);
}

sub getConfigurationGroupByName {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $name ) = $check->(@_);

    my $cgroups = $self->getConfigurationGroups($project_id);
    return 0 if ref($cgroups) ne 'ARRAY';
    @$cgroups = grep { $_->{'name'} eq $name } @$cgroups;
    return 0 unless scalar(@$cgroups);
    return $cgroups->[0];
}

sub addConfigurationGroup {
    state $check = compile( Object, Int, Str );
    my ( $self, $project_id, $name ) = $check->(@_);

    my $url = "index.php?/api/v2/add_config_group/$project_id";
    return $self->_doRequest( $url, 'POST', { 'name' => $name } );
}

sub editConfigurationGroup {
    state $check = compile( Object, Int, Str );
    my ( $self, $config_group_id, $name ) = $check->(@_);

    my $url = "index.php?/api/v2/update_config_group/$config_group_id";
    return $self->_doRequest( $url, 'POST', { 'name' => $name } );
}

sub deleteConfigurationGroup {
    state $check = compile( Object, Int );
    my ( $self, $config_group_id ) = $check->(@_);

    my $url = "index.php?/api/v2/delete_config_group/$config_group_id";
    return $self->_doRequest( $url, 'POST' );
}

sub getConfigurations {
    state $check = compile( Object, Int );
    my ( $self, $project_id ) = $check->(@_);

    my $cgroups = $self->getConfigurationGroups($project_id);
    my $configs = [];
    return $cgroups unless ( reftype($cgroups) || 'undef' ) eq 'ARRAY';
    foreach my $cfg (@$cgroups) {
        push( @$configs, @{ $cfg->{'configs'} } );
    }
    return $configs;
}

sub addConfiguration {
    state $check = compile( Object, Int, Str );
    my ( $self, $configuration_group_id, $name ) = $check->(@_);

    my $url = "index.php?/api/v2/add_config/$configuration_group_id";
    return $self->_doRequest( $url, 'POST', { 'name' => $name } );
}

sub editConfiguration {
    state $check = compile( Object, Int, Str );
    my ( $self, $config_id, $name ) = $check->(@_);

    my $url = "index.php?/api/v2/update_config/$config_id";
    return $self->_doRequest( $url, 'POST', { 'name' => $name } );
}

sub deleteConfiguration {
    state $check = compile( Object, Int );
    my ( $self, $config_id ) = $check->(@_);

    my $url = "index.php?/api/v2/delete_config/$config_id";
    return $self->_doRequest( $url, 'POST' );
}

sub translateConfigNamesToIds {
    my ( $self, $project_id, @names ) = @_;
    my $configs = $self->getConfigurations($project_id)
      or confess("Could not determine configurations in provided project.");
    return _X_in_my_Y( $self, $configs, 'id', @names );
}

sub getReports {
    state $check = compile( Object, Int );
    my ( $self, $project_id ) = $check->(@_);
    my $url = "index.php?/api/v2/get_reports/$project_id";
    return $self->_doRequest( $url, 'GET' );
}

sub runReport {
    state $check = compile( Object, Int );
    my ( $self, $report_id ) = $check->(@_);
    my $url = "index.php?/api/v2/run_report/$report_id";
    return $self->_doRequest( $url, 'GET' );
}

#Convenience method for building stepResults
sub buildStepResults {
    state $check = compile( Str, Str, Str, Int );
    my ( $content, $expected, $actual, $status_id ) = $check->(@_);

    return {
        content   => $content,
        expected  => $expected,
        actual    => $actual,
        status_id => $status_id
    };
}

# Convenience method for building filter string from filters Hashref
sub _convert_filters_to_string {
    state $check = compile( Maybe [HashRef] );
    my ($filters) = $check->(@_);

    $filters //= {};

    my $filter_string = '';
    foreach my $filter ( keys(%$filters) ) {
        if ( ref $filters->{$filter} eq 'ARRAY' ) {
            $filter_string .=
              "&$filter=" . join( ',', @{ $filters->{$filter} } );
        }
        else {
            $filter_string .= "&$filter=" . $filters->{$filter}
              if defined( $filters->{$filter} );
        }
    }
    return $filter_string;
}

1;

__END__