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

=head1 SYNOPSIS

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

=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 occured (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.

This obviously does not make sense with case_per_ok test upload; support for locking entire sections when in case_per_ok upload mode is not supported at this time.

=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.

-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

--mock : don't do any real HTTP requests.  Used only by tests.

--help : show this output

=back

=cut

use strict;
use warnings;
use utf8;

use TestRail::Utils;

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

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);
}

GetOptions(
    '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'},
    'mock'            => \$opts->{'mock'},
    'e|encoding=s'    => \$opts->{'encoding'},
    'h|help'          => \$opts->{'help'}
);

if ($opts->{help}) { help(); }
$opts->{'hostname'} = hostname;

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

print TestRail::Utils::pickAndLockTest($opts)."\n";
exit 0;

__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.