{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 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}