Pemetaan pengujian

Ini adalah pengantar singkat tentang pemetaan pengujian dan penjelasan tentang cara memulai konfigurasi pengujian di Project Open Source Android (AOSP).

Tentang pemetaan pengujian

Pemetaan pengujian adalah pendekatan berbasis Gerrit yang memungkinkan developer membuat aturan pengujian pra-kirim dan pasca-kirim langsung di hierarki sumber Android dan menyerahkan keputusan cabang dan perangkat yang akan diuji ke infrastruktur pengujian. Definisi pemetaan pengujian adalah file JSON bernama TEST_MAPPING yang dapat Anda tempatkan di direktori sumber mana pun.

Atest dapat menggunakan file TEST_MAPPING untuk menjalankan pengujian pra-kirim di direktori terkait. Dengan pemetaan pengujian, Anda dapat menambahkan kumpulan pengujian yang sama ke pemeriksaan pra-kirim dengan perubahan minimal di dalam hierarki sumber Android.

Lihat contoh berikut:

• Menambahkan pengujian pra-kirim ke TEST_MAPPING untuk services.core

• Menambahkan pengujian pra-kirim ke TEST_MAPPING untuk tools/dexter menggunakan impor

Pemetaan pengujian mengandalkan test harness Trade Federation (TF) untuk eksekusi pengujian dan pelaporan hasil.

Menentukan grup pengujian

Pemetaan pengujian mengelompokkan pengujian dengan grup pengujian. Nama grup pengujian dapat berupa string apa pun. Misalnya, pra-kirim dapat menjadi nama untuk grup pengujian yang akan dijalankan saat memvalidasi perubahan. Dan pasca-kirim dapat menjadi pengujian yang digunakan untuk memvalidasi build setelah perubahan digabungkan.

Aturan skrip build paket

Agar test harness Trade Federation dapat menjalankan modul pengujian untuk build tertentu, modul ini harus memiliki test_suites yang ditetapkan untuk Soong atau LOCAL_COMPATIBILITY_SUITE yang ditetapkan untuk Make ke salah satu dari dua suite ini:

• general-tests adalah untuk pengujian yang tidak bergantung pada kemampuan khusus perangkat (seperti hardware khusus vendor yang tidak dimiliki sebagian besar perangkat). Sebagian besar pengujian harus berada dalam suite general-tests, meskipun pengujian tersebut khusus untuk satu ABI atau bitness atau fitur hardware seperti HWASan (ada target test_suites terpisah untuk setiap ABI), dan meskipun pengujian tersebut harus dijalankan di perangkat.
• device-tests adalah untuk pengujian yang bergantung pada kemampuan khusus perangkat. Biasanya pengujian ini ditemukan di bagian vendor/. Khusus perangkat hanya mengacu pada kemampuan yang unik untuk perangkat, sehingga hal ini berlaku untuk pengujian JUnit serta pengujian GTest (yang biasanya harus ditandai sebagai general-tests meskipun khusus ABI).

Contoh:

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

Mengonfigurasi pengujian untuk dijalankan dalam suite pengujian

Agar pengujian dapat dijalankan di dalam paket pengujian, pengujian:

• Tidak boleh memiliki penyedia build.
• Harus dibersihkan setelah selesai, misalnya, dengan menghapus file sementara yang dihasilkan selama pengujian.
• Harus mengubah setelan sistem ke nilai default atau nilai asli.

• Tidak boleh mengasumsikan bahwa perangkat berada dalam status tertentu, misalnya, root siap. Sebagian besar pengujian tidak memerlukan hak istimewa root untuk dijalankan. Jika pengujian harus memerlukan root, pengujian tersebut harus menentukannya dengan RootTargetPreparer di AndroidTest.xml, seperti dalam contoh berikut:

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

Membuat file pemetaan pengujian

Untuk direktori yang memerlukan cakupan pengujian, tambahkan file JSON TEST_MAPPING yang menyerupai contoh. Aturan ini memastikan bahwa pengujian dijalankan dalam pemeriksaan pra-kirim saat file disentuh di direktori tersebut atau subdirektorinya.

Mengikuti contoh

Berikut adalah contoh file TEST_MAPPING (dalam format JSON tetapi dengan komentar yang didukung):

{
  "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"
    }
  ]
}

Menetapkan atribut

