—#!/usr/bin/perl
# ABSTRACT: Lock a test in a TestRail, and return the test name if successful.
# PODNAME: TestRail::Bin::Lock
package
TestRail::Bin::Lock;
$TestRail::Bin::Lock::VERSION
=
'0.052'
;
use
strict;
use
warnings;
use
utf8;
use
TestRail::Utils;
if
( !
caller
() ) {
my
(
$out
,
$code
) = run(
'args'
=> \
@ARGV
);
$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;
=pod
=encoding UTF-8
=head1 NAME
TestRail::Bin::Lock - Lock a test in a TestRail, and return the test name if successful.
=head1 VERSION
version 0.052
=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
=head1 SPECIAL THANKS
Thanks to cPanel Inc, for graciously funding the creation of this distribution.
=head1 AUTHOR
George S. Baugh <teodesian@cpan.org>
=head1 SOURCE
The development version is on github at L<https://github.com/teodesian/TestRail-Perl>
and may be cloned from L<git://github.com/teodesian/TestRail-Perl.git>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2022 by George S. Baugh.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut
__END__
L<TestRail::API>
L<File::HomeDir> for the finding of .testrailrc