---
name: "Test::Script::Run"
section: "3pm"
platform: "linux"
package: "libtest-script-run-perl"
version: "0.08-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::Script::Run"
---

# Test::Script::Run(3pm)

test scripts with run

## NAME

Test::Script::Run - test scripts with run

## SYNOPSIS

```
    use Test::Script::Run;
    # customized names of bin dirs, default is qw/bin sbin script ./;
    @Test::Script::Run::BIN_DIRS = qw/bin/;
    run_ok( 'app_name', [ app's args ], 'you_app runs ok' );
    my ( $return, $stdout, $stderr ) = run_script( 'app_name', [ app's args ] );
    run_output_matches(
        'app_name', [app's args],
        [ 'out line 1', 'out line 2' ],
        [ 'err line 1', 'err line 2' ],
        'run_output_matches'
    );
    run_output_matches_unordered(
        'app_name', [ app's args ],
        [ 'out line 2', 'out line 1' ],
        [ 'err line 2', 'err line 1' ],
        'run_output_matches_unordered'
    );
```

## DESCRIPTION

This module exports some subs to help test and run scripts in your dist's  script directory( bin, sbin, script, etc ), if the script path is not absolute.

Nearly all the essential code is stolen from Prophet::Test, we think subs like those should live below `"Test::"` namespace, that's why we packed them and created this module.

## FUNCTIONS

### run\_script($script, $args, $stdout, $stderr)

Runs the script `$script` as a perl script, setting the `@INC` to the same as our caller.

`$script` is the name of the script to be run (such as 'prophet'). `$args` is a reference to an array of arguments to pass to the script. `$stdout` and `$stderr` are both optional; if passed in, they will be passed to IPC::Run3's run3 subroutine as its `$stdout` and `$stderr` args.  Otherwise, this subroutine will create scalar references to pass to run3 instead (which are treated as strings for STDOUT/STDERR to be written to).

Returns run3's return value and, if no `$stdout` and `$stderr` were passed in, the STDOUT and STDERR of the script that was run.

### run\_ok($script, $args, $msg)

Runs the script, checking that it didn't error out.

`$script` is the name of the script to be run (e.g. 'prophet'). `$args` is an optional reference to an array of arguments to pass to the script when it is run. `$msg` is an optional message to print with the test. If `$args` is not specified, you can still pass in a `$msg`.

Returns nothing of interest.

### run\_not\_ok($script, $args, $msg)

opposite of run\_ok

### get\_perl\_cmd($script, @ARGS)

Returns a list suitable for passing to `"system"`, `"exec"`, etc. If you pass `$script` then we will search upwards for it in `@BIN_DIRS`

### is\_script\_output($scriptname \\@args, \\@stdout\_match, \\@stderr\_match, $msg)

Runs `$scriptname`, checking to see that its output matches.

`$args` is an array reference of args to pass to the script. `$stdout_match` and `$stderr_match` are references to arrays of expected lines. `$msg` is a string message to display with the test. `$stderr_match` and `$msg` are optional. (As is `$stdout_match` if for some reason you expect your script to have no output at all. But that would be silly, wouldn't it?)

Allows regex matches as well as string equality (lines in `$stdout_match` and `$stderr_match` may be Regexp objects).

### run\_output\_matches($script, $args, $exp\_stdout, $exp\_stderr, $msg)

A wrapper around is\_script\_output that also checks to make sure the test runs without throwing an exception.

### run\_output\_matches\_unordered($script, $args, $exp\_stdout, $exp\_stderr, $msg)

This subroutine has exactly the same functionality as run\_output\_matches, but doesn't impose a line ordering when comparing the expected and received outputs.

### last\_script\_stdout

return last script's stdout

### last\_script\_stderr

return last script's stderr

### last\_script\_exit\_code

return last script's exit code

## DEPENDENCIES

Test::More, Test::Exception, IPC::Run3, File::Basename, File::Spec

## BUGS AND LIMITATIONS

No bugs have been reported.

## AUTHOR

sunnavy \<sunnavy@bestpractical.com\>

## LICENCE AND COPYRIGHT

Copyright 2009-2013 Best Practical Solutions.

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