Dalam contoh ini, presubmit dan postsubmit adalah nama setiap grup pengujian. Lihat Menentukan grup pengujian untuk mengetahui informasi selengkapnya tentang grup pengujian.

Anda dapat menetapkan nama modul pengujian atau nama pengujian integrasi Trade Federation (jalur resource ke file XML pengujian, misalnya, uiautomator/uiautomator-demo) dalam nilai atribut name. Perhatikan bahwa kolom name tidak dapat menggunakan name class atau name metode pengujian. Untuk mempersempit pengujian yang akan dijalankan, gunakan opsi seperti include-filter. Lihat include-filter penggunaan contoh.

Setelan host pengujian menunjukkan apakah pengujian adalah pengujian tanpa perangkat yang berjalan di host atau tidak. Nilai defaultnya adalah false, yang berarti pengujian memerlukan perangkat untuk dijalankan. Jenis pengujian yang didukung adalah HostGTest untuk biner GTest dan HostTest untuk pengujian JUnit.

Atribut file_patterns memungkinkan Anda menetapkan daftar string ekspresi reguler untuk mencocokkan jalur relatif file kode sumber apa pun (relatif terhadap direktori yang berisi file TEST_MAPPING). Dalam contoh, pengujian CtsWindowManagerDeviceTestCases hanya berjalan dalam pra-kirim saat file Java dimulai dengan Window atau Activity, yang ada di direktori yang sama dengan file TEST_MAPPING atau subdirektorinya. Garis miring terbalik (\) harus di escape karena berada dalam file JSON.

Mengimpor file TEST_MAPPING

Atribut imports memungkinkan Anda menyertakan pengujian di file TEST_MAPPING lain tanpa menyalin konten. File TEST_MAPPING di direktori induk jalur yang diimpor juga disertakan. TEST_MAPPING memungkinkan impor bertingkat, yang berarti file yang diimpor dapat mengimpor file TEST_MAPPING lain, dan pemetaan pengujian dapat menggabungkan pengujian yang disertakan.

TEST_MAPPING mendukung impor tingkat root dan tingkat grup:

• Impor tingkat root: Ditentukan di tingkat atas file TEST_MAPPING (di luar grup pengujian mana pun). Impor tingkat root mengimpor seluruh file TEST_MAPPING target (dan direktori induknya) seolah-olah ditulis di jalur yang diimpor. Semua definisi grup pengujian dalam file yang diimpor (misalnya, presubmit, postsubmit) digabungkan ke dalam grup pengujian yang sesuai dari file impor.
• Impor tingkat grup: Ditentukan langsung di dalam grup pengujian tertentu (seperti presubmit atau postsubmit). Impor tingkat grup dicakup secara ketat ke grup pengujian tersebut, yang berarti hanya pengujian yang ditentukan dalam grup tertentu di dalam file TEST_MAPPING target yang akan diimpor. Semua grup pengujian lainnya dalam file target akan diabaikan.

Impor tingkat grup memberikan kontrol terperinci atas eksekusi uji. Misalnya, Anda dapat mengimpor pengujian khusus untuk pra-kirim tanpa menarik pengujian pasca-kirim yang berat dari direktori yang diimpor.

Contoh impor tingkat root:

{
  "imports": [
    {
      "path": "frameworks/base/services/core"
    }
  ],
  "presubmit": [
    {
      "name": "MyTestModule"
    }
  ]
}

Contoh impor tingkat grup:

{
  "presubmit": [
    {
      "name": "MyTestModule"
    },
    {
      "imports": [
        {
          "path": "frameworks/base/services/core"
        }
      ]
    }
  ],
  "postsubmit": [
    {
      "imports": [
        {
          "path": "frameworks/base/services/accessibility"
        }
      ]
    }
  ]
}

Atribut options berisi opsi command line Tradefed tambahan.

Untuk mendapatkan daftar lengkap opsi yang tersedia untuk pengujian tertentu, jalankan:

tradefed.sh run commandAndExit [test_module] --help

Lihat Penanganan opsi di Tradefed untuk mengetahui detail selengkapnya tentang cara kerja opsi.

Validasi TEST_MAPPING

Saat mengirimkan perubahan yang mengubah file TEST_MAPPING, pemeriksaan pra-kirim akan dijalankan untuk memastikan kebenaran:

