#!/usr/bin/perl
# ABSTRACT: Lock a test in a TestRail, and return the test name if successful.
# PODNAME: TestRail::Bin::Lock

=head1 SYNOPSIS

  # Lock a group of tests and execute them
  testrail-tests [OPTIONS] | xargs testrail-lock [OPTIONS] | xargs prove -PTestrail=...

  require `which testrail-lock`;
  TestRail::Bin::Lock::run('args' => \@args);

=head1 DESCRIPTION

testrail-lock - pick an untested/retest test in TestRail, lock it, and return the test name if successful.

It is useful to lock the test in situations where you have multiple disconnected test running processes trying to allocate resources toward testing outstanding cases so that effort is not duplicated.
This is accomplished via setting a special locking result on a test rather than simple assignment, as detecting lock conflicts is impossible then due to a lack of assignment history.
Results, however have a history of results set, so we use that fact to detect if a locking collision occurred (race condition) and fail to return a result when another process locked during our attempt to lock.

Will respect test priority when making the choice of what test to lock.

Can also be used as the modulino TestRail::Bin::Lock.
Has a single 'run' function which accepts a hash with the 'args' parameter being the array of arguments.

=head1 PARAMETERS:

=head2 MANDATORY PARAMETERS

=over 4

--apiurl      : full URL to get to TestRail index document

--password    : Your TestRail Password, or a valid API key (TestRail 4.2 and above).

--user        : Your TestRail User Name.

-j --project  : desired project name.

-r --run      : desired run name.

-l --lockname : internal name of lock status.

=back

All mandatory options not passed with the above switches, or in your ~/.testrailrc will be prompted for.

=head2 SEMI-OPTIONAL PARAMETERS

=over 4

-p --plan       : desired plan name.  Required if the run passed is a child of a plan.

-m --match      : attempt to find filenames matching the test names in the provided directory.

--no-match      : attempt to find filenames that do not match test names in the provided directory.

-n --no-recurse : if match (or no-match) passed, do not recurse subdirectories.

-t --case-type  : Only attempt to lock cases of the specified type.  May be passed multiple times.

-e --encoding   : Character encoding of arguments.  Defaults to UTF-8. See L<Encode::Supported> for supported encodings.

=back

=head2 OPTIONAL PARAMETERS

=over 4

-c --config : configuration name to filter plans in run.  Can be passed multiple times.

=back

=head1 CONFIGURATION FILE

In your $HOME, (or the current directory, if your system has no concept of a home directory) put a file called .testrailrc with key=value syntax separated by newlines.
Valid Keys are the same as documented by L<App::Prove::Plugin::TestRail>.
All options specified thereby are overridden by passing the command-line switches above.

=head1 MISCELLANEOUS OPTIONS:

=over 4

--help : show this output

=back

=cut

package TestRail::Bin::Lock;

use strict;
use warnings;
use utf8;

use TestRail::Utils;
use TestRail::Utils::Lock;

use Getopt::Long qw{GetOptionsFromArray};
use File::HomeDir qw{my_home};
use Sys::Hostname qw{hostname};

if (!caller()) {
    my ($out,$code) = run('args' => \@ARGV);
    print $out;
    exit $code;
}

sub run {
    my %params = @_;
    my $opts = {};

    #Parse config file if we are missing api url/key or user
    my $homedir = my_home() || '.';
    if (-e $homedir . '/.testrailrc') {
        $opts = TestRail::Utils::parseConfig($homedir);
    }

    GetOptionsFromArray($params{'args'},
        'apiurl=s'        => \$opts->{'apiurl'},
        'password=s'      => \$opts->{'password'},
        'user=s'          => \$opts->{'user'},
        'l|lockname=s'    => \$opts->{'lockname'},
        'j|project=s'     => \$opts->{'project'},
        'p|plan=s'        => \$opts->{'plan'},
        'r|run=s'         => \$opts->{'run'},
        'c|config=s@'     => \$opts->{'configs'},
        'm|match=s'       => \$opts->{'match'},
        'no-match=s'      => \$opts->{'no-match'},
        'n|no-recurse'    => \$opts->{'no-recurse'},
        't|case-type=s@'  => \$opts->{'case-types'},
        'e|encoding=s'    => \$opts->{'encoding'},
        'h|help'          => \$opts->{'help'},
    );

    if ($opts->{help}) { return ('',TestRail::Utils::help()); }

    $opts->{'browser'} = $params{'browser'};
    $opts->{'hostname'} = hostname;

    TestRail::Utils::interrogateUser($opts,qw{apiurl user password project run lockname});

    my $tr = TestRail::Utils::getHandle($opts);

    my $ret = TestRail::Utils::Lock::pickAndLockTest($opts,$tr);

    return ('Could not lock case.', 255) if !$ret;

    return ($ret->{'path'}."\n",0);
}

1;

__END__

L<TestRail::API>

L<File::HomeDir> for the finding of .testrailrc

=head1 SPECIAL THANKS

Thanks to cPanel Inc, for graciously funding the creation of this distribution.