How to get `"#!/opt/homebrew/bin/bats"` to work as expected?

Question

After installing https://github.com/bats-core/bats-core via brew install bats-core in Sonoma, I created a bats bash script.

When the first line is #!/usr/bin/env bats, it runs fine.

But when the first line is #!/opt/homebrew/bin/bats, it errors with @test: command not found. Strangely, running /opt/homebrew/bin/bats example.bats runs fine.

How do I go about getting #!/opt/homebrew/bin/bats to work the same as when explicitly using /opt/homebrew/bin/bats on the command line?

Answer 1

bats is a shell script, but shebangs (#!) can only point to binaries, not to shell scripts. The reason for this is that the execve() system call (which reads a file to be executed) doesn't handle indirect execution, it either expects a binary or a file starting with #! /path/to/binary.

This makes #!/usr/bin/env bats the only way to make these scripts work.

---

From execve(2):

execve() transforms the calling process into a new process.  The new process is
constructed from an ordinary file, whose name is pointed to by path, called the
new process file.  This file is either an executable object file, or a file of
data for an interpreter.  An executable object file consists of an identifying
header, followed by pages of data representing the initial program (text) and
initialized data pages.  Additional pages may be specified by the header to be 
initialized with zero data;  see a.out(5).

An interpreter file begins with a line of the form:

    #! interpreter [arg ...]

When an interpreter file is execve()'d, the system runs the specified interpreter.
If any optional args are specified, they become the first (second, ...) argument
to the interpreter. The name of the originally execve()'d file becomes the
subsequent argument; otherwise, the name of the originally execve()'d file is
the first argument.  The original arguments to the invocation of the interpreter
are shifted over to become the final arguments. The zeroth argument, normally the
name of the execve()'d file, is left unchanged.