Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Cmd::Common(3)  User Contributed Perl Documentation Test::Cmd::Common(3)

NAME
       Test::Cmd::Common - module for common Test::Cmd error handling

SYNOPSIS
	 use Test::Cmd::Common;

	 $test = Test::Cmd::Common->new(string => 'functionality being tested',
			       prog => 'program_under_test',
			       );

	 $test->run(chdir => 'subdir', fail => '$? != 0',
		       flags =>	'-x', targets => '.',
		       stdout => <<_EOF_, stderr => <<_EOF_);
	 expected standard output
	 _EOF_
	 expected error	output
	 _EOF_

	 $test->subdir('subdir', ...);

	 $test->read(\$contents, 'file');
	 $test->read(\@lines, 'file');

	 $test->write('file', <<_EOF_);
	 contents of the file
	 _EOF_

	 $test->file_matches();

	 $test->must_exist('file', ['subdir', 'file'], ...);

	 $test->must_not_exist('file', ['subdir', 'file'], ...);

	 $test->copy('src_file', 'dst_file');

	 $test->chmod($mode, 'file', ...);

	 $test->sleep;
	 $test->sleep($seconds);

	 $test->touch('file', ...);

	 $test->unlink('file', ...);

DESCRIPTION
       The "Test::Cmd::Common" module provides a simple, high-level interface
       for writing tests of executable commands	and scripts, especially
       commands	and scripts that interact with the file	system.	 All methods
       throw exceptions	and exit on failure.  This makes it unnecessary	to add
       explicit	checks for return values, making the test scripts themselves
       simpler to write	and easier to read.

       The "Test::Cmd::Common" class is	a subclass of Test::Cmd.  In essence,
       "Test::Cmd::Common" is a	wrapper	that treats common Test::Cmd error
       conditions as exceptions	that terminate the test.  You can use
       "Test::Cmd::Common" directly, or	subclass it for	your program and add
       additional (or override)	methods	to tailor it to	your program's
       specific	needs.	Alternatively, "Test::Cmd::Common" serves as a useful
       example of how to define	your own Test::Cmd subclass.

       The "Test::Cmd::Common" module provides the following importable
       variables:

       $_exe
	   The executable file suffix.	This value is normally available as
	   $Config{_exe} in Perl version 5.005 and later.  The
	   "Test::Cmd::Common" module figures it out via other means in
	   earlier versions.

       $_o The object file suffix.  This value is normally available from
	   $Config{_o} in Perl version 5.005 and later.	 The
	   "Test::Cmd::Common" module figures it out via other means in
	   earlier versions.

       $_a The library file suffix.  This value	is normally available from as
	   $Config{_a} in Perl version 5.005 and later.	 The
	   "Test::Cmd::Common" module figures it out via other means in
	   earlier versions.

       $_so
	   The shared library file suffix.  This value is normally available
	   as $Config{_so} in Perl version 5.005 and later.  The
	   "Test::Cmd::Common" module figures it out via other means in
	   earlier versions.

       $_is_win32
	   A Boolean value that	reflects whether the current platform is a
	   Win32 system.

