The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Test-UnixExit-0.01
River stage one • 1 direct dependent • 2 total dependents
/ Test::UnixExit

NAME

Test::UnixExit - tests exit status words

SYNOPSIS

  #use Expect;
  #use Test::Cmd;
  #use Test::Most;
  use Test::UnixExit;

  # ... some call that sets $? here or $expect->exitstatus ...

  exit_is( $?, 0, "exited ok" );
  exit_is( $?, { code => 0, signal => 2, iscore => 0 }, "SIGINT" );

DESCRIPTION

This module provides a means to check that the exit status word conforms to a particular pattern, including what signal and whether a core was generated; the simple <<$? > 8 == 0>>> test discards those last two points. This code is most useful when testing external commands via system, Test::Cmd, or Expect; perl code itself may instead be tested with other modules such as Test::Exit or Test::Trap.

Internally Test::Builder is used, so this module might best be paired with Test::Most (and is otherwise untested with other test modules).

FUNCTION

The one function is exported by default. Sorry about that.

exit_is status, expected-value, test-name

This function accepts a status (the 16-bit return value from the wait(2) call), an expected-value as either an 8-bit exit code or a hash reference with various fields set, and an optional name of the test. Whether or not the test passed is the return value.

The fields for the hash reference are:

    code   => 8-bit exit status number (WEXITSTATUS)
    iscore => 1 or 0 if a core file was created or not
    signal => what signal the process ate (WTERMSIG), if any

Unspecified fields default to 0, though will be checked against the provided status-word.

BUGS

Reporting Bugs

Please report any bugs or feature requests to bug-test-unixexit at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-UnixExit.

Patches might best be applied towards:

https://github.com/thrig/Test-UnixExit

Known Issues

The expected-value to exit_is is not much checked whether the inputs are sane, e.g. that code is an 8-bit number, etc. This may be a problem if this input is being generated by something that is buggy.

SEE ALSO

Test::Cmd, Expect - these provide means to check external commands, either by running the commands under a shell, or simulating a terminal environment. Good ways to obtain a $? to pass to this code, in other words.

Test::Exit, Test::Trap - these check that Perl code behaves in a particular way, and may be more suitable for testing code in a module over running a wrapper via the complication of a shell or virtual terminal.

wait(2) - note that shells are different from the system call in that the 16-bit status word is shoehorned into an 8-bit value available via the shell $? variable, which is the same name as the variable Perl stores the 16-bit status word in. This can and does cause confusion.

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) <jmates at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Jeremy Mates

This program is distributed under the (Revised) BSD License: http://www.opensource.org/licenses/BSD-3-Clause