Тестовое сопоставление

This is a brief introduction of test mapping and an explanation of how to get started configuring tests in the Android Open Source Project (AOSP).

About test mapping

Метод сопоставления тестов — это подход на основе Gerrit, который позволяет разработчикам создавать правила тестирования до и после отправки изменений непосредственно в исходном коде Android, оставляя решения о ветвях и тестируемых устройствах тестовой инфраструктуре. Определения сопоставления тестов представляют собой JSON-файлы с именем TEST_MAPPING , которые можно разместить в любом каталоге исходного кода.

Atest может использовать файлы TEST_MAPPING для запуска предварительных тестов перед отправкой в ​​соответствующих каталогах. С помощью сопоставления тестов можно добавить один и тот же набор тестов в предварительные проверки с минимальными изменениями в исходном коде Android.

See these examples:

• Add presubmit tests to TEST_MAPPING for services.core

• Add presubmit tests to TEST_MAPPING for tools/dexter using imports

Test mapping relies on the Trade Federation (TF) test harness for tests execution and results reporting.

Define test groups

Функция сопоставления тестов объединяет тесты в группу тестов . Название группы тестов может быть любой строкой. Например, presubmit может быть названием группы тестов, которые будут запускаться при проверке изменений. А postsubmit может быть названием тестов, используемых для проверки сборок после слияния изменений.

Package build script rules

Для того чтобы тестовая среда Trade Federation могла запускать тестовые модули для данной сборки, эти модули должны иметь параметр test_suites установленный для Soong , или параметр LOCAL_COMPATIBILITY_SUITE , установленный для Make, на один из этих двух наборов тестов:

• general-tests предназначен для тестов, которые не зависят от специфических возможностей устройства (например, от оборудования конкретного производителя, которого нет у большинства устройств). Большинство тестов должны быть включены в пакет general-tests , даже если они специфичны для одного ABI, разрядности или аппаратных функций, таких как HWASan (для каждого ABI существует отдельный целевой объект test_suites ), и даже если они должны выполняться на устройстве.
• device-tests предназначен для тестов, зависящих от возможностей конкретного устройства. Обычно такие тесты находятся в папке vendor/ . Device-specific относится только к возможностям, уникальным для данного устройства, поэтому это относится как к тестам JUnit, так и к тестам GTest (которые обычно следует помечать как general-tests даже если они специфичны для ABI).

Примеры:

Android.bp: test_suites: ["general-tests"],
Android.mk: LOCAL_COMPATIBILITY_SUITE := general-tests

Configure tests to run in a test suite

For a test to run inside of a test suite, the test:

• Must not have any build provider.
• Must clean up after it's finished, for example, by deleting any temporary files generated during the test.
• Must change system settings to the default or original value.

• Не следует предполагать, что устройство находится в определённом состоянии, например, готово к получению root-прав. Для большинства тестов root-права не требуются. Если для выполнения теста необходимы root-права, это следует указать с помощью RootTargetPreparer в файле AndroidTest.xml , как показано в следующем примере:

  <target_preparer class="com.android.tradefed.targetprep.RootTargetPreparer"/>
  

Create test mapping files

Для каталога, требующего проверки покрытия тестами, добавьте JSON-файл TEST_MAPPING аналогичный приведенному примеру . Эти правила гарантируют, что тесты будут запускаться в рамках предварительных проверок перед отправкой, когда в этом каталоге или любом из его подкаталогов будут изменены какие-либо файлы.

Follow an example

