Add new GoogleTests (GTests)

If you're new to Android platform development, you may find this complete example of adding a brand new GTest binary (also sometimes called a "native" test) from scratch useful to demonstrate the typical workflow involved. For additional information on the GTest framework for C++, refer to the GTest project site for additional documentation.

This guide uses the Hello World GTest as an example. We recommend reading through the code to get a rough understanding of it before you continue.

Decide on a source location

Typically your team will already have an established pattern of places to check in code, and places to add tests. Most team owns a single git repository, or share one with other teams but have a dedicated sub directory that contains component source code.

Assuming the root location for your component source is at <component source root>, most components have src and tests folders under it, and some additional files such as Android.mk (or broken up into additional .bp files).

Since you are adding a brand new test, you'll probably need to create the tests directory next to your component src, and populate it with content.

In some cases, your team might have further directory structures under tests due to the need to package different suites of tests into individual binaries. And in this case, you'll need to create a new sub directory under tests.

To illustrate, here's a typical directory outline for components with a single tests folder:

\
 <component source root>
  \-- Android.bp (component makefile)
  \-- AndroidTest.xml (test config file)
  \-- src (component source)
  |    \-- foo.cpp
  |    \-- ...
  \-- tests (test source root)
      \-- Android.bp (test makefile)
      \-- src (test source)
          \-- foo_test.cpp
          \-- ...

and here's a typical directory outline for components with multiple test source directories:

\
 <component source root>
  \-- Android.bp (component makefile)
  \-- AndroidTest.xml (test config file)
  \-- src (component source)
  |    \-- foo.cpp
  |    \-- ...
  \-- tests (test source root)
      \-- Android.bp (test makefile)
      \-- testFoo (sub test source root)
      |   \-- Android.bp (sub test makefile)
      |   \-- src (sub test source)
      |       \-- test_foo.cpp
      |       \-- ...
      \-- testBar
      |   \-- Android.bp
      |   \-- src
      |       \-- test_bar.cpp
      |       \-- ...
      \-- ...

Regardless of the structure, you'll end up populating the tests directory or the newly created sub directory with files similar to what's in the native directory in the sample gerrit change. The sections below will explain in further details of each file.

Source code

Refer to the Hello World GTest for an example.

The source code for that example is annotated here:

#include <gtest/gtest.h>

Header file include for GTest. The include file dependency is automatically resolved by using BUILD_NATIVE_TEST in the makefile.

#include <stdio.h>

TEST(HelloWorldTest, PrintHelloWorld) {
    printf("Hello, World!");
}

GTests are written using the TEST macro: the first parameter is the test case name, and the second is the test name. Along with test binary name, they form the following hierarchy in the result dashboard:

<test binary 1>
| \-- <test case 1>
| |   \-- <test 1>
| |   \-- <test 2>
| |   \-- ...
| \-- <test case 2>
| |   \-- <test 1>
| |   \-- ...
| \-- ...
<test binary 2>
|
...

For more information on writing tests with GTest, refer to the GTest documentation

Simple configuration file

Each new test module must have a configuration file to direct the build system with module metadata, compile-time dependencies and packaging instructions. In most cases, the Soong-based, Blueprint file option is sufficient. See Simple Test Configuration for details.

Complex configuration file

To use Trade Federation instead, write a test configuration file for Android's test harness, Trade Federation.

The test configuration can specify special device setup options and default arguments to supply the test class.

Build and test locally

For the most common use cases, employ Atest.

For more complex cases requiring heavier customization, follow the instrumentation instructions.