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