Document method for safely printing 'set -x' output in TAP mode

[robwiss]

Using set -x in TAP mode breaks bats scripts if the test fails. The cause of the failure is that the set -x debug output interleaves with the regular output and breaks bats' parsing for extraction of the failure reason.

This problem can be fixed without modifications to bats. Bash allows setting the file descriptor written to by set -x with the variable BASH_XTRACEFD. To get the set -x debug output visible within a TAP mode bats test, set BASH_XTRACEFD to file descriptor 3. For example:

test.bats

#!/usr/bin/env bats

@test "foo" {
  BASH_XTRACEFD=3
  set -x

  ls $HOME && 0
}

and execute this with

bats -t test.bats

Please document this somewhere, the technique is very useful for troubleshooting bats scripts.

[stefanlasiewski]

FYI, this project is no longer maintained. Please give it's successor a try:

https://github.com/bats-core/bats-core