=head1 NAME

B<xcattest> - Run xcat test cases. 

=head1 SYNOPSIS

B<xcattest> [B<-?|-h>] 

B<xcattest> [B<-f> I<configure file>] [B<-b> I<case bundle list>] [B<--restore>]

B<xcattest> [B<-f> I<configure file>] [B<-t> I<case list>] [B<--restore>]

B<xcattest> [B<-f> I<configure file>] [B<-c> I<cmd list>] [B<-l>] [B<--restore>]

=head1 DESCRIPTION

This command is used to run xCAT automated test and output the result to /opt/xcat/share/xcat/tool/xcat/result. All test cases is in the directory /opt/xcat/share/xcat/tools/autotest. Now there are some cases for basic function of xCAT. Each case has a unique case name. The cases for I<command> is place in directory /opt/xcat/share/xcat/tools/autotest/I<command>. When xcattest is run with -c , it will run all cases in the specified directory. User can add custom cases in the corresponding directory or add new directory if there is no corresponding directory.

=head1 OPTIONS

=over 10

=item B<-?|-h>

Display usage message.

=item B<-f> I<configure file>

Read configuration information from the configure file, default configure file is  /opt/xcat/share/xcat/tools/autotest/default.conf. See /opt/xcat/share/xcat/tools/autotest/*.conf.template for example.
             	
=item B<-b> I<case bundle list>

Comma separated list of file which contains cases which will be run. Default to run all cases.
             	
=item B<-t> I<case list>

Comma separated list of cases which will be run. Default to run all cases.
							
=item B<-c> I<cmd list>

Comma separated list of commands which the related cases will be run. Default to run all cases.

=item B<-l>

Display all available cases.
            	 
=item B<--restore>

Restore test environment after test.

=back
            
=head1 RETURN VALUE

0 The command completed successfully.

1 An error has occurred.

=head1 TEST CASE

The cases is specified as:

  #required, case name
  start:case name
  #optional, precondition
  os:AIX/Linux
  #optional, precondition
  arch:ppc/x86
  #optional, precondition
  hcp:hmc/mm/bmc/fsp
  #required, command need to run
  cmd:comand
  #optional, check return code of last executed command
  check:rc == or != return code
  #optional, check output of last executed command
  check:output== or != or =~ or !~ output check string
  end

The I<output check string> can be regular expression.

=head1 EXAMPLES

=over 4

=item 1.

To run all  test cases related command rpower:

  xcattest -c /tmp/config -c rpower
	
=item 2. 

To run custom bundle:

  xcattest -l  > /tmp/custom.bundle
  edit custom.bundle
  xcattest -b custom.bundle
	
=item 3.

To run specified test cases, and restore test environment after test.

  xcattest -t lsdef_t_o_l_z --restore

=item 4.

To add a new case to test chvm. In the example, we assume that the min_mem should not be equal to 16 in the lpar profile of computenode. The case name is chvm_custom. It create a test lpar named testnode firstly, that change the min_mem of the lpar to 16 using chvm, then check if min_mem have changed correctly. At last, the testnode be remove to ensure no garbage produced in the cases. 

  add a new file filename in /opt/xcat/share/xcat/tools/autotest/chvm
  edit filename
  start:chvm_custom
  hcp:hmc
  cmd:lsvm $$CN > /tmp/autotest.profile
  check:rc==0
  cmd:mkdef -t node -o testnode mgt=hmc groups=all
  cmd:mkvm testnode -i $$MaxLparID -l $$CN
  check:rc==0
  cmd:perl -pi -e 's/min_mem=\d+/min_mem=16/g' /tmp/autotest.profile
  cmd:cat /tmp/autotest.profile|chvm testnode
  check:rc==0
  cmd:lsvm testnode
  check:output=~min_mem=16
  cmd:rmvm testnode
  cmd:rm -f /tmp/autotest.profile
  end

=back

=head1 INLINE FUNCTION

There are some inline functions in the automated test tool. The function can be called in test cases as __FUNCTIONNAME(PARAMTERLIST)__. The function can be used in I<command> and I<output check string>. 
The functions are:

1. B<GETNODEATTR(nodename, attribute)> To get the value of specified node's attribute

2. B<INC(digit)> To get value of digit+1.

For example:
      To run rscan command with hcp point of compute node specified in configuration file
      cmd: rscan __GETNODEATTR($$CN, hcp)__ -z
      
=head1 FILES

/opt/xcat/bin/xcattest