From 6d358b2a706e45c3126ce92772692d80badf53d8 Mon Sep 17 00:00:00 2001 From: Jens Rehsack Date: Fri, 10 Aug 2012 13:04:38 +0200 Subject: [PATCH] improve documentation part2 --- bin/wtscript2json.pl | 42 +++++++++++++ lib/WWW/Mechanize/Script.pm | 5 ++ lib/WWW/Mechanize/Script/Plugin.pm | 64 +++++++++++++++++-- lib/WWW/Mechanize/Script/Util.pm | 126 ++++++++++++++++++++++++++++++++++++- 4 files changed, 232 insertions(+), 5 deletions(-) diff --git a/bin/wtscript2json.pl b/bin/wtscript2json.pl index 54abcc6..b6d4cc3 100644 --- a/bin/wtscript2json.pl +++ b/bin/wtscript2json.pl @@ -51,6 +51,10 @@ defined( $opts{usage} ) and $opts{usage} and pod2usage(1); opt_required_all( \%opts, qw(input-files) ); opt_exclusive( \%opts, qw(output-files output-pattern) ); opt_required_one( \%opts, qw(output-files output-pattern) ); + +_ARRAY( $opts{"input-files"} ) and $opts{"input-files"} = [ split(",", join(",", @{$opts{"input-files"}}) ) ]; +_ARRAY( $opts{"output-files"} ) and $opts{"output-files"} = [ split(",", join(",", @{$opts{"output-files"}}) ) ]; + _ARRAY( $opts{"input-files"} ) and _ARRAY( $opts{"output-files"} ) and scalar( @{ $opts{"input-files"} } ) != scalar( @{ $opts{"output-files"} } ) @@ -110,3 +114,41 @@ foreach my $filename ( @{ $opts{"input-files"} } ) __END__ +=head1 DESCRIPTION + +wtscript2json is a helper to convert WebTest Script files into a modern +format. Currently the format is hard-coded to JSON. + +To avoid conflicts or duplicates running check_web(2), it's recommended to +use different C in special configuration files for check_web(2) +and wtscript2json (check-web2.json vs. wtscript2json.json vs. check_web.json +as common configuration file for both). See +L for further information. + +=head1 SYNOPSIS + + # search in $config->{script_dirs} for any loadable script config + $ wtscript2json --input-files service1/script1,service1/script2,service2/cool_script \ + --output-files /opt/new_checks/service1/script1.json \ + --output-files /opt/new_checks/service1/script2.json \ + --output-files /opt/new_checks/service2/cool_script.json + + # in-location conversion ... + $ find . -name "*splunk*" + ./check_web_config/log/test_splunk_1.txt + ./check_web_config/log/test_splunk_2.txt + ./check_web_config/log/test_splunk_3.txt + ./check_web_config/log/test_splunk_4.txt + $ wtscript2json --input-files log/test_splunk[1-4] --output-pattern .txt .json + $ find . -name "*splunk*" + $ find . -name "*splunk*" + ./check_web_config/log/test_splunk_1.txt + ./check_web_config/log/test_splunk_2.txt + ./check_web_config/log/test_splunk_3.txt + ./check_web_config/log/test_splunk_4.txt + ./check_web_config/log/test_splunk_4.json + ./check_web_config/log/test_splunk_3.json + ./check_web_config/log/test_splunk_2.json + ./check_web_config/log/test_splunk_1.json + +=cut diff --git a/lib/WWW/Mechanize/Script.pm b/lib/WWW/Mechanize/Script.pm index 7091b87..311faae 100644 --- a/lib/WWW/Mechanize/Script.pm +++ b/lib/WWW/Mechanize/Script.pm @@ -373,6 +373,11 @@ Which checks are executed is defined below C<< test->check >>. Each valid plugin below the I namespace is approved for relevance for the test (see L). +The test specification is enriched by the configuration in +C<< config->defaults >> using L with the I +ruleset. Please care about the ruleset especially when merging arrays +is to expect. + The code to accumulate the return codes from each test is taken from C<< test->check >> as described in L. diff --git a/lib/WWW/Mechanize/Script/Plugin.pm b/lib/WWW/Mechanize/Script/Plugin.pm index ce63475..1c2be40 100644 --- a/lib/WWW/Mechanize/Script/Plugin.pm +++ b/lib/WWW/Mechanize/Script/Plugin.pm @@ -9,31 +9,52 @@ our $VERSION = '0.001_003'; use 5.014; +=method new() + +Instantiates new WWW::Mechanize::Script::Plugin. This is an abstract class. + +=cut + sub new { - my ( $class, $default ) = @_; + my ( $class ) = @_; - my $self = bless( { %{$default} }, $class ); + my $self = bless( { }, $class ); return $self; } +=method get_check_value(\%check,$value_name) + +Retrieves the value for I<$value_name> from the hash I<%check>. + +=cut + sub get_check_value { my ( $self, $check, $value_name ) = @_; $value_name or return; - return $check->{check}->{$value_name} // $self->{check}->{$value_name}; + return $check->{check}->{$value_name}; } +=method get_check_value_as_bool(\%check,$value_name) + +Retrieves the value for I<$value_name> from the hash I<%check> and returns +true when it can be interpreted as a boolean value with true content +(any object is always returned as it is, (?:(?i)true|on|yes) evaluates to +I, anything else to I). + +=cut + sub get_check_value_as_bool { my ( $self, $check, $value_name ) = @_; $value_name or return; - my $val = $check->{check}->{$value_name} // $self->{check}->{$value_name}; + my $val = $check->{check}->{$value_name}; defined($val) or return; ref($val) and return $val; @@ -45,6 +66,14 @@ sub get_check_value_as_bool return 0; } +=method can_check(\%check) + +Proves whether this instance can check anything on the current run test. +Looks if any of the required L are specified in the +check parameters of the current test. + +=cut + sub can_check { my ( $self, $check ) = @_; @@ -61,8 +90,35 @@ sub can_check } +=method check_value_names() + +Returns list of check values which are used to check the response. + +Each I has a IC<_code> counterpart which is used to modify +the return value of L when the check upon that value +fails. + +=cut + sub check_value_names { ... } +=method check_response(\%check,$mech) + +Checks the response based on test specifications. See individual plugins +for specific test information. + +Returns the accumulated code for each failing check along with optional +messages containing details about each failure. + + # no error + return (0); + # some error + return ($code,@messages); + # some error but no details + return ($code); + +=cut + sub check_response { ... } 1; diff --git a/lib/WWW/Mechanize/Script/Util.pm b/lib/WWW/Mechanize/Script/Util.pm index d8e1e81..5f17bde 100644 --- a/lib/WWW/Mechanize/Script/Util.pm +++ b/lib/WWW/Mechanize/Script/Util.pm @@ -24,6 +24,43 @@ $VERSION = '0.001_003'; @EXPORT_OK = qw(opt_required_all opt_required_one opt_exclusive load_config find_scripts); %EXPORT_TAGS = ( ALL => \@EXPORT_OK ); +=head1 EXPORTS + +This module doesn't export anything by default, but any of the following on request: + +=over 4 + +=item * + +opt_required_all + +=item * + +opt_required_one + +=item * + +opt_exclusive + +=item * + +load_config + +=item * + +find_scripts + +=back + +=head1 FUNCTIONS + +=head2 opt_required_one(\%opt_hash, @opt_names) + +Fails by invoking pod2usage when none of the options in @opt_names are +given in %opt_hash. + +=cut + sub opt_required_one { my ( $opt_hash, @opt_names ) = @_; @@ -35,6 +72,13 @@ sub opt_required_one -message => "Missing at least one of " . join( ", ", map { "--$_" } @opt_names ) ); } +=head2 opt_required_all(\%opt_hash, @opt_names) + +Fails by invoking pod2usage when any of the options in @opt_names are +missing in %opt_hash. + +=cut + sub opt_required_all { my ( $opt_hash, @opt_names ) = @_; @@ -51,6 +95,13 @@ sub opt_required_all ); } +=head2 opt_exclusive(\%opt_hash, @opt_names) + +Fails by invoking pod2usage when more than one of the options in @opt_names +are given in %opt_hash. + +=cut + sub opt_exclusive { my ( $opt_hash, @opt_names ) = @_; @@ -68,6 +119,20 @@ sub opt_exclusive ); } +=head2 load_config(;\%opt_hash) + +Tries to load the primary configuration. It looks in any directory returned +by L for files named either I or +like the basename of the invoking script (C<$0>) with any extension +supported by L. The found configuration files are merged into +a single configuration hash using L with the I +ruleset. + +When an option hash is given, the default agent is computed based on +the value of I<$opt_hash{file}>. + +=cut + sub load_config { my %opts; @@ -96,7 +161,7 @@ sub load_config # find config file my @cfg_dirs = uniq map { realpath($_) } config_dirs(); my $progname = fileparse( $0, qr/\.[^.]*$/ ); - my @cfg_pattern = map { ( $progname . "." . $_, "check_web." . $_ ) } Config::Any->extensions(); + my @cfg_pattern = map { ( "check_web." . $_, $progname . "." . $_ ) } Config::Any->extensions(); my @cfg_files = File::Find::Rule->file()->name(@cfg_pattern)->maxdepth(1)->in(@cfg_dirs); if (@cfg_files) { @@ -122,6 +187,65 @@ sub load_config return %cfg; } +=head2 find_scripts(\%cfg,@patterns) + +Finds scripts based on configuration and given patterns. + +=over 4 + +=item * + +When C<%cfg> contains an array with full qualified path names below the +I, those directories are scanned. When the directories are +relative, the are concatenated using L (each +entry in the I is evaluated separately). + +When C<%cfg> contains a string below the key I, the +I is used to find the scripts. + +In any other case, I is used. + +=item * + +The C<@patterns> list must contain one or more file names or expandable +shell patterns with or without directory parts and/or extensions. + +Valid entries are for example: + +=over 8 + +=item - + +qw(check_host_app_one) + +=item - + +qw(check_host/app_one) + +=item - + +qw(check_host_app_one.json) + +=item - + +qw(check_host/app_one.yml) + +=item - + +qw(check_splunk_[1-5]) + +=item - + +qw(splunk/test*) + +=back + +=back + +Returns the list of found script file names. + +=cut + sub find_scripts { my ( $cfg, @patterns ) = @_; -- 2.11.4.GIT