Here is a sample TEST_MAPPING file (it's in JSON format but with comments supported):

{
  "presubmit": [
    // JUnit test with options and file patterns.
    {
      "name": "CtsWindowManagerDeviceTestCases",
      "options": [
        {
          "include-annotation": "android.platform.test.annotations.RequiresDevice"
        }
      ],
      "file_patterns": ["(/|^)Window[^/]*\\.java", "(/|^)Activity[^/]*\\.java"]
    },
    // Device-side GTest with options.
    {
      "name" : "hello_world_test",
      "options": [
        {
          "native-test-flag": "\"servicename1 servicename2\""
        },
        {
          "native-test-timeout": "6000"
        }
      ]
    }
    // Host-side GTest.
    {
      "name" : "net_test_avrcp",
      "host" : true
    }
  ],
  "postsubmit": [
    {
      "name": "CtsDeqpTestCases",
      "options": [
        {
          // Use regex in include-filter which is supported in AndroidJUnitTest
          "include-filter": "dEQP-EGL.functional.color_clears.*"
        }
      ]
    }
  ],
  "imports": [
    {
      "path": "frameworks/base/services/core/java/com/android/server/am"
    }
  ]
}

Установить атрибуты

In the example , presubmit and postsubmit are the names of each test group. See Define test groups for more information about test groups.

В значении атрибута name можно задать имя тестового модуля или имя интеграционного теста Trade Federation (например, путь к XML-файлу теста, uiautomator/uiautomator-demo ). Обратите внимание, что в поле name нельзя использовать name класса или name тестового метода. Чтобы сузить круг запускаемых тестов, используйте такие параметры, как include-filter . См. пример использования include-filter .

Параметр host теста указывает, является ли тест беспроводным и выполняется ли он на хосте или нет. Значение по умолчанию — false , что означает, что для выполнения теста требуется устройство. Поддерживаются следующие типы тестов: HostGTest для бинарных файлов GTest и HostTest для тестов JUnit.

Атрибут file_patterns позволяет задать список строк регулярных выражений для сопоставления относительного пути к любому файлу исходного кода (относительно каталога, содержащего файл TEST_MAPPING ). В примере тест CtsWindowManagerDeviceTestCases запускается в режиме presubmit только тогда, когда файл Java начинается с Window или Activity и находится в том же каталоге, что и файл TEST_MAPPING или в любом из его подкаталогов. Обратные косые черты (\) необходимо экранировать, поскольку они находятся в файле JSON.

Атрибут imports позволяет включать тесты в другие файлы TEST_MAPPING без копирования их содержимого. Файлы TEST_MAPPING находящиеся в родительских каталогах импортируемого пути, также включаются. Функция сопоставления тестов допускает вложенный импорт; это означает, что два файла TEST_MAPPING могут импортировать друг друга, а сопоставление тестов может объединять включенные тесты.

The options attribute contains additional Tradefed command line options.

To get a complete list of available options for a given test, run:

tradefed.sh run commandAndExit [test_module] --help

Refer to Option handling in Tradefed for more details about how options work.

Запускайте тесты с помощью Atest

To execute the presubmit test rules locally:

1. Go to the directory containing the TEST_MAPPING file.

2. Выполните команду:

   atest
   

All presubmit tests configured in the TEST_MAPPING files of the current directory and its parent directories are run. Atest locates and runs two tests for presubmit (A and B).

Это самый простой способ запуска тестов перед отправкой, хранящихся в файлах TEST_MAPPING в текущем рабочем каталоге (CWD) и родительских каталогах. Atest находит и использует файл TEST_MAPPING в CWD и всех его родительских каталогах.

Structure source code

This example shows how you can configure TEST_MAPPING files across the source tree:

src
├── project_1
│   └── TEST_MAPPING
├── project_2
│   └── TEST_MAPPING
└── TEST_MAPPING

Content of src/TEST_MAPPING :

{
  "presubmit": [
    {
      "name": "A"
    }
  ]
}

Content of src/project_1/TEST_MAPPING :

{
  "presubmit": [
    {
      "name": "B"
    }
  ],
  "postsubmit": [
    {
      "name": "C"
    }
  ],
  "other_group": [
    {
      "name": "X"
    }
  ]}

Content of src/project_2/TEST_MAPPING :

{
  "presubmit": [
    {
      "name": "D"
    }
  ],
  "import": [
    {
      "path": "src/project_1"
    }
  ]}

Specify target directories

You can specify a target directory to run tests in TEST_MAPPING files in that directory. The following command runs two tests (A, B):

atest --test-mapping src/project_1

Run postsubmit test rules

You can also use this command to run the postsubmit test rules defined in TEST_MAPPING in src_path (default to CWD) and its parent directories:

atest [--test-mapping] [src_path]:postsubmit

Run only tests that require no device

Для запуска тестов в Atest можно использовать опцию --host , чтобы выполнять только те тесты, которые настроены для хоста, не требующего устройства. Без этой опции Atest запускает оба типа тестов: те, которые требуют устройства, и те, которые выполняются на хосте, не требующем устройства. Тесты запускаются в двух отдельных наборах:

atest [--test-mapping] --host

Identify test groups

You can specify test groups in the Atest command. The following command runs all postsubmit tests related to files in the src/project_1 directory, which contains only one test (C).

Or you can use :all to run all tests regardless of group. The following command runs four tests (A, B, C, X):

atest --test-mapping src/project_1:all

Включить подкаталоги

По умолчанию при запуске тестов в TEST_MAPPING с помощью Atest выполняются только предварительные тесты, настроенные в файле TEST_MAPPING , расположенном в текущем каталоге (CWD) и его родительских каталогах. Если вы хотите запустить тесты во всех файлах TEST_MAPPING в подкаталогах, используйте опцию --include-subdir чтобы заставить Atest включить и эти тесты.

atest --include-subdir

Without the --include-subdir option, Atest runs only test A. With the --include-subdir option, Atest runs two tests (A, B).

Line-level comment supported

Вы можете добавить построчный комментарий // format, чтобы дополнить файл TEST_MAPPING описанием следующей за ним настройки. ATest and Trade Federation предварительно обрабатывает файл TEST_MAPPING преобразуя его в допустимый формат JSON без комментариев. Для сохранения чистоты файла JSON поддерживается только построчный комментарий // format.

Пример:

{
  // For presubmit test group.
  "presubmit": [
    {
      // Run test on module A.
      "name": "A"
    }
  ]
}