OpenCellular/manufacturing/software/mods/fbt_config.pm

# Copyright (c) 2017-present, Facebook, Inc.
# All rights reserved.
#
# This source code is licensed under the BSD-style license found in the
# LICENSE file in the root directory of this source tree. An additional grant
# of patent rights can be found in the PATENTS file in the same directory.

package mods::fbt_config;
#
#	File: fbt_config.pm
#	
#	This is a module that pre-defined tests that may be run.
#	
#
use Exporter;
our (@ISA, @EXPORT);
@ISA	= 		qw/Exporter/;
@EXPORT	= 		qw/@Ttable $Yoda $Conn1 $Dott $Dled $Resdir/;
use strict;
use Term::ANSIColor	qw/:constants/;
use mods::walker	qw/std_match date_range field_match
			tod_match range_match std_1_match
			led_inquire/;
use mods::chain::dott	qw/$Dottpwr $Dottests/;
use mods::chain::c1	qw/$C1pwr $C1tests/;

our $Resdir	= '/media/sf_vmshr/fb_results';
my $Tsen	= qr/Temperature\ssensor/;
my $Isen	= qr/INA\ssensor/;
my $Prompt	= $ENV{LOGIN_PROMPT} // ':~\$ ';
my @Stdkeys	= (
	ip	=> $ENV{LOGIN_TGT} // '192.168.1.36',
	tip	=> $ENV{TEST_NET} // '192.168.1.19',
	acct	=> $ENV{LOGIN_ACCT} // 'oc',
	pw	=> $ENV{LOGIN_PW} // '123',
	poke	=> qr{$Prompt},
	ldir	=> '/var/log/fbt',
	lfn	=> '/var/log/fbt/fbt.log',
	tdir	=> $Resdir,
);
our $Yoda	= {
	@Stdkeys,
	tests	=> [
	{	# These HRs are individual tests. Each has all info needed.
		# The prog key points to the execuable.
		# A shell test -x will be run before its launch.
		prog	=> '/usr/local/bin/dde3',
		# The res key is a pointer to an array of residual tests.
		# Each res entry will be a test on the text 
		# matched before the prompt generated by running prog.
		res	=> [
			# The HRs within res have keys for test name, regular
			# expression, and a subroutine reference to handle 
			# the test.
			{
				name	=> 'SinCorr',
				re	=> qr/SinCorr:/,
				func	=> \&std_match,
			},
			{
				name	=> 'SumSamp',
				re	=> qr/SumSamp/,
				func	=> \&std_match,
			},
		],
		# The xcode key is a flag to check the exit code of this
		# program.
		xcode	=> 0,
		tid	=> 'Test Case ID 1',
		name	=> 'Run dde3',
		to	=> 3,
	},
	{	
		prog	=> '/usr/local/bin/whatsystem',
		res	=> [
			{
				name	=> 'Apps Build Date',
				re	=> qr/(Apps Build Date:)/,
				func	=> \&std_match,
			},
			{
				name	=> 'FPGA Date',
				re	=> qr/^FPGA Build Date: ([^\.]+)/m,
				func	=> \&date_range,
			},
		],
		xcode	=> 0,
		tid	=> 'Test Case ID 2',
		name	=> 'Run whatsystem',
		to	=> 3,
	},
	{	
		prog	=> '/bin/date',
		args	=> [],
		timereq	=> 1,
		res	=> [
			{
				name	=> 'verify time',
				re	=> qr/^([MTWFS][a-z]{2}\s.+)$/m,
				func	=> \&tod_match,
			},
		],
		xcode	=> 0,
		name	=> 'Set time of day',
		to	=> 3,
	},
	],
};

my $Rpath	= '/home/oc/bin';
my $Upath1	= '/home/oc/opencellular/uhd/host/build/utils';
our $Conn1	= {
	@Stdkeys,
	rcfn	=> '/usr/local/fbin/config/test.poke',
	pon	=> $C1pwr,
	useip	=> 1,
	tests	=> $C1tests,
};

our $Revc	= {
	@Stdkeys,
	rcfn	=> '/usr/local/fbin/config/test.poke',
	tests	=> $C1tests,
};

my $Tpath	= '/usr/local/sbin';
our $Dott =	{
	@Stdkeys,
	pon	=> $Dottpwr,
	poke	=> qr/xyz\$ /, # test.poke file in config sets PS1.
	rcfn	=> '/usr/local/fbin/config/test.poke',
	tests	=> $Dottests,
};

