Util¶

Various utilities to aid with testing.

force_exec_config¶

force_exec_config(name, tools=[])

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

ATTRIBUTES ¶

name¶:: (required Name) A unique name for this target.
tools¶:: (optional list of labels, default []) A list of tools to force into the exec config

¶

(name, tools=[])

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

ATTRIBUTES ¶

name¶:: (required Name) A unique name for this target.
tools¶:: (optional list of labels, default []) A list of tools to force into the exec config

TestingAspectInfo¶

TestingAspectInfo(attrs, actions, vars, bin_path)

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

FIELDS ¶

attrs¶:: The raw attributes of the target under test.
actions¶:: The actions registered for the target under test.
vars¶:: The var dict (ctx.var) for the target under text.
bin_path¶:: str; the ctx.bin_dir.path value (aka execroot).

empty_file¶

empty_file(name)

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

PARAMETERS ¶

name¶:: str, name of the generated output file.

RETURNS ¶: str, the name of the generated output.

get_target_actions¶

get_target_actions(env)

PARAMETERS ¶

env¶:: undocumented

get_target_attrs¶

get_target_attrs(env)

PARAMETERS ¶

env¶:: undocumented

helper_target¶

helper_target(rule, 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.

PARAMETERS ¶

rule¶:: rule-like function.
kwargs¶:: Any kwargs to pass to rule. Additional tags will be added to hide the target.

is_file¶

is_file(obj)

Tells if an object is a File object.

PARAMETERS ¶

obj¶:: undocumented

is_runfiles¶

is_runfiles(obj)

Tells if an object is a runfiles object.

PARAMETERS ¶

obj¶:: undocumented

merge_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.

PARAMETERS ¶

kwargs¶:: kwarg arg dicts to merge

RETURNS ¶: dict of the merged kwarg dics.

runfiles_map¶

runfiles_map(workspace_name, runfiles)

Convert runfiles to a path->file mapping.

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

PARAMETERS ¶

workspace_name¶:: str; the workspace the runfiles belong to.
runfiles¶:: runfiles; the runfiles to convert to a map.

RETURNS ¶: 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.

runfiles_paths¶

runfiles_paths(workspace_name, runfiles)

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

PARAMETERS ¶

workspace_name¶:: str, the workspace name (ctx.workspace_name).
runfiles¶:: runfiles, the runfiles to convert to short paths.

RETURNS ¶: list of short paths but runfiles root-relative. e.g. ‘myworkspace/foo/bar.py’.

short_paths¶

short_paths(files_depset)

Returns the short_path paths for a depset of files.

PARAMETERS ¶

files_depset¶:: undocumented

skip_test¶

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.

PARAMETERS ¶

name¶:: The name of the target.

util.empty_file¶

util.empty_file(name)

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

PARAMETERS ¶

name¶:: str, name of the generated output file.

RETURNS ¶: str, the name of the generated output.

util.helper_target¶

util.helper_target(rule, 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.

PARAMETERS ¶

rule¶:: rule-like function.
kwargs¶:: Any kwargs to pass to rule. Additional tags will be added to hide the target.

util.merge_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.

PARAMETERS ¶

kwargs¶:: kwarg arg dicts to merge

RETURNS ¶: dict of the merged kwarg dics.

util.runfiles_map¶

util.runfiles_map(workspace_name, runfiles)

Convert runfiles to a path->file mapping.

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

PARAMETERS ¶

workspace_name¶:: str; the workspace the runfiles belong to.
runfiles¶:: runfiles; the runfiles to convert to a map.

RETURNS ¶: 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.

util.runfiles_paths¶

util.runfiles_paths(workspace_name, runfiles)

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

PARAMETERS ¶

workspace_name¶:: str, the workspace name (ctx.workspace_name).
runfiles¶:: runfiles, the runfiles to convert to short paths.

RETURNS ¶: list of short paths but runfiles root-relative. e.g. ‘myworkspace/foo/bar.py’.

util.short_paths¶

util.short_paths(files_depset)

Returns the short_path paths for a depset of files.

PARAMETERS ¶

files_depset¶:: undocumented

util.skip_test¶

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.

PARAMETERS ¶

name¶:: The name of the target.

recursive_testing_aspect¶

recursive_testing_aspect(name)

ASPECT ATTRIBUTES

Name	Type
*	String

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required

testing_aspect¶

testing_aspect(name)

ASPECT ATTRIBUTES

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required