Buck: python_test()

python_test()

This is liable to change in the future.

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

Arguments

  • name (required) #

    The name of the rule.

  • srcs (defaults to []) #

    The set of .py files included 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 is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched (as defined in the `python#name` section of `.buckconfig`), and the second element is a list of source files.

  • resources (defaults to []) #

    Static files to be packaged along with the python sources. These resources can be accessed at runtime using the pkg_resources API.

  • platform_resources (defaults to []) #

    Python-platform-specific resource files. These should be specified as a list of pairs where the first element is an un-anchored regex (in java.util.regex.Pattern syntax) against which the platform name is matched (as defined in the `python#name` section of `.buckconfig`), and the second element is a list of resource files.

  • base_module (defaults to None) #

    The package for which the given specified sources and resources should reside in their final location in the top-level binary. If unset, the project relative directory that houses the BUCK file is used.

  • 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 to build against by default (as defined in the `python#name` 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.

  • package_style (defaults to None) #

    Used to override the global packaging style set with 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 python binary starts up. This requires dynamic loader support found on most systems (e.g. `LD_PRELOAD`).

  • linker_flags (defaults to []) #

    Additional linker flags that should be applied to any links which are specific to this rule. Note that whether these flags are used are dependent on the native link strategy selected in `.buckconfig` and currently only applies to the `MERGED` link strategy, as the `SEPARATE` link strategy pulls in shared libraries linked in the context of their owning rule (e.g. `cxx_library`).

  • visibility (defaults to []) #

    List of build target patterns that identify the build rules that can include this rule in its deps.

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