python_test()

This is liable to change in the future.

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

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.

Arguments

• name (required) #

  The short name for this build target.

• srcs (defaults to []) #

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

• platform_srcs (defaults to []) #

  Python-platform-specific source 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 source files. The regex should use java.util.regex.Pattern syntax. The platform name is a Python platform flavor defined in the [python] section of .buckconfig.

• resources (defaults to []) #

  Static files to be packaged along with the Python sources. These resources can be accessed at runtime using the pkg_resources module distributed with Python's setuptools.

• platform_resources (defaults to []) #

  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 [python] section of .buckconfig.

• base_module (defaults to None) #

  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.

• exclude_deps_from_merged_linking (defaults to False) #

  When linking the top-level binary with a merged [python].native_link_strategy, 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.

• main_module (defaults to None) #

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

• platform (defaults to None) #

  The name of the Python platform flavor to build against by default as defined in the [python] section of .buckconfig.

• env (defaults to {}) #

  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.

• deps (defaults to []) #

  python_library rules used by the tests in this rules sources.

• labels (defaults to []) #

  A list of labels to be applied to these tests. These labels are arbitrary text strings and have no meaning within buck itself. They can, however, have meaning for you as a test author (e.g., smoke or fast). A label can be used to filter or include a specific python_test() rule when executing buck test.

• test_rule_timeout_ms (defaults to None) #

  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 [test].rule_timeout.

• contacts (defaults to []) #

  A list of organizational contacts for this test. These could be individuals who you would contact in the event of a test failure or other issue with the test.

  contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]
  

• package_style (defaults to None) #

  Used to override the global packaging style that is set in [[python].package_style].

• preload_deps (defaults to []) #

  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.

• linker_flags (defaults to []) #

  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 [python].native_link_strategy; the separate link strategy pulls in shared libraries that are linked in the context of the rules that own them, such as cxx_library.

• visibility (defaults to []) #

  List of build target patterns that identify the build rules that can include this rule as a dependency, for example, by listing it in their deps or exported_deps attributes. For more information, see visibility.

• licenses (defaults to []) #

  Set of license files for this library. To get the list of license files for a given build rule and all of its dependencies, you can use buck query.

• labels (defaults to []) #

  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 attrfilter().

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',
  ],
)

Here is an example of using the `platform_srcs` and `platform_resources` parameters to pull in sources/resources only when building for a specific Python platform:

; .buckconfig
[python#py2]
  interpreter = /usr/bin/python2.7
[python#py3]
  interpreter = /usr/bin/python3.4

# BUCK
python_test(
  name = 'test',
  platform_srcs = [
    ('py2', ['foo.py']),
    ('py3', ['bar.py']),
  ],
  platform_resources = [
    ('py2', ['foo.dat']),
    ('py3', ['bar.dat']),
  ],
)

Here is an example of using the `platform` parameter to select the "py2" Python platform as defined in `.buckconfig` above:

# BUCK
python_test(
  name = 'bin',
  platform = 'py2',
  srcs = [
    'foo.py',
  ],
)