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

FreeBSD Manual Pages

  
 
  

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

NAME
       Test::Command - Test routines for external commands

VERSION
       Version 0.11

SYNOPSIS
       Test the	exit status, signal, STDOUT or STDERR of an external command.

	  use Test::Command tests => 11;

	  ## testing exit status

	  my $cmd = 'true';

	  exit_is_num($cmd, 0);
	  exit_cmp_ok($cmd, '<', 10);

	  $cmd = 'false';

	  exit_isnt_num($cmd, 0);

	  ## testing terminating signal

	  $cmd = 'true';

	  signal_is_num($cmd, 0);

	  ## testing STDOUT

	  $cmd	       = [qw/ echo out /];  ## run as "system @$cmd"
	  my $file_exp = 'echo_stdout.exp';

	  stdout_is_eq($cmd, "out\n");
	  stdout_isnt_eq($cmd, "out");
	  stdout_is_file($cmd, $file_exp);

	  ## testing STDERR

	  $cmd = 'echo err >&2';

	  stderr_like($cmd, /err/);
	  stderr_unlike($cmd, /rre/);
	  stderr_cmp_ok($cmd, 'eq', "err\n");

	  ## run-once-test-many-OO-style
	  ## the first test lazily runs	command
	  ## the second	test uses cached results

	  my $echo_test	= Test::Command->new( cmd => 'echo out'	);

	  $echo_test->exit_is_num(0);
	  $echo_test->signal_is_num(0);
	  $echo_test->stdout_is_eq("out\n");

	  ## force a re-run of the command

	  $echo_test->run;

	  ## arbitrary results inspection

	  is( $echo_test->exit_value, 0,	 'echo exit' );
	  is( $echo_test->signal_value,	undef,	 'echo signal' );
	  is( $echo_test->stdout_value,	"out\n", 'echo stdout' );
	  is( $echo_test->stderr_value,	'',	 'echo stderr' );
	  is( -s $echo_test->stdout_file, 4,	 'echo stdout file size' );
	  is( -s $echo_test->stderr_file, 0,	 'echo stderr file size' );

DESCRIPTION
       "Test::Command" intends to bridge the gap between the well tested
       functions and objects you choose	and their usage	in your	programs. By
       examining the exit status, terminating signal, STDOUT and STDERR	of
       your program you	can determine if it is behaving	as expected.

       This includes testing the various combinations and permutations of
       options and arguments as	well as	the interactions between the various
       functions and objects that make up your program.

       The various test	functions below	can accept either a command string or
       an array	reference for the first	argument. If the command is expressed
       as a string it is passed	to "system" as is. If the command is expressed
       as an array reference it	is dereferenced	and passed to "system" as a
       list. See '"perldoc -f system"' for how these may differ.

       The final argument for the test functions, $name, is optional. By
       default the $name is a concatenation of the test	function name, the
       command string and the expected value. This construction	is generally
       sufficient for identifying a failing test, but you may always specify
       your own	$name if desired.

       Any of the test functions can be	used as	instance methods on a
       "Test::Command" object. This is done by dropping	the initial $cmd
       argument	and instead using arrow	notation.

       All of the following "exit_is_num" calls	are equivalent.

	  exit_is_num('true', 0);
	  exit_is_num('true', 0, 'exit_is_num: true, 0');
	  exit_is_num(['true'],	0);
	  exit_is_num(['true'],	0, 'exit_is_num: true, 0');

	  my $cmd = Test::Command->new(	cmd => 'true' );

	  exit_is_num($cmd, 0);
	  exit_is_num($cmd, 0, 'exit_is_num: true, 0');
	  $cmd->exit_is_num(0);
	  $cmd->exit_is_num(0, 'exit_is_num: true, 0');

	  $cmd = Test::Command->new( cmd => ['true'] );

	  exit_is_num($cmd, 0);
	  exit_is_num($cmd, 0, 'exit_is_num: true, 0');
	  $cmd->exit_is_num(0);
	  $cmd->exit_is_num(0, 'exit_is_num: true, 0');

EXPORT
       All of the test functions mentioned below are exported by default.

