Skip to main content

python_test

name​

def name(
    *,
    name: str,
    default_target_platform: None | str = ...,
    target_compatible_with: list[str] = ...,
    compatible_with: list[str] = ...,
    exec_compatible_with: list[str] = ...,
    visibility: list[str] = ...,
    within_view: list[str] = ...,
    metadata: OpaqueMetadata = ...,
    tests: list[str] = ...,
    modifiers: OpaqueMetadata = ...,
    _apple_platforms: dict[str, str] = ...,
    _build_info: dict[str, typing.Any] = ...,
    _create_manifest_for_source_dir: str = ...,
    _cxx_hacks: str = ...,
    _cxx_toolchain: str = ...,
    _exec_os_type: str = ...,
    _inject_test_env: str = ...,
    _python_toolchain: str = ...,
    _remote_test_execution_toolchain: str = ...,
    _target_os_type: str = ...,
    _test_main: str = ...,
    _test_toolchain: str = ...,
    additional_coverage_targets: list[str] = ...,
    anonymous_link_groups: bool = ...,
    auto_link_groups: bool = ...,
    base_module: None | str = ...,
    binary_linker_flags: list[str] = ...,
    bolt_flags: list[str] = ...,
    bolt_profile: None | str = ...,
    build_args: list[str] = ...,
    compile: None | bool = ...,
    compiler_flags: list[str] = ...,
    constraint_overrides: list[str] = ...,
    contacts: list[str] = ...,
    coverage_instrumentation_compiler_flags: list[str] = ...,
    cuda_compile_style: str = ...,
    cxx_main: str = ...,
    cxx_runtime_type: None | str = ...,
    deduplicate_merged_link_roots: None | bool = ...,
    default_host_platform: None | str = ...,
    default_platform: None | str = ...,
    defaults: dict[str, str] = ...,
    deps: list[str] = ...,
    deps_query: None | str = ...,
    devirt_enabled: bool = ...,
    distributed_thinlto_partial_split_dwarf: bool = ...,
    dummy_omnibus: None | str = ...,
    enable_distributed_thinlto: bool = ...,
    env: dict[str, str] = ...,
    exclude_deps_from_merged_linking: bool = ...,
    executable_deps: list[str] = ...,
    executable_name: None | str = ...,
    exported_needs_coverage_instrumentation: bool = ...,
    extension: None | str = ...,
    fat_lto: bool = ...,
    focused_list_target: None | str = ...,
    frameworks: list[str] = ...,
    header_namespace: None | str = ...,
    headers: list[str] | dict[str, str] = ...,
    headers_as_raw_headers_mode: None | str = ...,
    implicit_test_library: None | str = ...,
    include_directories: list[str] = ...,
    inplace_build_args: list[str] = ...,
    labels: list[str] = ...,
    lang_compiler_flags: dict[str, list[str]] = ...,
    lang_platform_compiler_flags: dict[str, list[(str, list[str])]] = ...,
    lang_platform_preprocessor_flags: dict[str, list[(str, list[str])]] = ...,
    lang_preprocessor_flags: dict[str, list[str]] = ...,
    libraries: list[str] = ...,
    licenses: list[str] = ...,
    link_deps_query_whole: bool = ...,
    link_execution_preference: None | str = ...,
    link_group: None | str = ...,
    link_group_deps: list[str] = ...,
    link_group_map: None | str | list[(str, list[(None | str | list[None | str], str, None | str | list[str], None | str)], None | dict[str, typing.Any])] = ...,
    link_group_min_binary_node_count: None | int = ...,
    link_group_public_deps_label: None | str = ...,
    link_ordering: None | str = ...,
    link_style: str = ...,
    link_whole: bool = ...,
    linker_extra_outputs: list[str] = ...,
    linker_flags: list[str] = ...,
    main_function: None | str = ...,
    main_module: None | str = ...,
    make_py_package: None | str = ...,
    manifest_module_entries: None | dict[str, list[str] | dict[str, typing.Any]] = ...,
    native_link_strategy: None | str = ...,
    needed_coverage: list[(int, str, None | str)] = ...,
    opt_by_default_enabled: bool = ...,
    package_split_dwarf_dwp: bool = ...,
    package_style: None | str = ...,
    par_style: None | str = ...,
    platform: None | str = ...,
    platform_compiler_flags: list[(str, list[str])] = ...,
    platform_deps: list[(str, list[str])] = ...,
    platform_headers: list[(str, list[str] | dict[str, str])] = ...,
    platform_linker_flags: list[(str, list[str])] = ...,
    platform_override: None | str = ...,
    platform_preload_deps: list[(str, list[str])] = ...,
    platform_preprocessor_flags: list[(str, list[str])] = ...,
    platform_resources: list[(str, list[str] | dict[str, str])] = ...,
    platform_srcs: list[(str, list[str | (str, list[str])])] = ...,
    post_linker_flags: list[str] = ...,
    post_platform_linker_flags: list[(str, list[str])] = ...,
    precompiled_header: None | str = ...,
    prefer_stripped_native_objects: bool = ...,
    prefer_stripped_objects: bool = ...,
    prefix_header: None | str = ...,
    preload_deps: list[str] = ...,
    preprocessor_flags: list[str] = ...,
    py_version_for_type_checking: None | str = ...,
    raw_headers: list[str] = ...,
    raw_headers_as_headers_mode: None | str = ...,
    remote_execution: None | str | dict[str, None | bool | int | str | list[dict[str, str]] | dict[str, str | list[str]]] = ...,
    repl_main: None | str = ...,
    repl_only_deps: list[str] = ...,
    resources: list[str] | dict[str, str] = ...,
    run_with_inplace: bool = ...,
    runner: None | str = ...,
    runtime_bundle: None | str = ...,
    runtime_bundle_full: bool = ...,
    runtime_dependency_handling: None | str = ...,
    runtime_env: None | dict[str, str] = ...,
    separate_debug_info: bool = ...,
    shard_typing: None | bool = ...,
    specs: None | str = ...,
    srcs: list[str] | dict[str, str] = ...,
    standalone_build_args: list[str] = ...,
    static_extension_finder: str = ...,
    static_extension_utils: str = ...,
    strip_libpar: str = ...,
    strip_stapsdt: bool = ...,
    test_rule_timeout_ms: None | int = ...,
    thin_lto: bool = ...,
    typing: bool = ...,
    use_anon_target_for_analysis: bool = ...,
    use_header_units: bool = ...,
    use_oss_python: bool = ...,
    use_rust_make_par: bool = ...,
    version_selections: dict[str, str] = ...,
    version_universe: None | str = ...,
    versioned_resources: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    versioned_srcs: None | list[(dict[str, str], list[str] | dict[str, str])] = ...,
    weak_framework_names: list[str] = ...,
    zip_safe: None | bool = ...,
) -> None