METHODS
       "new"
	   Creates a new test environment object.  Any arguments are keyword-
	   value pairs that are	passed through to the construct	method for the
	   base	class from which we inherit our	methods	(that is, the
	   Test::Cmd class).  In the normal case, this should be the program
	   to be tested	and a description of the functionality being tested:

	       $test = Test::Cmd::Common->new(prog => 'my_program',
					      string =>	'cool new feature');

	   By default, methods that match actual versus	expected output	(the
	   "run", and "file_matches" methods) use an exact match.  Tests that
	   require regular expression matches can specify this on
	   initialization of the test environment:

	       $test = Test::Cmd::Common->new(prog => 'my_program',
					      string =>	'cool new feature',
					      match_sub	=> \&Test::Cmd::diff_regex);

	   or by executing the following after initialization of the test
	   environment:

	       $test->match_sub(\&Test::Cmd::diff_regex);

	   Creates a temporary working directory for the test environment and
	   changes directory to	it.

	   Exits NO RESULT if the object can not be created, the temporary
	   working directory can not be	created, or the	current	directory
	   cannot be changed to	the temporary working directory.

       "run"
	   Runs	the program under test,	checking that the test succeeded.
	   Arguments are keyword-value pairs that affect the manner in which
	   the program is executed or the results are evaluated.

	       chdir =>	'subdir'
	       fail => 'failure	condition' # default is	'$? != 0'
	       flags =>	'Cons flags'
	       stderr => 'expected error output'
	       stdout => 'expected standard output'
	       targets => 'targets to build'

	   The test fails if:

	     --	 The specified failure condition is met.  The default failure
		 condition is '$? != 0', i.e. the program exits	unsuccesfully.
		 A not-uncommon	alternative is:

		     $test->run(fail =>	'$? == 0');	   # expect failure

		 when testing how the program handles errors.

	     --	 Actual	standard output	does not match expected	standard output
		 (if any).  The	expected standard output is an array of	lines
		 or a scalar which will	be split on newlines.

	     --	 Actual	error output does not match expected error output (if
		 any).	The expected error output is an	array of lines or a
		 scalar	which will be split on newlines.

		 This method will test for NO error output by default if no
		 expected error	output is specified (unlike standard output).
		 The error output test may be explicitly suppressed by
		 specifying undef as the "expected" error output:

		     $test->run(stderr => undef);

	   By default, this method performs an exact match of actual vs.
	   expected standard output or error output:

	       $test->run(stdout => <<_EOF_, stderr => _EOF_);
	       An expected STDOUT line,	which must be matched exactly.
	       _EOF_
	       One or more expected STDERR lines,
	       which must be matched exactly.
	       _EOF_

	   Tests that require regular expression matches should	be executed
	   using a test	environment that calls the "match_sub" method as
	   follows:

	       $test->match_sub(\&Test::Cmd::diff_regex);

	       $test->run(stdout => <<_EOF_, stderr => _EOF_);
	       An expected (STDOUT|standard output) line\.
	       _EOF_
	       One or more expected (STDERR|error output) lines,
	       which may contain (regexes|regular expressions)\.
	       _EOF_

       "subdir"
	   Creates one or more subdirectories in the temporary working
	   directory.  Exits NO	RESULT if the number of	subdirectories
	   actually created does not match the number expected.	 For
	   compatibility with its superclass method, returns the number	of
	   subdirectories actually created.

       "read"
	   Reads the contents of a file, depositing the	contents in the
	   destination referred	to by the first	argument (a scalar or array
	   reference).	If the file name is not	an absolute path name, it is
	   relative to the temporary working directory.	 Exits NO RESULT if
	   the file could not be read for any reason.  For compatibility with
	   its superclass method, returns TRUE on success.

       "write"
	   Writes a file with the specified contents.  If the file name	is not
	   an absolute path name, it is	relative to the	temporary working
	   directory.  Exits NO	RESULT if there	were any errors	writing	the
	   file.  For compatibility with its superclass	method,	returns	TRUE
	   on success.

	       $test->write('file', <<_EOF_);
	       contents	of the file
	       _EOF_

       "file_matches"
	   Matches the contents	of the specified file (first argument) against
	   the expected	contents.  The expected	contents are an	array of lines
	   or a	scalar which will be split on newlines.	 By default, each
	   expected line must match exactly its	corresponding line in the
	   file:

	       $test->file_matches('file', <<_EOF_);
	       Line #1.
	       Line #2.
	       _EOF_

	   Tests that require regular expression matches should	be executed
	   using a test	environment that calls the "match_sub" method as
	   follows:

	       $test->match_sub(\&Test::Cmd::diff_regex);

	       $test->file_matches('file', <<_EOF_);
	       The (1st|first) line\.
	       The (2nd|second)	line\.
	       _EOF_

       "must_exist"
	   Ensures that	the specified files must exist.	 Files may be
	   specified as	an array reference of directory	components, in which
	   case	the pathname will be constructed by concatenating them.	 Exits
	   FAILED if any of the	files does not exist.

       "must_not_exist"
	   Ensures that	the specified files must not exist.  Files may be
	   specified as	an array reference of directory	components, in which
	   case	the pathname will be constructed by concatenating them.	 Exits
	   FAILED if any of the	files exists.

       "copy"
	   Copies a file from the source (first	argument) to the destination
	   (second argument).  Exits NO	RESULT if the file could not be	copied
	   for any reason.

       "chmod"
	   Changes the permissions of a	list of	files to the specified mode
	   (first argument).  Exits NO RESULT if any file could	not be changed
	   for any reason.

       "sleep"
	   Sleeps at least the specified number	of seconds.  If	no number is
	   specified, sleeps at	least a	minimum	number of seconds necessary to
	   advance file	time stamps on the current system.  Sleeping more
	   seconds is all right.  Exits	NO RESULT if the time slept was	less
	   than	specified.

       "touch"
	   Updates the access and modification times of	the specified files.
	   Exits NO RESULT if any file could not be modified for any reason.

       "unlink"
	   Removes the specified files.	 Exits NO RESULT if any	file could not
	   be removed for any reason.

ENVIRONMENT
       The "Test::Cmd::Common" module also uses	the "PRESERVE",
       "PRESERVE_FAIL",	"PRESERVE_NO_RESULT", and "PRESERVE_PASS" environment
       variables from the Test::Cmd module.  See the Test::Cmd documentation
       for details.

SEE ALSO
       perl(1),	Test::Cmd.

       The most	involved example of using the "Test::Cmd::Common" module to
       test a real-world application is	the "cons-test"	testing	suite for the
       Cons software construction utility.  The	suite sub-classes
       "Test::Cmd::Common" to provide common, application-specific
       infrastructure across a large number of end-to-end application tests.
       The suite, and other information	about Cons, is available at:

	       http://www.dsmit.com/cons

AUTHOR
       Steven Knight, knight@baldmt.com

ACKNOWLEDGEMENTS
       Thanks to Johan Holmberg	for asking the question	that led to the
       creation	of this	package.

       The general idea	of testing commands in this way, as well as the	test
       reporting of the	"pass",	"fail" and "no_result" methods,	come from the
       testing framework invented by Peter Miller for his Aegis	project	change
       supervisor.  Aegis is an	excellent bit of work which integrates
       creation	and execution of regression tests into the software
       development process.  Information about Aegis is	available at:

	       http://www.tip.net.au/~millerp/aegis.html

perl v5.32.1			  2015-10-25		  Test::Cmd::Common(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ENVIRONMENT | SEE ALSO | AUTHOR | ACKNOWLEDGEMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Cmd::Common&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help