File Coverage

bin/testrail-lock
Criterion Covered Total %
statement 37 39 94.8
branch 4 6 66.6
condition 1 2 50.0
subroutine 9 9 100.0
pod n/a
total 51 56 91.0


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2             # ABSTRACT: Lock a test in a TestRail, and return the test name if successful.
3             # PODNAME: TestRail::Bin::Lock
4              
5             package TestRail::Bin::Lock;
6             $TestRail::Bin::Lock::VERSION = '0.051';
7 1     1   585 use strict;
  1         3  
  1         31  
8 1     1   5 use warnings;
  1         2  
  1         25  
9 1     1   602 use utf8;
  1         15  
  1         6  
10              
11 1     1   483 use TestRail::Utils;
  1         4  
  1         43  
12 1     1   563 use TestRail::Utils::Lock;
  1         5  
  1         46  
13              
14 1     1   815 use Getopt::Long qw{GetOptionsFromArray};
  1         10870  
  1         5  
15 1     1   661 use File::HomeDir qw{my_home};
  1         5689  
  1         73  
16 1     1   479 use Sys::Hostname qw{hostname};
  1         1176  
  1         413  
17              
18             if ( !caller() ) {
19             my ( $out, $code ) = run( 'args' => \@ARGV );
20             print $out;
21             exit $code;
22             }
23              
24             sub run {
25 2     2   6006 my %params = @_;
26 2         6 my $opts = {};
27              
28             #Parse config file if we are missing api url/key or user
29 2   50     7 my $homedir = my_home() || '.';
30 2 50       93 if ( -e $homedir . '/.testrailrc' ) {
31 0         0 $opts = TestRail::Utils::parseConfig($homedir);
32             }
33              
34             GetOptionsFromArray(
35             $params{'args'},
36             'apiurl=s' => \$opts->{'apiurl'},
37             'password=s' => \$opts->{'password'},
38             'user=s' => \$opts->{'user'},
39             'l|lockname=s' => \$opts->{'lockname'},
40             'j|project=s' => \$opts->{'project'},
41             'p|plan=s' => \$opts->{'plan'},
42             'r|run=s' => \$opts->{'run'},
43             'c|config=s@' => \$opts->{'configs'},
44             'm|match=s' => \$opts->{'match'},
45             'no-match=s' => \$opts->{'no-match'},
46             'n|no-recurse' => \$opts->{'no-recurse'},
47             't|case-type=s@' => \$opts->{'case-types'},
48             'e|encoding=s' => \$opts->{'encoding'},
49 2         27 'h|help' => \$opts->{'help'},
50             );
51              
52 2 100       2920 if ( $opts->{help} ) { return ( '', TestRail::Utils::help() ); }
  1         6  
53              
54 1         3 $opts->{'browser'} = $params{'browser'};
55 1         5 $opts->{'hostname'} = hostname;
56              
57 1         25 TestRail::Utils::interrogateUser( $opts,
58             qw{apiurl user password project run lockname} );
59              
60 1         3 my $tr = TestRail::Utils::getHandle($opts);
61              
62 1         8 my $ret = TestRail::Utils::Lock::pickAndLockTest( $opts, $tr );
63              
64 1 50       51 return ( 'Could not lock case.', 255 ) if !$ret;
65              
66 0           return ( $ret->{'path'} . "\n", 0 );
67             }
68              
69             1;
70              
71             =pod
72              
73             =encoding UTF-8
74              
75             =head1 NAME
76              
77             TestRail::Bin::Lock - Lock a test in a TestRail, and return the test name if successful.
78              
79             =head1 VERSION
80              
81             version 0.051
82              
83             =head1 SYNOPSIS
84              
85             # Lock a group of tests and execute them
86             testrail-tests [OPTIONS] | xargs testrail-lock [OPTIONS] | xargs prove -PTestrail=...
87              
88             require `which testrail-lock`;
89             TestRail::Bin::Lock::run('args' => \@args);
90              
91             =head1 DESCRIPTION
92              
93             testrail-lock - pick an untested/retest test in TestRail, lock it, and return the test name if successful.
94              
95             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.
96             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.
97             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.
98              
99             Will respect test priority when making the choice of what test to lock.
100              
101             Can also be used as the modulino TestRail::Bin::Lock.
102             Has a single 'run' function which accepts a hash with the 'args' parameter being the array of arguments.
103              
104             =head1 PARAMETERS:
105              
106             =head2 MANDATORY PARAMETERS
107              
108             =over 4
109              
110             --apiurl : full URL to get to TestRail index document
111              
112             --password : Your TestRail Password, or a valid API key (TestRail 4.2 and above).
113              
114             --user : Your TestRail User Name.
115              
116             -j --project : desired project name.
117              
118             -r --run : desired run name.
119              
120             -l --lockname : internal name of lock status.
121              
122             =back
123              
124             All mandatory options not passed with the above switches, or in your ~/.testrailrc will be prompted for.
125              
126             =head2 SEMI-OPTIONAL PARAMETERS
127              
128             =over 4
129              
130             -p --plan : desired plan name. Required if the run passed is a child of a plan.
131              
132             -m --match : attempt to find filenames matching the test names in the provided directory.
133              
134             --no-match : attempt to find filenames that do not match test names in the provided directory.
135              
136             -n --no-recurse : if match (or no-match) passed, do not recurse subdirectories.
137              
138             -t --case-type : Only attempt to lock cases of the specified type. May be passed multiple times.
139              
140             -e --encoding : Character encoding of arguments. Defaults to UTF-8. See L for supported encodings.
141              
142             =back
143              
144             =head2 OPTIONAL PARAMETERS
145              
146             =over 4
147              
148             -c --config : configuration name to filter plans in run. Can be passed multiple times.
149              
150             =back
151              
152             =head1 CONFIGURATION FILE
153              
154             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.
155             Valid Keys are the same as documented by L.
156             All options specified thereby are overridden by passing the command-line switches above.
157              
158             =head1 MISCELLANEOUS OPTIONS:
159              
160             =over 4
161              
162             --help : show this output
163              
164             =back
165              
166             =head1 SPECIAL THANKS
167              
168             Thanks to cPanel Inc, for graciously funding the creation of this distribution.
169              
170             =head1 AUTHOR
171              
172             George S. Baugh
173              
174             =head1 SOURCE
175              
176             The development version is on github at L
177             and may be cloned from L
178              
179             =head1 COPYRIGHT AND LICENSE
180              
181             This software is copyright (c) 2021 by George S. Baugh.
182              
183             This is free software; you can redistribute it and/or modify it under
184             the same terms as the Perl 5 programming language system itself.
185              
186             =cut
187              
188             __END__