A python_test() rule defines a set of .py files that contain tests to run via the Python unit testing framework.

Parameters​

  • name: name of the target

  • default_target_platform: specifies the default target platform, used when no platforms are specified on the command line

  • target_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with a configuration

  • exec_compatible_with: a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

  • visibility: a list of visibility patterns restricting what targets can depend on this one

  • within_view: a list of visibility patterns restricting what this target can depend on

  • metadata: a key-value map of metadata associated with this target

  • tests: a list of targets that provide tests for this one

  • modifiers: an array of modifiers associated with this target

  • _build_info: Build info that is passed along here will be late-stamped into a fb_build_info section on the output binary

  • base_module: The package in which the specified source files and resources should reside in their final location in the top-level binary. If unset, Buck uses the project-relative directory that contains the BUCK file.

  • deduplicate_merged_link_roots: When linking multiple top-level binaries with the merged .buckconfig, coalesce root link rules which are identical across independent merged links.

  • deps: A list of python_library() rules that specify Python modules to include in the binary — including all transitive dependencies of these rules.

  • env: A map of environment names and values to set when running the test.

    It is also possible to expand references to other rules within the values of these environment variables, using builtin string parameter macros :

    $(location //path/to:target) Expands to the location of the output of the build rule. This means that you can refer to these without needing to be aware of how Buck is storing data on the disk mid-build.

  • exclude_deps_from_merged_linking: When linking the top-level binary with a merged .buckconfig, do not merge or re-link any native transitive deps of this library. This is useful if this library wraps prebuilt native extensions which cannot be re-linked as part of library merging.

  • labels: Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query() .

  • link_group_deps: Additional targets to traverse when building link groups, but which should not be direct dependencies of the main executable.

  • link_group_public_deps_label: Surface nodes with this label as "public" nodes in the main executable when linking with with link groups.

  • linker_flags: Additional linker flags that should be applied to any linking which is specific to this rule. Note that whether these flags are used is dependent on the native link strategy selected in .buckconfig and currently applies only to the merged .buckconfig; the separate link strategy pulls in shared libraries that are linked in the context of the rules that own them, such as cxx_library().

  • main_function: Name of a Python function that will serve as the main entry point of the binary. The name is either a fully qualified name like foo.bar.baz or it starts with a . like .bar.baz, in which case it is relative to the package containing the target. This should usually be a function defined within one of the dependencies of this target. This attribute should be preferred over main_module or main, and it is an error to specify more than one of these.

  • main_module: The main module used to run the tests. This parameter is normally not needed, as Buck will provide a default main module that runs all tests. However, you can override this with your own module to perform custom initialization or command line processing. Your custom module can import the standard Buck test main as __test_main__, and can invoke it's normal main function as __test_main__.main(sys.argv).

  • manifest_module_entries: If present, it should be a string -> entry mapping that gets generated into a __manifest__ module in the executable. Top level string keys will be the names of variables in this module (so they must be valid Python identifiers). An entry can be a list of strings, or a further string-keyed dictionary.

  • package_style: Used to override the global packaging style that is set in [.buckconfig ].

  • platform: The name of the Python platform flavor to build against by default as defined in the buckconfig#pythonsection of .buckconfig.

  • platform_resources: Python-platform-specific resource files. These should be specified as a list of pairs where the first element in each pair is an un-anchored regex against which the platform name is matched, and the second element is a list of resource files. The regex should use java.util.regex.Pattern syntax. The platform name is a Python platform flavor defined in the buckconfig#python section of .buckconfig.

  • preload_deps: A list of C/C++ library dependencies that need to be loaded before any other libraries when the PEX starts up. This requires dynamic loader support, such as LD_PRELOAD, found on most systems. This list is order- sensitive and the preload libraries listed here are passed down to the dynamic linker in the same order.

  • py_version_for_type_checking: This option will force the type checker to perform checking under a specific version of Python interpreter.

  • shard_typing: Determines if sharding should be enabled on a given target.

  • srcs: The set of Python (.py) files to include in this library.

  • test_rule_timeout_ms: If set specifies the maximum amount of time (in milliseconds) in which all of the tests in this rule should complete. This overrides the default rule_timeout if any has been specified in .buckconfig .

  • typing: Determines whether to perform type checking on the given target. Default is False.

  • version_selections: A mapping from library name to desired version. Versioned dependencies from the entire dependency tree with the given name will be used at the specified version, if available. Versioned libraries that are unspecified will be used at their respective default version.

Details​

If your test requires static files you should specify these in the resources or platform_resources arguments. If you do not specify these files, they won't be available when your test runs.

Examples:


# A rule that includes a single .py file containing tests.
python_test(
  name = 'fileutil_test',
  srcs = ['fileutil_tests.py'],
  deps = [
    ':fileutil',
  ],
)

# A rule that uses glob() to include all sources in the directory which the
# rule is defined.  It also lists a resource file that gets packaged with
# the sources in this rule.
python_library(
  name = 'fileutil',
  srcs = glob(['fileutil/**/*.py']),
  resources = [
    'testdata.dat',
  ],
)