our $Dgui =	{
	@Stdkeys,
	pon	=> [
	{
		prog	=> '/usr/local/fbin/p1apply',
		args	=> [11, 0.54321],
		xcode	=> 0,
		name	=> 'PS1 to ON, 11v, 0.5a',
	},
	{
		prog	=> '/usr/local/fbin/p2apply',
		args	=> [12, 0.54321],
		xcode	=> 0,
		name	=> 'PS2 to ON, 11v, 0.5a',
	},
	{
		prog	=> '/usr/local/fbin/p3on',
		xcode	=> 0,
		name	=> 'PS3 to ON',
	},
	],

	poke	=> qr/xyz\$ /, # test.poke file in config sets PS1.
	rcfn	=> '/usr/local/fbin/config/test.poke',
	tests	=> [
	{	# These HRs are individual tests. Each has all info needed.
		# The prog key points to the execuable.
		# A shell test -x will be run before its launch.
		prog	=> '/usr/bin/arch',
		# The res key is a pointer to an array of regular expressions.
		# Each re will be a test on the text matched before the prompt.
		res	=> [
			# The HRs within res have keys for test name, regular
			# expression, and a subroutine reference to handle 
			# the test.
			{
				name	=> 'x86',
				re	=> qr/(^x86)/m,
				func	=> \&std_match,
			},
			{
				name	=> '6_64',
				re	=> qr/(6_64$)/,
				func	=> \&std_match,
			},
		],
		# The xcode key is a flag to check the exit code of this
		# program.
		xcode	=> 0,
		name	=> 'Run arch',
		to	=> 3,
	},
	{	# These HRs are individual tests. Each has all info needed.
		# The prog key points to the execuable.
		# A shell test -x will be run before its launch.
		prog	=> '/bin/sleep',
		args	=> ['10'],
		# The res key is a pointer to an array of regular expressions.
		# Each re will be a test on the text matched before the prompt.
		res	=> [
			# The HRs within res have keys for test name, regular
			# expression, and a subroutine reference to handle 
			# the test.
			{
				name	=> 'sleep fields',
				re	=> qr/sl(ee)p\s+(\d+)/m,
				func	=> \&field_match,
				marry	=> ['ee', qr/^10$/],
			},
		],
		xcode	=> 0,
		name	=> 'sleep 10',
		to	=> 12,
	},
	{
		prog	=> '/usr/local/fbin/p3off',
		xcode	=> 0,
		name	=> 'PS3 to OFF',
	},
	{
		prog	=> '/usr/local/fbin/p2off',
		xcode	=> 0,
		name	=> 'PS2 to OFF',
	},
	{	# These HRs are individual tests. Each has all info needed.
		prog	=> '/bin/sleep',
		args	=> ['5'],
		res	=> [
			{
				name	=> 'sleep fields',
				re	=> qr/sl(ee)p\s+(\d+)/m,
				func	=> \&field_match,
				marry	=> ['ee', qr/^5$/],
			},
		],
		xcode	=> 0,
		name	=> 'sleep 5',
		to	=> 7,
	},
	{
		prog	=> '/usr/local/fbin/p2on',
		xcode	=> 0,
		name	=> 'PS2 to ON',
	},
	{
		prog	=> '/usr/local/fbin/p1off',
		xcode	=> 0,
		name	=> 'PS1 to OFF',
	},
	{
		prog	=> '/usr/local/fbin/p3on',
		xcode	=> 0,
		name	=> 'PS3 to ON',
	},
	{
		prog	=> '/usr/local/fbin/p2off',
		xcode	=> 0,
		name	=> 'PS2 to OFF',
	},
	{	# These HRs are individual tests. Each has all info needed.
		prog	=> '/bin/sleep',
		args	=> ['5'],
		res	=> [
			{
				name	=> 'sleep fields',
				re	=> qr/sl(ee)p\s+(\d+)/m,
				func	=> \&field_match,
				marry	=> ['ee', qr/^5$/],
			},
		],
		xcode	=> 0,
		name	=> 'sleep 5',
		to	=> 7,
	},
	{	
		prog	=> '/bin/stty',
		args	=> ['-a'],
		res	=> [
			{
				name	=> 'icanon',
				re	=> qr/(\sicanon\s)/,
				func	=> \&std_match,
			},
			{
				name	=> 'speed',
				re	=> qr/speed\s(\d+)/m,
				func	=> \&std_1_match,
			},
			{
				name	=> 'min',
				re	=> qr/(\smin\s=\s1;)/m,
				func	=> \&std_match,
			},
		],
		xcode	=> 0,
		wait	=> 10,
		name	=> 'Run stty',
		to	=> 3,
	},
	],
};