METHODS
   new
	  my $test_cmd_obj = Test::Command->new( cmd =>	$cmd )

       This constructor	creates	and returns a "Test::Command" object. Use this
       to test multiple	aspects	of a single command execution while avoiding
       repeatedly running commands which are slow or resource intensive.

       The "cmd" parameter can accept either a string or an array reference
       for its value. The value	is dereferenced	if necessary and passed
       directly	to the "system"	builtin.

   run
	  $test_cmd_obj->run;

       This instance method forces the execution of the	command	specified by
       the invocant.

       You only	need to	call this when you wish	to re-run a command since the
       first test method invoked will lazily execute the command if necessary.
       However,	if the state of	your inputs has	changed	and you	wish to	re-run
       the command, you	may do so by invoking this method at any point between
       your tests.

FUNCTIONS
   Testing Exit	Status
       The test	routines below compare against the exit	status of the executed
       command right shifted by	8 (that	is, "$?	>> 8").

       exit_value

	  exit_value($cmd)

       Return the exit status of the command. Useful for performing arbitrary
       tests not covered by this module.

       exit_is_num

	  exit_is_num($cmd, $exp_num, $name)

       If the exit status of the command is numerically	equal to the expected
       number, this passes. Otherwise it fails.

       exit_isnt_num

	  exit_isnt_num($cmd, $unexp_num, $name)

       If the exit status of the command is not	numerically equal to the given
       number, this passes. Otherwise it fails.

       exit_cmp_ok

	  exit_cmp_ok($cmd, $op, $operand, $name)

       If the exit status of the command is compared with the given operand
       using the given operator, and that operation returns true, this passes.
       Otherwise it fails.

       exit_is_defined

	  exit_is_defined($cmd,	$name)

       If the exit status of the command is defined, this passes. Otherwise it
       fails. A	defined	exit status indicates that the command exited normally
       by calling exit() or running off	the end	of the program.

       exit_is_undef

	  exit_is_undef($cmd, $name)

       If the exit status of the command is not	defined, this passes.
       Otherwise it fails. An undefined	exit status indicates that the command
       likely exited due to a signal.

   Testing Terminating Signal
       The test	routines below compare against the lower 8 bits	of the exit
       status of the executed command.

       signal_value

	  signal_value($cmd)

       Return the signal code of the command. Useful for performing arbitrary
       tests not covered by this module.

       signal_is_num

	  signal_is_num($cmd, $exp_num,	$name)

       If the terminating signal of the	command	is numerically equal to	the
       expected	number,	this passes. Otherwise it fails.

       signal_isnt_num

	  signal_isnt_num($cmd,	$unexp_num, $name)

       If the terminating signal of the	command	is not numerically equal to
       the given number, this passes. Otherwise	it fails.

       signal_cmp_ok

	  signal_cmp_ok($cmd, $op, $operand, $name)

       If the terminating signal of the	command	is compared with the given
       operand using the given operator, and that operation returns true, this
       passes. Otherwise it fails.

       signal_is_defined

	  signal_is_defined($cmd, $name)

       If the terminating signal of the	command	is defined, this passes.
       Otherwise it fails. A defined signal indicates that the command likely
       exited due to a signal.

       signal_is_undef

	  signal_is_undef($cmd,	$name)

       If the terminating signal of the	command	is not defined,	this passes.
       Otherwise it fails. An undefined	signal indicates that the command
       exited normally by calling exit() or running off	the end	of the
       program.

   Testing STDOUT
       Except where specified, the test	routines below treat STDOUT as a
       single slurped string.

       stdout_value

	  stdout_value($cmd)

       Return the STDOUT of the	command. Useful	for performing arbitrary tests
       not covered by this module.

       stdout_file

	  stdout_file($cmd)

       Return the file name containing the STDOUT of the command. Useful for
       performing arbitrary tests not covered by this module.

       stdout_is_eq

	  stdout_is_eq($cmd, $exp_string, $name)

       If the STDOUT of	the command is equal (compared using "eq") to the
       expected	string,	then this passes. Otherwise it fails.

       stdout_isnt_eq

	  stdout_isnt_eq($cmd, $unexp_string, $name)

       If the STDOUT of	the command is not equal (compared using "eq") to the
       given string, this passes. Otherwise it fails.

       stdout_is_num

	  stdout_is_num($cmd, $exp_num,	$name)

       If the STDOUT of	the command is equal (compared using "==") to the
       expected	number,	then this passes. Otherwise it fails.

       stdout_isnt_num

	  stdout_isnt_num($cmd,	$unexp_num, $name)

       If the STDOUT of	the command is not equal (compared using "==") to the
       given number, this passes. Otherwise it fails.

       stdout_like

	  stdout_like($cmd, $exp_regex,	$name)

       If the STDOUT of	the command matches the	expected regular expression,
       this passes. Otherwise it fails.

       stdout_unlike

	  stdout_unlike($cmd, $unexp_regex, $name)

       If the STDOUT of	the command does not match the given regular
       expression, this	passes.	Otherwise it fails.

       stdout_cmp_ok

	  stdout_cmp_ok($cmd, $op, $operand, $name)

       If the STDOUT of	the command is compared	with the given operand using
       the given operator, and that operation returns true, this passes.
       Otherwise it fails.

       stdout_is_file

	  stdout_is_file($cmd, $exp_file, $name)

       If the STDOUT of	the command is equal (compared using "eq") to the
       contents	of the given file, then	this passes. Otherwise it fails. Note
       that this comparison is performed line by line, rather than slurping
       the entire file.

   Testing STDERR
       Except where specified, the test	routines below treat STDERR as a
       single slurped string.

       stderr_value

	  stderr_value($cmd)

       Return the STDERR of the	command. Useful	for performing arbitrary tests
       not covered by this module.

       stderr_file

	  stderr_file($cmd)

       Return the file name containing the STDERR of the command. Useful for
       performing arbitrary tests not covered by this module.

       stderr_is_eq

	  stderr_is_eq($cmd, $exp_string, $name)

       If the STDERR of	the command is equal (compared using "eq") to the
       expected	string,	then this passes. Otherwise it fails.

       stderr_isnt_eq

	  stderr_isnt_eq($cmd, $unexp_string, $name)

       If the STDERR of	the command is not equal (compared using "eq") to the
       given string, this passes. Otherwise it fails.

       stderr_is_num

	  stderr_is_num($cmd, $exp_num,	$name)

       If the STDERR of	the command is equal (compared using "==") to the
       expected	number,	then this passes. Otherwise it fails.

       stderr_isnt_num

	  stderr_isnt_num($cmd,	$unexp_num, $name)

       If the STDERR of	the command is not equal (compared using "==") to the
       given number, this passes. Otherwise it fails.

       stderr_like

	  stderr_like($cmd, $exp_regex,	$name)

       If the STDERR of	the command matches the	expected regular expression,
       this passes. Otherwise it fails.

       stderr_unlike

	  stderr_unlike($cmd, $unexp_regex, $name)

       If the STDERR of	the command does not match the given regular
       expression, this	passes.	Otherwise it fails.

       stderr_cmp_ok

	  stderr_cmp_ok($cmd, $op, $operand, $name)

       If the STDERR of	the command is compared	with the given operand using
       the given operator, and that operation returns true, this passes.
       Otherwise it fails.

       stderr_is_file

	  stderr_is_file($cmd, $exp_file, $name)

       If the STDERR of	the command is equal (compared using "eq") to the
       contents	of the given file, then	this passes. Otherwise it fails. Note
       that this comparison is performed line by line, rather than slurping
       the entire file.

