stabilize `experimental_test_shell_command` as `test_shell_command`

[tdyas]

Tasks to complete to stabilize experimental_test_shell_command as test_shell_command:

• Support capturing outputs as test "extra outputs."
  • experimental_test_shell_command should support capture of outputs (test reports, coverage, etc.) #21981
  • shell: support extra output files in experimental_test_shell_command #22002
• Support runnable_dependencies field. shell: support runnable_dependencies for experimental_test_shell_command #22003
• Update documentation to be current. For example, reflect how CHROOT is not actually set during executions.

[jcrobak]

As mentioned on slack

• If we add runnable_dependencies, then when should we use tools instead of runnable_dependencies? If we add runnable_dependencies, should we remove tools? Otherwise, it's a little confusing—I think tools is the only place in pants resources where we take binary names and not system_binary targets?
• I'm not able to get the $CHROOT variable working. I tried printenv CHROOT and echo "$CHROOT" in my command. both return nothing.
• {chroot} sort of works.
  • echo "chroot: {chroot}"
    • prints chroot: /private/var/folders/mm/n9m9_2sd77b4gqm1938rhx_m0000gn/T/pants-sandbox-q9sHP9
  • echo "chroot: {chroot}/foo":
    • prints chroot: foo

(I can put together a repro and file a separate issue later)

[tdyas]

I'm not able to get the $CHROOT variable working. I tried printenv CHROOT and echo "$CHROOT" in my command. both return nothing.

experimental_test_shell_command does not currently set CHROOT at all. run_shell_command apparently does set that var. You can probably just set extra_env_vars={"CHROOT": "{chroot}"}. The Pants rules do not set CHROOT for all process invocations in general, just when a specific rule using the process intrinsic explicitly calls for it like with run_shell_command.

[jcrobak]

@tdyas makes sense. Should we update the docs? they say that the variable is being set: https://www.pantsbuild.org/stable/reference/targets/experimental_test_shell_command

[tdyas]

@tdyas makes sense. Should we update the docs? they say that the variable is being set: https://www.pantsbuild.org/stable/reference/targets/experimental_test_shell_command

Yes we should. Added a task to update the documentation for this and more generally.

[tdyas]

Regarding the chroot substitution issues, that would not be specific to experimental_test_shell_command given {chroot} substitution is performed by the Rust-side process execution logic, so a reproduction will be very much appreciated!

[jcrobak]

Filed #22014 with a repro of the chroot issue I am seeing

[tdyas]

Stabilization PR: #22016