{namespace buck.command.test}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'buck test' /}
    {param description}
      A command that builds and runs the tests for one or more specified
      targets.
    {/param}
    {param content}


{call buck.command}
{param overview}
Builds and runs the tests for one or more specified targets:

<pre>buck test &#x2F;/javatests/com/example:tests</pre>


{/param}

{param params}
{call buck.param}
  {param name: 'all' /}
  {param desc}
  Run all tests available in the tree. If no targets are specified, this is the
  default.
 {/param}
{/call}

{call buck.param}
  {param name: 'code-coverage' /}
  {param desc}
  Collects code coverage information while running tests.  Currently, this only
  works with Java using <a href="http://www.eclemma.org/jacoco/">JaCoCo</a>.
  After running:

  <pre>buck test --code-coverage</pre>

  <p>

  The code coverage information can be found in:

  <pre>buck-out/gen/jacoco/code-coverage/</pre>
 {/param}
{/call}

{call buck.param}
  {param name: 'debug' /}
  {param desc}
  If specified, the tests will start suspended with a JDWP debug port of 5005.
  This means that they will not run until a debugger is attached.
 {/param}
{/call}


{call buck.param}
  {param name: 'include' /}
  {param desc}
  Test labels to run with this test.  Labels are a way to group together tests
  of a particular type and run them together.  For example, a developer could
  mark all tests that run in less than 100 milliseconds with
  the <code>fast</code> label, and then use:

  <pre>buck test --all --include fast</pre>

  to run only fast tests. See <a href="{ROOT}rule/java_test.html"><code>{sp}
  java_test()</code></a> for more details.

  <p>

  Use multiple arguments to match any label, and <code>+</code> to match a set
  of labels.  For example to match all the fast tests that are either stable or
  trustworthy, and aren't unstable:

  <pre>&hellip; --include fast+stable fast+trustworthy --exclude fast+unstable</pre>
  {/param}
{/call}

{call buck.param}
  {param name: 'exclude' /}
  {param desc}
  The inverse of <code>include</code>.  Labels specified with the exclude option
  won't be run.  For example, if we wanted to run all tests except slow ones, we
  would run:

  <pre>buck test --all --exclude slow</pre>
 {/param}
{/call}

{call buck.param}
  {param name: 'test-selectors' /}
  {param alias: 'filter' /}
  {param desc}
    Select tests to run by name, using a <code>class#method</code> syntax.  All
    other tests will not be run and test result caching is disabled:

    <pre>buck test --all --test-selectors 'com.example.MyTest#testX'</pre>

    Matching is done using <code>java.util.regex</code> regular expressions,
    and the class part (or method) part can be omitted to match all classes (or
    methods).

    Selectors are anchored to the end of each class and/or method name (i.e.
    a <code>$</code> at the end of your regular expressions is implied.)

    <pre>buck test --all --filter 'Foo.*'  # ...every class starting Foo</pre>
    <pre>buck test --all --filter '#testX' # ...run testX in every class</pre>

    You can exclude tests with <code>!</code>, and if all your test selectors
    are exclusive, then the default is to run everything except those tests:

    <pre>buck test --all --test-selectors '!MyTest'  # ...all except MyTest</pre>

    Test selectors can also be read from a file by formatting them as
    {sp}<code>@/path/to/file</code>.  The file should contain one test selector
    per line.

    <p>

    The first matching selector decides whether to include or exclude a test.
    The full logic is described in the <code>--help</code>.
  {/param}
{/call}

{call buck.param}
  {param name: 'dry-run' /}
  {param desc}
  Print the test rules that will be matched by command line arguments such as
  {sp}<code>--include</code> and <code>--exclude</code>, but exit before
  building or running tests.
  {/param}
{/call}

{call buck.param}
  {param name: 'num-threads' /}
  {param desc}
  The number of threads that buck should use when executing the
  build. This defaults to 1.25 times the number of processors in the
  system (on systems with hyperthreading, this means that each core is
  counted twice).

  The number of active threads may not always be equal to this
  argument.
 {/param}
{/call}

{call buck.param}
  {param name: 'ignore-when-dependencies-fail'/}
  {param desc}
  If a library is broken its tests are probably failing.  If another library
  depends on that library and its tests are also failing, it is probably
  because the dependency has a bug.

  <p>

  For example, if the library <code>HouseBuilder</code> depends on
  {sp}<code>Bricks</code> and the <code>Bricks</code> library is broken, it will
  probably cause its own tests as well as <code>HouseBuilder</code>'s to fail.

  <p>

  Accordingly, if the libraries are tested respectively by
  {sp}<code>HouseBuilderTest</code> and <code>BricksTest</code>, and both tests
  fail then only the error for <code>BricksTest</code> is printed; the error
  for <code>HouseBuilderTest</code> is ignored.

  <p>

  You'll still be notified that <code>HouseBuilderTest</code> is failing, and
  running the tests again without this option will show the cached test result
  (and error) in full.
  {/param}
{/call}

{call buck.param}
  {param name: 'verbose' /}
  {param alias: 'v'/}
  {param desc}
  How verbose logging to the console should be, with 1 as the minimum
  and 10 as the most verbose.
  {/param}
{/call}

{call buck.param}
  {param name: 'xml' /}
  {param desc}
  If specified, Buck will write the test results as XML to the location
  specified.  For example:

  <pre>buck test --all --xml testOutput.xml</pre>
 {/param}
 {/call}

{/param}

{/call}

    {/param}  // content
  {/call} // buck.page
{/template}