{namespace python_test}

{template .soyweb}

{call buck.page}

{param title: 'python_test()' /}

{param navid: 'rule_python_test' /}

{param prettify: true /}

{param description}

A rule that is used to define a set of python files that contian tests

to run via the python unit testing framework.

{/param}

{param content}

{call buck.rule}

{param status: 'UNFROZEN' /}

{param overview}

A <code>python_test()</code> rule is used to define a set of <code>.py</code>{sp}

files that contain tests to run via the <a href="https://docs.python.org/2/library/unittest.html">Python unit testing framework</a>.

{/param}

{param args}

{call buck.arg}

{param name: 'name' /}

{param desc}

The name of the rule.

{/param}

{/call}

{call python_common.srcs_arg /}

{call python_common.platform_srcs_arg /}

{call python_common.resources_arg /}

{call python_common.platform_resources_arg /}

{call python_common.base_module_arg /}

{call python_common.exclude_deps_from_merged_linking_arg /}

{call buck.arg}

{param name: 'main_module' /}

{param default : 'None' /}

{param desc}

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 <code>__test_main__</code>, and can invoke it's normal main function

as <code>__test_main__.main(sys.argv)</code>.

{/param}

{/call}

{call python_common.platform_arg /}

{call buck.arg}

{param name: 'env' /}

{{param default : '{}' /}}

{param desc}

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

<br><br>

It is also possible to expand references to other rules within the <b>values</b> of

these environment variables, using builtin {call buck.string_parameter_macros /}:

<dl>

<dt><code>$(location /&#x2F;path/to:target)</code></dt>

<dd>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.</dd>

</dl>

{/param}

{/call}

{call buck.arg}

{param name: 'deps' /}

{param default : '[]' /}

{param desc}

{call buck.python_library /} rules used by the tests in this rules sources.

{/param}

{/call}

{call buck.arg}

{param name: 'labels' /}

{param default: '[]' /}

{param desc}

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., <code>smoke</code> or <code>fast</code>). A label can be

used to filter or include a specific <code>python_test()</code> rule

when executing <a href="{ROOT}command/test.html"><code>buck

test</code></a>.

{/param}

{/call}

{call buck.test_rule_timeout_ms /}

{call python_common.package_style_arg /}

{call python_common.preload_deps_arg /}

{call python_common.linker_flags_arg /}

{/param} // close args

{param examples}

{literal}<pre class="prettyprint lang-py">

# 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',

],

)

</pre>{/literal}

<p>

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:

</p>

{literal}<pre class="prettyprint lang-ini">

; .buckconfig

[python#py2]

interpreter = /usr/bin/python2.7

[python#py3]

interpreter = /usr/bin/python3.4

</pre>{/literal}

{literal}<pre class="prettyprint lang-py">

# BUCK

python_test(

name = 'test',

platform_srcs = [

('py2', ['foo.py']),

('py3', ['bar.py']),

],

platform_resources = [

('py2', ['foo.dat']),

('py3', ['bar.dat']),

],

)

</pre>{/literal}

<p>

Here is an example of using the `platform` parameter to select the "py2"

Python platform as defined in `.buckconfig` above:

</p>

{literal}<pre class="prettyprint lang-py">

# BUCK

python_test(

name = 'bin',

platform = 'py2',

srcs = [

'foo.py',

],

)

</pre>{/literal}

{/param}

{/call} // close buck.rule

{/param}

{/call}

{/template}