• Validasi pola file: Memastikan semua ekspresi reguler di file_patterns cocok dengan setidaknya satu file di repositori. Pola lama yang tidak cocok dengan file apa pun akan menyebabkan pemeriksaan gagal.
• Validasi waktu build: Mempromosikan peringatan validasi waktu build yang dikumpulkan build ke error pemblokiran dalam pra-kirim untuk cabang utama. Peringatan umum mencakup:
  • Modul yang tidak ada: Mereferensikan nama modul pengujian yang tidak ada dalam codebase, seperti saat nama memiliki kesalahan ketik.
  • Impor tidak valid: Jalur referensi di imports yang tidak ada atau tidak berisi file TEST_MAPPING.
  • Masalah skema: Menggunakan kunci yang tidak didukung atau struktur yang salah format dalam konfigurasi JSON.

Menjalankan pengujian dengan Atest

Untuk menjalankan aturan pengujian pra-kirim secara lokal:

1. Buka direktori yang berisi file TEST_MAPPING.

2. Jalankan perintah:

   atest
   

Semua pengujian pra-kirim yang dikonfigurasi dalam file TEST_MAPPING dari direktori saat ini dan direktori induknya akan dijalankan. Atest menemukan dan menjalankan dua pengujian untuk pra-kirim (A dan B).

Ini adalah cara paling mudah untuk menjalankan pengujian pra-kirim dalam file TEST_MAPPING di direktori kerja saat ini (CWD) dan direktori induk. Atest menemukan dan menggunakan file TEST_MAPPING di CWD dan semua direktori induknya.

Menstruktur kode sumber

Contoh ini menunjukkan cara mengonfigurasi file TEST_MAPPING di seluruh hierarki sumber:

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

Konten src/TEST_MAPPING:

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

Konten src/project_1/TEST_MAPPING:

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

Konten src/project_2/TEST_MAPPING:

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

Menentukan direktori target

Anda dapat menentukan direktori target untuk menjalankan pengujian dalam file TEST_MAPPING di direktori tersebut. Perintah berikut menjalankan dua pengujian (A, B):

atest --test-mapping src/project_1

Menjalankan aturan pengujian pasca-kirim

Anda juga dapat menggunakan perintah ini untuk menjalankan aturan pengujian pasca-kirim yang ditentukan dalam TEST_MAPPING di src_path (default ke CWD) dan direktori induknya:

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

Hanya menjalankan pengujian yang tidak memerlukan perangkat

Anda dapat menggunakan opsi --host untuk Atest agar hanya menjalankan pengujian yang dikonfigurasi terhadap host yang tidak memerlukan perangkat. Tanpa opsi ini, Atest menjalankan kedua pengujian, yaitu pengujian yang memerlukan perangkat dan pengujian yang berjalan di host yang tidak memerlukan perangkat. Pengujian dijalankan dalam dua paket terpisah:

atest [--test-mapping] --host

Mengidentifikasi grup pengujian

Anda dapat menentukan grup pengujian dalam perintah Atest. Perintah berikut menjalankan semua pengujian postsubmit yang terkait dengan file di direktori src/project_1, yang hanya berisi satu pengujian (C).

Atau, Anda dapat menggunakan :all untuk menjalankan semua pengujian, terlepas dari grup. Perintah berikut menjalankan empat pengujian (A, B, C, X):

atest --test-mapping src/project_1:all

Menyertakan subdirektori

Secara default, menjalankan pengujian di TEST_MAPPING dengan Atest hanya menjalankan pengujian pra-kirim yang dikonfigurasi dalam file TEST_MAPPING di CWD (atau direktori yang diberikan) dan direktori induknya. Jika Anda ingin menjalankan pengujian di semua file TEST_MAPPING di subdirektori, gunakan opsi --include-subdir untuk memaksa Atest menyertakan pengujian tersebut.

atest --include-subdir

Tanpa opsi --include-subdir, Atest hanya menjalankan pengujian A. Dengan opsi --include-subdir, Atest menjalankan dua pengujian (A, B).

Komentar tingkat baris didukung

Anda dapat menambahkan komentar format // tingkat baris untuk melengkapi file TEST_MAPPING dengan deskripsi setelan yang mengikuti. ATest dan Trade Federation melakukan prapemrosesan TEST_MAPPING ke format JSON yang valid tanpa komentar. Untuk menjaga file JSON tetap bersih, hanya komentar format // tingkat baris yang didukung.

Contoh:

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