Skip to main content
Version: 2.24 (prerelease)

experimental_test_shell_command

Run a script as a test via the test goal, with all dependencies packaged/copied available in the chroot.

Example BUILD file:

experimental_test_shell_command(
    name="test",
    tools=["test"],
    command="test -r $CHROOT/some-data-file.txt",
    execution_dependencies=["src/project/files:data"],
)

The command may use either {chroot} on the command line, or the $CHROOT environment variable to get the root directory for where any dependencies are located.

In contrast to the run_shell_command, this target is intended to run shell commands as tests and will only run them via the test goal.

Backend: pants.backend.shell

command​

str
required

Shell command to execute.

The command is executed as 'bash -c <command>' by default. If you want to invoke a binary use exec -a $0 <binary> <args> as the command so that the binary gets the correct argv[0] set.

description​

str | None
default: None

A human-readable description of the target.

Use pants list --documented :: to see all targets with descriptions.

environment​

str | None
default: '__local__'

Specify which environment target to consume environment-sensitive options from.

Once environments are defined in [environments-preview].names, you can specify the environment for this target by its name. Any fields that are defined in that environment will override the values from options set by pants.toml, command line values, or environment variables.

You can specify multiple valid environments by using parametrize. If __local__ is specified, Pants will fall back to the local_environment defined for the current platform, or no environment if no such environment exists.

execution_dependencies​

Iterable[str] | None
default: None

The execution dependencies for this command.

Dependencies specified here are those required to make the command complete successfully (e.g. file inputs, packages compiled from other targets, etc), but NOT required to make the outputs of the command useful. Dependencies that are required to use the outputs produced by this command should be specified using the output_dependencies field.

If this field is specified, dependencies from output_dependencies will not be added to the execution sandbox.

See also output_dependencies and runnable_dependencies.

extra_env_vars​

Iterable[str] | None
default: None

Additional environment variables to provide to the process.

Entries are strings in the form ENV_VAR=value to use explicitly; or just ENV_VAR to copy the value of a variable in Pants's own environment.

log_output​

bool
default: False

Set to true if you want the output logged to the console.

path_env_modify​

'append' | 'off' | 'prepend' | None
default: 'prepend'

When executing the command of an adhoc_tool or shell_command target, Pants may augment the PATH environment variable with the location of any binary shims created for tools and for any runnable dependencies.

Modification of the PATH environment variable can be configured as follows: - prepend: Prepend the extra path components to any existing PATH value. - append: Append the extra path componenets to any existing PATH value. - off: Do not modify the existing PATH value.

skip_tests​

bool
default: False

If true, don't run this tests for target.

tags​

Iterable[str] | None
default: None

Arbitrary strings to describe a target.

For example, you may tag some test targets with 'integration_test' so that you could run pants --tag='integration_test' test :: to only run on targets with that tag.

timeout​

int | None
default: 30

Command execution timeout (in seconds).

tools​

Iterable[str] | None
default: ()

Specify required executable tools that might be used.

Only the tools explicitly provided will be available on the search PATH, and these tools must be found on the paths provided by [shell-setup].executable_search_paths (which defaults to the system PATH).

workdir​

str | None
default: '.'

Sets the working directory for the process.

Values are relative to the build root, except in the following cases:

  • . specifies the location of the BUILD file.
  • Values beginning with ./ are relative to the location of the BUILD file.
  • / or the empty string specifies the build root.
  • Values beginning with / are also relative to the build root.