my $Cled	= {
	@Stdkeys,

	tests	=> [
	{	
		prog	=> "$Rpath/occli",
		bgjob	=> "$Rpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['1..14 green'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 1 to 14 green',
				re	=> qr/Set led 1\.\.14 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 1 to 14 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 14], color => ON_GREEN,
					msg	=> 'Are all LEDs green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 1..14 to green',
		tid	=> 'TC_LED_01',
		to	=> 3,
	},
	{	
		prog	=> "$Rpath/occli",
		bgjob	=> "$Rpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['1..5 red'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 1 to 5 red',
				re	=> qr/Set led 1\.\.5 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 1 to 5 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 5], color => ON_RED,
					msg	=> 'Are 1 .. 5 LEDs red, '
						. 'others green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 1..5 to red',
		tid	=> 'TC_LED_01.a',
		to	=> 3,
	},
	{	
		prog	=> "$Rpath/occli",
		bgjob	=> "$Rpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['10..14 red'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 10 to 14 red',
				re	=> qr/Set led 10\.\.14 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 10 to 14 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 5, 10 .. 14], 
					color => ON_RED,
					msg	=> 'Are 1 .. 5 and 10 .. 14 '
						. 'LEDs red, with 6 .. 9 '
						. 'green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 10..14 to red',
		tid	=> 'TC_LED_01.b',
		to	=> 3,
	},
	{	
		prog	=> "$Rpath/occli",
		bgjob	=> "$Rpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['6..9 off'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 6 to 9 off',
				re	=> qr/Set led 6\.\.9 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 6 to 9 off',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [6 .. 9], color => ON_BLACK,
					msg	=> 'Are 1 .. 5 and 10 .. 14 '
						. 'LEDs red, with 6 .. 9 '
						. 'off?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 6..9 to off',
		tid	=> 'TC_LED_01.c',
		to	=> 3,
	},
	],
};

our $Dled	= {
	@Stdkeys,

	poke	=> qr/xyz\$ /, # test.poke file in config sets PS1.
	rcfn	=> '/usr/local/fbin/config/test.poke',
	tests	=> [
	{	
		prog	=> "$Tpath/occli",
		bgjob	=> "$Tpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['1..14 green'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 1 to 14 green',
				re	=> qr/Set led 1\.\.14 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 1 to 14 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 14], color => ON_GREEN,
					msg	=> 'Are all LEDs green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 1..14 to green',
		tid	=> 'TC_LED_01',
		to	=> 3,
	},
	{	
		prog	=> "$Tpath/occli",
		bgjob	=> "$Tpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['1..5 red'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 1 to 5 red',
				re	=> qr/Set led 1\.\.5 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 1 to 5 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 5], color => ON_RED,
					msg	=> 'Are 1 .. 5 LEDs red, '
						. 'others green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 1..5 to red',
		tid	=> 'TC_LED_01.a',
		to	=> 3,
	},
	{	
		prog	=> "$Tpath/occli",
		bgjob	=> "$Tpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['10..14 red'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 1 to 5 red',
				re	=> qr/Set led 10\.\.14 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 10 to 14 red',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [1 .. 5, 10 .. 14], 
					color => ON_RED,
					msg	=> 'Are 1 .. 5 and 10 .. 14 '
						. 'LEDs red, with 6 .. 9 '
						. 'green?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 10..14 to red',
		tid	=> 'TC_LED_01.b',
		to	=> 3,
	},
	{	
		prog	=> "$Tpath/occli",
		bgjob	=> "$Tpath/ocmw_uart",
		subcmd	=> 'led',
		args	=> ['6..9 off'],
		fgpoke	=> 'opencellular# ',
		res	=> [
			{
				name	=> 'LED 6 to 9 off',
				re	=> qr/Set led 6\.\.9 : Success/m,
				func	=> \&std_match,
			},
			{
				name	=> 'Observe LED 6 to 9 off',
				re	=> qr/y|n/mi,
				func	=> \&led_inquire,
				led	=> {
					range	=> [6 .. 9], color => ON_BLACK,
					msg	=> 'Are 1 .. 5 and 10 .. 14 '
						. 'LEDs red, with 6 .. 9 '
						. 'off?',
					},
			},
		],
		xcode	=> 0,
		name	=> 'LED 6..9 to off',
		tid	=> 'TC_LED_01.c',
		to	=> 3,
	},
	],
};