AUTHOR
       Daniel B. Boorstein, "<danboo at	cpan.org>"

BUGS
       Please report any bugs or feature requests to "bug-test-command at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Command>.  I will
       be notified, and	then you'll automatically be notified of progress on
       your bug	as I make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc Test::Command

       You can also look for information at:

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/Test-Command>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/Test-Command>

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command>

       o   Search CPAN

	   <http://search.cpan.org/dist/Test-Command>

ACKNOWLEDGEMENTS
       Test::Builder by	Michael	Schwern	allowed	me to focus on the specifics
       related to testing system commands by making it easy to produce proper
       test output.

COPYRIGHT & LICENSE
       Copyright 2007 Daniel B.	Boorstein, all rights reserved.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

DEVELOPMENT IDEAS
       o  create a tool	that produces test scripts given a list	of commands to
	  run

       o  optionally save the temp files with STDOUT and STDERR	for user
	  debugging

       o  if user defines all options and sample arguments to basic command

	  o  create tool to enumerate all possible means of calling program

	  o  allow testing with	randomized/permuted/collapsed opts and args

       o  potential test functions:

	  o  time_lt($cmd, $seconds)

	  o  time_gt($cmd, $seconds)

	  o  stdout_line_custom($cmd, \&code)

	  o  stderr_line_custom($cmd, \&code)

SEE ALSO
       Test::Builder provides the testing methods used in this module.

       Test::Builder::Module is	the superclass of this module.

perl v5.24.1			  2013-04-29		      Test::Command(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | EXPORT | METHODS | FUNCTIONS | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE | DEVELOPMENT IDEAS | SEE ALSO

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

home | help