Very interesting. I assume you need this in order to test the side effects of shell functions? Could you share a real test case that uses this technique?

Sure thing! Here's a not-entirely-contrived example:

function parse_opts() {
    while getopts ":dv" option; do
        case $option in
            d) DEBUG=1;;
            v) VERBOSE=1;;
            *) usage;;
        esac
    done
}

function usage() {
    exit 1
}

@test "ensure -v sets VERBOSE mode" {
    run parse_opts -v
    set_run_vars VERBOSE
    [ "$VERBOSE" -eq 1 ]
}

@test "ensure -d sets DEBUG mode" {
    run parse_opts -d
    set_run_vars DEBUG
    [ "$DEBUG" -eq 1 ]
}

I can understand the need for this but I don't like the proposed API nor the implementation in this PR. It seems contrived. I don't have a good alternative, though, but I'll come back if I get inspiration for how it might be handled better

I appreciate the feedback and will gladly welcome any improvements you may suggest!

For the example you've supplied, I'd suggest not using run at all, since you're not testing output or exit status:

@test "ensure -v sets VERBOSE mode" {
    parse_opts -v
    [ "$VERBOSE" -eq 1 ]
}

@test "ensure -d sets DEBUG mode" {
    parse_opts -d
    [ "$DEBUG" -eq 1 ]
}

And I would suggest using run to test the print-usage-and-exit behavior of invalid flags:

@test "invalid option prints usage" {
    run parse_opts -x
    [ "$status" -eq 1 ]
}

So, closing this for now—but please do reopen if you have a compelling case where the technique I've described won't work. (And thanks for the lovely patch.)

Fair enough. Here are my reasons for wanting to run such functions with run:

1. Temporary unsetting of the e flag. Without run, any failing line within the function under test will cause the whole test to fail. (This could be unset/set in the test, of course).
2. Better isolation from the rest of the test by use of a subshell. Only the requested variables are copied into the scope of the test.

In any case, I appreciate you taking the time to look at my pull request—and thanks for a great unit test framework!

@mislav I've changed the API in my fork so that my above example would now look like this:

@test "ensure -v sets VERBOSE mode" {
    run -v VERBOSE parse_opts -v
    [ "$VERBOSE" -eq 1 ]
}

@test "ensure -d sets DEBUG mode" {
    run -v DEBUG parse_opts -d
    [ "$DEBUG" -eq 1 ]
}

It also accepts multiple variables:

@test "run accepts multiple variables" {
    change_vars() {
        var1=1
        var2=2
        var3=3
    }

    run -v var1 -v var2 -v var3 change_vars

    [ "$var1" -eq 1 ]
    [ "$var2" -eq 2 ]
    [ "$var3" -eq 3 ]
}

I like this usage better because it doesn't introduce a new command. What do you think?

I use bats exclusively to test the outcome of running shell executables. Your use case is different than that. Sam was right when he said that run is not tailored to your use-case. You probably want to make your own helper function that clears and resets the -e flag.

Yes, the subshell is useful for isolation but it seems that you don't want to test in isolation here. If you wanted to, you wouldn't be interested in changes to global environment variables.