#                Index  0      1      2      3      4      5      6
our @Ttable	= ($Conn1, $Yoda, $Dott, $Dled, $Cled, $Dgui, $Revc);

1;

__END__

=head1 NAME

mods::fbt_config - A configuration file for the fbt(1) program.

=head1 SYNOPSIS

 use mods::fbt_config qw/@Ttable $Resdir/;

=head1 DESCRIPTION

The B<mods::fbt_config> module contains a table of 
hash references to 
the tests used by the fbt(1) program. The array B<@Ttable>  
is exported from this module. Within it are 
references to defined test hashes which in turn 
contain a list of tests to be performed.

Also exported from B<mods::fbt_config> is a scalar B<$Resdir> 
that contains the name of the 
directory where test result files will be kept.

Test result files have the form I<fbt.mo-day-year_hr-min-sec.json>. 
The output file format is serialized ascii data that is I<json> compatible.

The index that the fbt(1) program uses to select a particular 
defined test is set by the environment variable B<FBT_TEST_TABLE_INDEX>. 
If this environment variable is not defined, the table 
index is set to zero.

=head2 TEST TABLE KEYS

There is a standard group of keys that may be used 
as the basis for most test definitions. These
standard keys are contained in the array B<@Stdkeys>.

 our $Resdir    = '/media/sf_vmshr/fb_results';
 my $Prompt     = $ENV{LOGIN_PROMPT} // ':~\$ ';
 my @Stdkeys    = (
     ip         => $ENV{LOGIN_TGT} // '192.168.1.36',
     acct       => $ENV{LOGIN_ACCT} // 'oc',
     pw         => $ENV{LOGIN_PW} // '123',
     poke       => qr{$Prompt},
     ldir       => '/var/log/fbt',
     lfn        => '/var/log/fbt/fbt.log',
     tdir       => $Resdir,
 );

