# Util

Various utilities to aid with testing.

{.starlark-object}
## force_exec_config

{.starlark-signature}
force_exec_config([name](#force_exec_config_name),
[tools](#force_exec_config_tools)=[])

Rule to force arbitrary targets to `cfg=exec` so they can be tested when used as tools.

{#force_exec_config_attributes}
**ATTRIBUTES** [¶](#force_exec_config_attributes){.headerlink}

:[name[¶](#force_exec_config_name){.headerlink}]{.span}: []{#force_exec_config_name}
  _(required [Name][target-name])_
  A unique name for this target.

:[tools[¶](#force_exec_config_tools){.headerlink}]{.span}: []{#force_exec_config_tools}
  _(optional list of [label][attr-label]s, default `[]`)_
  A list of tools to force into the exec config



{.starlark-object}
## util.force_exec_config

{.starlark-signature}
util.force_exec_config([name](#util_force_exec_config_name),
[tools](#util_force_exec_config_tools)=[])

Rule to force arbitrary targets to `cfg=exec` so they can be tested when used as tools.

{#util_force_exec_config_attributes}
**ATTRIBUTES** [¶](#util_force_exec_config_attributes){.headerlink}

:[name[¶](#util_force_exec_config_name){.headerlink}]{.span}: []{#util_force_exec_config_name}
  _(required [Name][target-name])_
  A unique name for this target.

:[tools[¶](#util_force_exec_config_tools){.headerlink}]{.span}: []{#util_force_exec_config_tools}
  _(optional list of [label][attr-label]s, default `[]`)_
  A list of tools to force into the exec config



{.starlark-object}
## TestingAspectInfo

{.starlark-signature}
TestingAspectInfo([attrs](#testingaspectinfo_attrs),
[actions](#testingaspectinfo_actions),
[vars](#testingaspectinfo_vars),
[bin_path](#testingaspectinfo_bin_path),
[required_aspects](#testingaspectinfo_required_aspects))

Details about a target-under-test useful for testing.

**FIELDS** [¶](#testingaspectinfo_fields){.headerlink}

:[attrs[¶](#testingaspectinfo_attrs){.headerlink}]{.span}: []{#testingaspectinfo_attrs}
  The raw attributes of the target under test.
:[actions[¶](#testingaspectinfo_actions){.headerlink}]{.span}: []{#testingaspectinfo_actions}
  The actions registered for the target under test.
:[vars[¶](#testingaspectinfo_vars){.headerlink}]{.span}: []{#testingaspectinfo_vars}
  The var dict (ctx.var) for the target under text.
:[bin_path[¶](#testingaspectinfo_bin_path){.headerlink}]{.span}: []{#testingaspectinfo_bin_path}
  str; the ctx.bin_dir.path value (aka execroot).
:[required_aspects[¶](#testingaspectinfo_required_aspects){.headerlink}]{.span}: []{#testingaspectinfo_required_aspects}
  list[str]: aspects applied over this target


{.starlark-object}
## empty_file

{.starlark-signature}
empty_file([name](#empty_file_name))

Generates an empty file and returns the target name for it.

{#empty_file_parameters}
**PARAMETERS** [¶](#empty_file_parameters){.headerlink}

{.params-box}
:[name[¶](#empty_file_name){.headerlink}]{.span}: []{#empty_file_name}
  str, name of the generated output file.

{#empty_file_returns}
RETURNS [¶](#empty_file_returns){.headerlink}
: str, the name of the generated output.


{.starlark-object}
## get_target_actions

{.starlark-signature}
get_target_actions([env](#get_target_actions_env))



{#get_target_actions_parameters}
**PARAMETERS** [¶](#get_target_actions_parameters){.headerlink}

{.params-box}
:[env[¶](#get_target_actions_env){.headerlink}]{.span}: []{#get_target_actions_env}
  _undocumented_


{.starlark-object}
## get_target_attrs

{.starlark-signature}
get_target_attrs([env](#get_target_attrs_env))



{#get_target_attrs_parameters}
**PARAMETERS** [¶](#get_target_attrs_parameters){.headerlink}

{.params-box}
:[env[¶](#get_target_attrs_env){.headerlink}]{.span}: []{#get_target_attrs_env}
  _undocumented_


{.starlark-object}
## helper_target

{.starlark-signature}
helper_target([rule](#helper_target_rule),
[kwargs](#helper_target_kwargs))

Define a target only used as a Starlark test input.

This is useful for e.g. analysis tests, which have to setup a small
graph of targets that should only be built via the test (e.g. they
may require config settings the test sets). Tags are added to
hide the target from `:all`, `/...`, TAP, etc.


{#helper_target_parameters}
**PARAMETERS** [¶](#helper_target_parameters){.headerlink}

{.params-box}
:[rule[¶](#helper_target_rule){.headerlink}]{.span}: []{#helper_target_rule}
  rule-like function.
:[kwargs[¶](#helper_target_kwargs){.headerlink}]{.span}: []{#helper_target_kwargs}
  Any kwargs to pass to `rule`. Additional tags will
  be added to hide the target.


{.starlark-object}
## is_file

{.starlark-signature}
is_file([obj](#is_file_obj))

Tells if an object is a File object.

{#is_file_parameters}
**PARAMETERS** [¶](#is_file_parameters){.headerlink}

{.params-box}
:[obj[¶](#is_file_obj){.headerlink}]{.span}: []{#is_file_obj}
  _undocumented_


{.starlark-object}
## is_runfiles

{.starlark-signature}
is_runfiles([obj](#is_runfiles_obj))

Tells if an object is a runfiles object.

{#is_runfiles_parameters}
**PARAMETERS** [¶](#is_runfiles_parameters){.headerlink}

{.params-box}
:[obj[¶](#is_runfiles_obj){.headerlink}]{.span}: []{#is_runfiles_obj}
  _undocumented_


{.starlark-object}
## merge_kwargs

{.starlark-signature}
merge_kwargs([kwargs](#merge_kwargs_kwargs))

Merges multiple dicts of kwargs.

This is similar to dict.update except:
    * If a key's value is a list, it'll be concatenated to any existing value.
    * An error is raised when the same non-list key occurs more than once.


{#merge_kwargs_parameters}
**PARAMETERS** [¶](#merge_kwargs_parameters){.headerlink}

{.params-box}
:[kwargs[¶](#merge_kwargs_kwargs){.headerlink}]{.span}: []{#merge_kwargs_kwargs}
  kwarg arg dicts to merge

{#merge_kwargs_returns}
RETURNS [¶](#merge_kwargs_returns){.headerlink}
: dict of the merged kwarg dics.


{.starlark-object}
## runfiles_map

{.starlark-signature}
runfiles_map([workspace_name](#runfiles_map_workspace_name),
[runfiles](#runfiles_map_runfiles))

Convert runfiles to a path->file mapping.

This approximates how Bazel materializes the runfiles on the file
system.


{#runfiles_map_parameters}
**PARAMETERS** [¶](#runfiles_map_parameters){.headerlink}

{.params-box}
:[workspace_name[¶](#runfiles_map_workspace_name){.headerlink}]{.span}: []{#runfiles_map_workspace_name}
  str; the workspace the runfiles belong to.
:[runfiles[¶](#runfiles_map_runfiles){.headerlink}]{.span}: []{#runfiles_map_runfiles}
  runfiles; the runfiles to convert to a map.

{#runfiles_map_returns}
RETURNS [¶](#runfiles_map_returns){.headerlink}
: `dict[str, optional File]` that maps the path under the runfiles root
    to it's backing file. The file may be None if the path came
    from `runfiles.empty_filenames`.


{.starlark-object}
## runfiles_paths

{.starlark-signature}
runfiles_paths([workspace_name](#runfiles_paths_workspace_name),
[runfiles](#runfiles_paths_runfiles))

Returns the root-relative short paths for the files in runfiles.

{#runfiles_paths_parameters}
**PARAMETERS** [¶](#runfiles_paths_parameters){.headerlink}

{.params-box}
:[workspace_name[¶](#runfiles_paths_workspace_name){.headerlink}]{.span}: []{#runfiles_paths_workspace_name}
  str, the workspace name (`ctx.workspace_name`).
:[runfiles[¶](#runfiles_paths_runfiles){.headerlink}]{.span}: []{#runfiles_paths_runfiles}
  runfiles, the runfiles to convert to short paths.

{#runfiles_paths_returns}
RETURNS [¶](#runfiles_paths_returns){.headerlink}
: list of short paths but runfiles root-relative. e.g.
    'myworkspace/foo/bar.py'.


{.starlark-object}
## short_paths

{.starlark-signature}
short_paths([files_depset](#short_paths_files_depset))

Returns the `short_path` paths for a depset of files.

{#short_paths_parameters}
**PARAMETERS** [¶](#short_paths_parameters){.headerlink}

{.params-box}
:[files_depset[¶](#short_paths_files_depset){.headerlink}]{.span}: []{#short_paths_files_depset}
  _undocumented_


{.starlark-object}
## skip_test

{.starlark-signature}
skip_test([name](#skip_test_name))

Defines a test target that is always skipped.

This is useful for tests that should be skipped if some condition,
determinable during the loading phase, isn't met. The resulting target will
show up as "SKIPPED" in the output.

If possible, prefer to use `target_compatible_with` to mark tests as
incompatible. This avoids confusing behavior where the type of a target
varies depending on loading-phase behavior.


{#skip_test_parameters}
**PARAMETERS** [¶](#skip_test_parameters){.headerlink}

{.params-box}
:[name[¶](#skip_test_name){.headerlink}]{.span}: []{#skip_test_name}
  The name of the target.


{.starlark-object}
## util.empty_file

{.starlark-signature}
util.empty_file([name](#util_empty_file_name))

Generates an empty file and returns the target name for it.

{#util_empty_file_parameters}
**PARAMETERS** [¶](#util_empty_file_parameters){.headerlink}

{.params-box}
:[name[¶](#util_empty_file_name){.headerlink}]{.span}: []{#util_empty_file_name}
  str, name of the generated output file.

{#util_empty_file_returns}
RETURNS [¶](#util_empty_file_returns){.headerlink}
: str, the name of the generated output.


{.starlark-object}
## util.helper_target

{.starlark-signature}
util.helper_target([rule](#util_helper_target_rule),
[kwargs](#util_helper_target_kwargs))

Define a target only used as a Starlark test input.

This is useful for e.g. analysis tests, which have to setup a small
graph of targets that should only be built via the test (e.g. they
may require config settings the test sets). Tags are added to
hide the target from `:all`, `/...`, TAP, etc.


{#util_helper_target_parameters}
**PARAMETERS** [¶](#util_helper_target_parameters){.headerlink}

{.params-box}
:[rule[¶](#util_helper_target_rule){.headerlink}]{.span}: []{#util_helper_target_rule}
  rule-like function.
:[kwargs[¶](#util_helper_target_kwargs){.headerlink}]{.span}: []{#util_helper_target_kwargs}
  Any kwargs to pass to `rule`. Additional tags will
  be added to hide the target.


{.starlark-object}
## util.make_testing_aspect

{.starlark-signature}
util.make_testing_aspect([aspects](#util_make_testing_aspect_aspects)=[])

Makes a testing_aspect

Use when you need to test actions created by aspect. Pass
the returned aspect to analysis_test as `testing_aspect`.


{#util_make_testing_aspect_parameters}
**PARAMETERS** [¶](#util_make_testing_aspect_parameters){.headerlink}

{.params-box}
:[aspects[¶](#util_make_testing_aspect_aspects){.headerlink}]{.span}: []{#util_make_testing_aspect_aspects}
(_default `[]`_)   a list of aspects to apply testing aspect over.

{#util_make_testing_aspect_returns}
RETURNS [¶](#util_make_testing_aspect_returns){.headerlink}
: custom testing aspect


{.starlark-object}
## util.merge_kwargs

{.starlark-signature}
util.merge_kwargs([kwargs](#util_merge_kwargs_kwargs))

Merges multiple dicts of kwargs.

This is similar to dict.update except:
    * If a key's value is a list, it'll be concatenated to any existing value.
    * An error is raised when the same non-list key occurs more than once.


{#util_merge_kwargs_parameters}
**PARAMETERS** [¶](#util_merge_kwargs_parameters){.headerlink}

{.params-box}
:[kwargs[¶](#util_merge_kwargs_kwargs){.headerlink}]{.span}: []{#util_merge_kwargs_kwargs}
  kwarg arg dicts to merge

{#util_merge_kwargs_returns}
RETURNS [¶](#util_merge_kwargs_returns){.headerlink}
: dict of the merged kwarg dics.


{.starlark-object}
## util.runfiles_map

{.starlark-signature}
util.runfiles_map([workspace_name](#util_runfiles_map_workspace_name),
[runfiles](#util_runfiles_map_runfiles))

Convert runfiles to a path->file mapping.

This approximates how Bazel materializes the runfiles on the file
system.


{#util_runfiles_map_parameters}
**PARAMETERS** [¶](#util_runfiles_map_parameters){.headerlink}

{.params-box}
:[workspace_name[¶](#util_runfiles_map_workspace_name){.headerlink}]{.span}: []{#util_runfiles_map_workspace_name}
  str; the workspace the runfiles belong to.
:[runfiles[¶](#util_runfiles_map_runfiles){.headerlink}]{.span}: []{#util_runfiles_map_runfiles}
  runfiles; the runfiles to convert to a map.

{#util_runfiles_map_returns}
RETURNS [¶](#util_runfiles_map_returns){.headerlink}
: `dict[str, optional File]` that maps the path under the runfiles root
    to it's backing file. The file may be None if the path came
    from `runfiles.empty_filenames`.


{.starlark-object}
## util.runfiles_paths

{.starlark-signature}
util.runfiles_paths([workspace_name](#util_runfiles_paths_workspace_name),
[runfiles](#util_runfiles_paths_runfiles))

Returns the root-relative short paths for the files in runfiles.

{#util_runfiles_paths_parameters}
**PARAMETERS** [¶](#util_runfiles_paths_parameters){.headerlink}

{.params-box}
:[workspace_name[¶](#util_runfiles_paths_workspace_name){.headerlink}]{.span}: []{#util_runfiles_paths_workspace_name}
  str, the workspace name (`ctx.workspace_name`).
:[runfiles[¶](#util_runfiles_paths_runfiles){.headerlink}]{.span}: []{#util_runfiles_paths_runfiles}
  runfiles, the runfiles to convert to short paths.

{#util_runfiles_paths_returns}
RETURNS [¶](#util_runfiles_paths_returns){.headerlink}
: list of short paths but runfiles root-relative. e.g.
    'myworkspace/foo/bar.py'.


{.starlark-object}
## util.short_paths

{.starlark-signature}
util.short_paths([files_depset](#util_short_paths_files_depset))

Returns the `short_path` paths for a depset of files.

{#util_short_paths_parameters}
**PARAMETERS** [¶](#util_short_paths_parameters){.headerlink}

{.params-box}
:[files_depset[¶](#util_short_paths_files_depset){.headerlink}]{.span}: []{#util_short_paths_files_depset}
  _undocumented_


{.starlark-object}
## util.skip_test

{.starlark-signature}
util.skip_test([name](#util_skip_test_name))

Defines a test target that is always skipped.

This is useful for tests that should be skipped if some condition,
determinable during the loading phase, isn't met. The resulting target will
show up as "SKIPPED" in the output.

If possible, prefer to use `target_compatible_with` to mark tests as
incompatible. This avoids confusing behavior where the type of a target
varies depending on loading-phase behavior.


{#util_skip_test_parameters}
**PARAMETERS** [¶](#util_skip_test_parameters){.headerlink}

{.params-box}
:[name[¶](#util_skip_test_name){.headerlink}]{.span}: []{#util_skip_test_name}
  The name of the target.


<a id="testing_aspect"></a>

## testing_aspect

<pre>
load("@rules_testing//lib:util.bzl", "testing_aspect")

testing_aspect()
</pre>



**ASPECT ATTRIBUTES**



**ATTRIBUTES**



<a id="util.testing_aspect"></a>

## util.testing_aspect

<pre>
load("@rules_testing//lib:util.bzl", "util")

util.testing_aspect()
</pre>



**ASPECT ATTRIBUTES**



**ATTRIBUTES**



[`Action`]: https://bazel.build/rules/lib/Action
[`ActionSubject`]: /api/action_subject
[`bool`]: https://bazel.build/rules/lib/bool
[`BoolSubject`]: /api/bool_subject
[`CollectionSubject`]: /api/collection_subject
[`depset`]: https://bazel.build/rules/lib/depset
[`DepsetFileSubject`]: /api/depset_file_subject
[`dict`]: https://bazel.build/rules/lib/dict
[`DictSubject`]: /api/dict_subject
[`Expect`]: /api/expect
[`ExpectMeta`]: /api/expect_meta
[`File`]: https://bazel.build/rules/lib/File
[`FileSubject`]: /api/file_subject
[`format_str`]: /api/expect_meta.html#expectmeta-format-str
[`IntSubject`]: /api/int_subject
[`Label`]: https://bazel.build/rules/lib/Label
[`LabelSubject`]: /api/label_subject
[`list`]: https://bazel.build/rules/lib/list
[`Ordered`]: /api/ordered
[`RunfilesSubject`]: /api/runfiles_subject
[`str`]: https://bazel.build/rules/lib/string
[`struct`]: https://bazel.build/rules/lib/builtins/struct
[`StrSubject`]: /api/str_subject
[`StructSubject`]: /api/struct_subject
[`Target`]: https://bazel.build/rules/lib/Target
[`TargetSubject`]: /api/target_subject
[target-name]: https://bazel.build/concepts/labels#target-names
[attr-label]: https://bazel.build/concepts/labels