Buck: buck test

buck test

Builds and runs the tests for one or more specified targets:
buck test //javatests/com/example:tests

You can either directly specify test targets, or any other target which contains a tests = ['...'] field to specify its tests.


  • --all Run all tests available in the tree. If no targets are specified, this is the default.
  • --no-results-cache Disables caching results for tests between runs. If specified, all tests will be run regardless of previous results.

    Buck normally caches test results. This means unless you change the test code (or any transitive dependency) buck will not re-run the test. This flag disables the caching entirely and always runs the specified tests.

  • --only-failing If specified, this runs only tests that aren't cached passed. This is similar to --no-results-cache but still attempts to use cached results for tests that passed. If the tests or any transitive dependencies change, they are re-run regardless of cached status.

    This can be useful in CI to re-run flaky tests.

  • --code-coverage Collects code coverage information while running tests. Currently, this only works with Java using JaCoCo. After running:
    buck test --code-coverage

    The code coverage information can be found in:

  • --debug 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.
  • --include 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 fast label, and then use:
    buck test --all --include fast
    to run only fast tests. See java_test() for more details.

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

    … --include fast+stable fast+trustworthy --exclude fast+unstable
  • --exclude The inverse of include. 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:
    buck test --all --exclude slow
  • --test-selectors (-filter) Select tests to run by name, using a class#method syntax. All other tests will not be run and test result caching is disabled:
    buck test --all --test-selectors 'com.example.MyTest#testX'
    Matching is done using java.util.regex 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 $ at the end of your regular expressions is implied.)
    buck test --all --filter 'Foo.*'  # ...every class starting Foo
    buck test --all --filter '#testX' # ...run testX in every class
    You can exclude tests with !, and if all your test selectors are exclusive, then the default is to run everything except those tests:
    buck test --all --test-selectors '!MyTest'  # ...all except MyTest
    Test selectors can also be read from a file by formatting them as @/path/to/file. The file should contain one test selector per line.

    The first matching selector decides whether to include or exclude a test. The full logic is described in the --help.

  • --num-threads 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.
  • --ignore-when-dependencies-fail 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.

    For example, if the library HouseBuilder depends on Bricks and the Bricks library is broken, it will probably cause its own tests as well as HouseBuilder's to fail.

    Accordingly, if the libraries are tested respectively by HouseBuilderTest and BricksTest, and both tests fail then only the error for BricksTest is printed; the error for HouseBuilderTest is ignored.

    You'll still be notified that HouseBuilderTest is failing, and running the tests again without this option will show the cached test result (and error) in full.

  • --test-runner-env Add or override an environment variable passed to the test runner. Can be specified multiple times for different environment variables. Later occurrences override earlier occurrences. Currently this only support Apple(ios/osx) tests.
    buck test --test-runner-env FOO=BAR --test-runner-env BAZ=QUUX //some:target
  • --verbose (-v) How verbose logging to the console should be, with 1 as the minimum and 10 as the most verbose.
  • --xml If specified, Buck will write the test results as XML to the location specified. For example:
    buck test --all --xml testOutput.xml