Simply insert the B<@Stdkeys> array into the test definition 
as seen below and all of the overhead keys are set for a particular 
test. Note in the example below that the key B<poke> is defined 
in both the B<@Stdkeys> array and in the B<$Dott> test definition. 
This is perfectly legitimate as Perl will simply use the most recent value 
for the key B<poke>, overwriting any prior one.

 our $Dott =	{
     @Stdkeys,
         poke   => qr/xyz\$ /, # test.poke file in config sets PS1.
         pon    => [ ...
         tests  => [ ...

Note that the 
B<$Dott> test definition within this module 
is used strictly for fbt(1) algorithm 
testing and is not appropriate for use with any actual hardware.

=head3 GENERAL TEST KEYS

Please refer to the B<@Stdkeys> and B<$Dott> code examples above 
as each of their keys are explained below.

=head4 ip

B<ip> is the key for the address of the unit under test (UUT). 
The value is either the value of the environment variable 
B<LOGIN_TGT>, or if not defined, B<192.168.1.36> is used.

=head4 acct

B<acct> is the account name key. When the fbt(1) program logs into 
the UUT, it needs to specify an account name. The value of the 
B<acct> key is either the value of the environment variable 
B<LOGIN_ACCT> or if not defined in the environment, B<oc> 
is used.

=head4 pw

B<pw> is the UUT's account password. The value is set 
to the environment variable's B<LOGIN_PW> value or 
B<123> if B<LOGIN_PW> is not set.

=head4 poke

The B<poke> key has a value that the Expect(3pm) module uses 
as its prompt. The value of B<poke> is set from the  
environment variable B<LOGIN_PROMPT> or 
the default prompt is the quoted 
regular expression B<':~\$ '>. (This prompt has the following 
four characters: colon, tilde, dollar sign, and a space.)

=over

Note that in the example above, a determination is 
made as to which string shall be used for the prompt string. 
The answer to the logical defined or (i.e. //) is 
stored in the scalar B<$Prompt> variable. This value is 
then quoted in a B<qr> expression. The prompt string 
sent to the Expect(3pm) module should always be a 
quoted regular expression and Perl operators cannot be 
executed within a quoted string. Thus the prompt is evaluated 
first and then quoted. Also note that the dollar sign 
within the default prompt is escaped. The dollar sign 
usually means an end of line, not a literal dollar sign 
inside a regular expression.

=back

=head4 ldir

The B<ldir> key specifies the directory to be used to log 
dialogs with the UUT. The B<lfn> key is the name of 
the file that the fbt(1) program will use to capture the 
test dialog. For the B<$Conn1> hash reference, these keys 
are set to B</var/log/fbt> and B</var/log/fbt/fbt.log>.

=head4 tdir

B<tdir> is the key that points to the location where the test 
results are kept.

=head4 pon

The optional B<pon> key calls the pon(1) program 
or variations of pon(1) at the beginning 
of the test and poff(1) at the end of the test. This key 
is optional and if not defined, the UUT is presumed to be powered 
on through manual intervention, not software control. 

The value of the key B<pon> is an array reference containing 
hash references used to setup the UUT for test operation. 
The keys for the B<pon> hash references are the same as 
those used with B<tests> below with these exceptions. 

The keys B<timereq>, B<tid>, B<subcmd>, B<bgjob>, and B<fgpoke> 
are ignored when used within a B<pon> sequence.

A side-effect of using the B<pon> startup sequence is that 
its use creates three global keys B<peh>, B<plfn>, and B<ppoke>. 
The B<peh> 
key contains the Expect(3pm) 
handle used to call the pon(1) commands 
through the local shell, this is not the shell session 
used to communicate with the UUT.
The power sequence related activity is kept in a 
separate log file from the main test activity. 

The key B<plfn> defines this log file name and it is written 
into the directory defined by the key B<ldir>. As of this 
writing, the default value for the power related log file 
name is B<fbt.pwr.log>.
The B<ppoke> value is the power-on shell prompt used with the B<peh> 
session. If this power-on shell session is created, the 
dialog is appended to the power log file. The default name 
and path are:

 /var/log/fbt/fbt.pwr.log

The B<peh> Expect(3pm) handle 
remains open for the duration of the test and may be referred to 
by the regular tests defined by the B<tests> key.

=head4 tests

The B<tests> key points to an array reference that contains 
hash references that test the UUT. The B<tests> key points 
to a list of things to do for a particular test.

=head3 KEYS USED BY THE KEY tests

Note that for each member of the array pointed to by B<tests>, 
the fbt(1) program assigns a major test number for it. Any residual 
tests defined by the key B<res>, has assigned to each of its members 
a minor number at run time. 

Test numbers are in the form B<major.minor>. Where the major 
number comes from the test's position within the array 
pointed to by B<tests> and the minor number from 
the residual test position from within the array pointed 
to by B<res>, if defined.

For example, the first test run will be test B<1.0>. If this 
test had two residual tests following, those tests would be 
tests B<1.1> and B<1.2>.

For each hash reference pointed to by B<tests>, 
the following keys can be used. 

=over

=item prog (required)

The major test program to be run is defined by the key B<prog>. 
This program must exist within the UUT's file system. The B<prog> 
key must have a value that is the absolute path to 
the program executable file or it may be a function reference. 
In the case of an executable program, before B<prog> is launched, 
the fbt(1) program makes a check to ensure that an executable 
file by that name exists. If it does not, fbt(1) exists 
immediately with an error.

=item args (optional)

Contained within the array pointed to by the key B<args> 
is a list of arguments that will be passed to the program 
being run at this test step.

=item tid (optional)

The key B<tid> provides a test case identifier to be used in 
the test report.

=item to (optional, default 5 seconds)

The key B<to> has a value that represents the timeout value 
to be used by Expect(3pm) waiting for the return prompt.

=item name (optional, default unknown)

The B<name> key provides a text label identifying the reason 
for this particular test.

=item poke (optional, default previously defined)

Use the B<poke> key to override the previously 
defined Expect(3pm) prompt. 
Note that the internal fbt(1) object running these tests will remember 
the change of the Expect(3pm) prompt from this test forward.
Therefore, the first B<poke> change stays in effect 
until the next B<poke> is defined or the program ends.

If tests begin using a prompt appropriate for the bash(1) 
shell, and then an interactive program is lauched requiring 
a different prompt, set the key B<poke> to the interactive 
prompt at this test step. At the test step that exits 
the interactive mode, set B<poke> back to a bash(1) 
appropriate prompt.

=item wait (optional, default 0, floating point may be used)

If time must elapse before the current test step is executed, 
The B<wait> key may be specified to force the fbt(1) program 
into a Perl usleep call. The value given to wait 
is in seconds with floating point notation allowed for time 
intervals less than a second. Therefore, when B<wait> is set 
to the value 0.25, a 250 milliseond delay is inserted before 
executing the test step containing the B<wait> key. The value 
of 2 delays execution by two seconds. 

In the case where the I<occli> command is used, the wait 
interval will happen after the background job is launched 
and before I<occli> is launched.

=item xcode (optional, default skip check)

Setting the key B<xcode> signals an examination of this step's 
exit code. 
The B<xcode> key is both a flag and a value. When set, 
the fbt(1) program will check the exit code from 
the program run at this major test step. Its value must match 
the specified value of the B<xcode> key.

Most Linux commands return a zero for successful 
operation, but some do not. Using a non-zero 
B<xcode> value allows testing of those commands 
that return a non-zero value or exit codes 
from a forced failure.

=item timereq (optional, nodefault)

The B<timereq> flag notifies the test program that 
time of day information is required to be 
passed to the B<prog> program appended to the 
list of arguments. The format of the additional 
argument will be MMDDhhmmCCYY as per the man 
page of the Linux date(1) command.

=item subcmd (mandatory for the program occli)

The Linux program I<occli> performs various set and get 
commands. The B<subcmd> key is the text used for the  
I<occli> command to be combined sequentially with 
the argument list.

=item bgjob (mandatory for the program occli)

The key B<bgjob> points to the location of the middle 
ware program to be run in the background while the I<occli> 
program runs in the foreground.

=item fgpoke (mandatory for the program occli)

While running the I<occli> program in the foreground, 
it will present to fbt(1) a different prompt than 
what is used by the Linux shell. The key B<fgpoke> 
defines the prompt of the I<occli> command.

=item res (optional, no default)

The B<res> key defines residual tests to be run 
analyzing the output from the previously 
run major step.

The residual tests are defined through 
an array of hash references pointed to by the B<res> key.

Any number of sub tests may be specified through 
B<res>. Each hash reference 
within the array pointed to by B<res> must have these keys 
defined within it: B<name>, B<re>, and B<func>.

An optional key B<led> may point to the LED test required key 
set. The B<led> key point to an anonymous hash. The B<led> 
hash must contain keys B<range>, B<color>, and B<msg>.

The value for B<range> could be a single number (1 to 14 only) or 
a range of numbers within an anonymous array.

The B<color> key has a value equal to the ANSIcolor(3pm) 
color constant desired.

The B<msg> key is the prompt string for the user. Note that 
the LED test is an interactive test where the screen 
is painted for the operator and test results come from 
the operator's keyboard. A sample LED test is given below.

Referring to the example below, this test runs the B<occli> command 
as the major test. As configured, the B<ocmw_uart> command must 
be running in the background otherwise it is launched at this 
step.

The B<occli> program will prompt with the string B<opencellular# >. 
Then the command to it will be 'B<led 1..5 red>'. The return will 
hopefully be 'B<Set led 1..5 : Success>'. After that the B<occli> 
prompt will be issued again and the fbt(1) program will type 
B<quit> to end this session. After quit, this major test will 
expect the normal B<poke> prompt indicating that the shell is 
ready for another command. Before the residual tests are executed, 
the key B<xcode> forces a check for the B<occli>'s exit code. 
The exit code must match a zero for this major test to pass. 

All of the output data is preserved for use by the residual tests. 
In the example below, the first minor test examines the output from 
the B<occli> command. All minor test one looks for is that the 
B<occli> command produced the text B<led 1..5 red>. The function 
B<std_match> will attempt to match the regular expression defined 
by B<re> against the text output from B<occli>.

The second minor test is an interactive B<led> test. This test 
uses the function B<led_inquire> to prompt the user with an outline 
of the LED configuration as expect on the UUT. The key B<led> 
defines what B<led_inquire> is to fill in with what color on 
the user's screen. It then posts the string of key B<msg> 
and receives the test operator's answer. In the case below, 
if the operator observes that LED one through five are red while 
all others are green, he reports B<y>. The B<led_inquire> function 
prints an outline on the screen of the expected LED configuration 
as a visual aid.

 {
     prog    => "$Rpath/occli",
     bgjob   => "$Rpath/ocmw_uart",
     subcmd  => 'led',
     args    => ['1..5 red'],
     fgpoke  => 'opencellular# ',
     res     => [
             {  # This is {res}[0] and minor test 1.
             name    => 'LED 1 to 5 red',
             re      => qr/Set led 1\.\.5 : Success/m,
             func    => \&std_match,
             },
             {  # This is {res}[1] and minor test 2.
             name    => 'Observe LED 1 to 5 red',
             re      => qr/y|n/mi,
             func    => \&led_inquire,
             led     => {
                     range  => [1 .. 5], color => ON_RED,
                     msg => 'Are 1 .. 5 LEDs red, others green?',
                     },
              },
      ],
      xcode   => 0,
      name    => 'LED 1..5 to red',
      tid     => 'TC_LED_01.a',
      to      => 3,
 },

The value associated with the residual test key B<name> 
is a text string, similar to the B<name> key used 
for each major test. These residual tests will be 
identified by their names along with the test number 
created by 
combining the major test number and minor test number. 
The minor number test is equal to the place 
this residual test is found within the array 
that the B<res> key points to plus one. Perl 
arrays begin at zero. The first B<res> minor number 
will be one. Consider a B<res> array containing three members, 
they will be numbered minor test number one, two, and three. 

Next, the B<re> required key must point to 
a Perl quoted regular expression. A quoted regular 
expression takes the form: 'qr/STRING/msixpodualngc'. 
The text STRING defines the regular expression. 
Modifiers (msixpodualngc) 
may be added to alter the potential match. 

Finally, the B<func> key must point to 
a function that will decide whether this 
residual test passes or fails. 

=back

=head2 FUNCTIONS AVAILABLE FOR KEY func

The functions available for residual processing are located in 
the Perl module mods::walker(3). Below is a brief description 
of what each does.

Note that a call to the function reference pointed to by B<func> 
uses a provided regular expression that will be compared against the 
text output from the encapsulating test step or from user input, 
as in the case of residual tests of the LEDs.

=head3 std_1_match()

The B<std_1_match()> function expects a regular expression 
that contains one capture field. On success, the function 
passes to the test report the contents of the capture field.

=head3 std_match()

The B<std_match()> determines its pass or fail criteria based 
on whether the regular expression it is given matches 
the previous test's output text.

=head3 tod_match()

The B<tod_match()> function expects a regular expression to capture 
date and time information contained within the text of the 
previously executed command. Once the text string is extracted, 
the B<tod_match()> function converts this information to the number 
of non-leap seconds since the epoch and subtracts this information from the 
current time on the test system. B<tod_match()> will pass if 
both the regular expression matches and the time 
difference is within 
120 seconds of the current time.

The key B<timereq> being set in the enclosing test forces the 
time of day and date to be set in the UUT. Once set, the test 
system and UUT clocks should be in close agreement. Refer to 
the key B<timereq> above.

=head3 field_match()

The B<field_match()> function matches fields within fields.

The B<field_match()> function works with two specifications for 
matching text from the enclosing test. The first is the 
normal regular expression pointed to by the key B<re>. 
Within the regular expression, there needs to be at least one 
capture group specified. For each capture group, expected 
text is defined within an array pointed to by the key 
B<marry>.

B<field_match()> returns a pass when all capture groups match and 
from each captured group, the respective B<marry> value matches 
as well.

=head3 range_match()

The function B<range_match()> uses tolerances specified in the 
module B<mods::tolerance.pm>. The key B<name> for this residual 
test must match a key within the B<%Tol> hash contained within 
the B<mods::tolerance.pm> file.

The objective of the B<range_match()> function is to extract 
a field out of the enclosing test output text and check its 
value against the minimum and maximum values allowed 
as specified with the B<%Tol> hash.

=head1 ENVIRONMENT VARIABLES

FBT_TEST_TABLE_INDEX -- Used by fbt(1) to index into @Ttable. (Default: 0)

LOGIN_PROMPT -- Prompt text for use by Expect(3pm). (Default: ':~\$ ')

LOGIN_TGT -- IP address of the UUT. (Default: 192.168.1.36)

LOGIN_ACCT -- UUT account name. (Default: oc)

LOGIN_PW -- UUT account password. (Default: 123)

=head1 FILES

/usr/local/fbin/mods/fbt_config.pm -- Module file name.

/usr/local/fbin/mods/tolerance.pm -- Tolerance file used with range_match()().

/media/sf_vmshr/fb_results/fbt*.json -- Test results.

=head1 SEE ALSO

fbt(1), lresult(1), mods::walker(3), pon(1)

=cut