Menjalankan pengujian dari command line

Dokumen ini menjelaskan cara menjalankan pengujian langsung dari command line. Dokumen ini mengasumsikan bahwa Anda telah memahami cara membuat aplikasi Android dan menulis pengujian untuk aplikasi. Untuk mengetahui informasi selengkapnya tentang cara mem-build pengujian untuk aplikasi, lihat Menguji aplikasi di Android.

Saat mem-build aplikasi menggunakan sistem build Gradle, plugin Android Gradle memungkinkan Anda menjalankan pengujian dari project Gradle menggunakan command line. Untuk kontrol lebih detail, Anda juga dapat memilih untuk menjalankan pengujian melalui shell Android Debug Bridge (adb). Hal ini dapat berguna saat menjalankan pengujian di lingkungan continuous integration.

Untuk mempelajari cara menjalankan pengujian berinstrumen otomatis dari command line menggunakan perangkat virtual yang dikelola Gradle untuk Anda, lihat Menskalakan pengujian dengan Perangkat yang Dikelola Gradle.

Menjalankan pengujian dengan Gradle

Plugin Android Gradle memungkinkan Anda menjalankan pengujian dari project Gradle menggunakan command line.

Tabel di bawah merangkum cara menjalankan pengujian dengan Gradle:

Tabel 1. Berbagai cara menjalankan pengujian dengan Gradle.

Jenis pengujian unit Perintah untuk dijalankan Lokasi hasil pengujian
Pengujian unit lokal Jalankan tugas test: 

./gradlew test
File hasil pengujian HTML:
direktori path_to_your_project/module_name/build/reports/tests/.

File hasil pengujian XML:
direktori path_to_your_project/module_name/build/test-results/.

Pengujian unit berinstrumen Jalankan tugas connectedAndroidTest: 

./gradlew connectedAndroidTest
File hasil pengujian HTML:
direktori path_to_your_project/module_name/build/reports/androidTests/connected/.

File hasil pengujian XML:
direktori path_to_your_project/module_name/build/outputs/androidTest-results/connected/.

Gradle mendukung singkatan nama tugas. Misalnya, Anda dapat memulai tugas connectedAndroidTest dengan memasukkan perintah berikut:

./gradlew cAT

Anda juga dapat memilih untuk menjalankan tugas Gradle check dan connectedCheck. Tugas ini masing-masing berjalan di pengujian berinstrumen atau lokal, tetapi menyertakan pemeriksaan lain yang ditambahkan oleh plugin Gradle lain.

Menjalankan pengujian pada modul

Tugas test dan connectedAndroidTest menjalankan pengujian pada setiap modul di project Anda. Anda dapat menjalankan pengujian pada modul tertentu dengan memberi awalan pada tugas test atau connectedAndroidTest dengan nama modul dan titik dua (:). Misalnya, perintah berikut menjalankan pengujian berinstrumen hanya untuk modul mylibrary:

./gradlew mylibrary:connectedAndroidTest

Menjalankan pengujian pada varian build

Tugas test dan connectedAndroidTest menjalankan pengujian pada setiap varian build di project Anda. Anda dapat menargetkan varian build tertentu menggunakan sintaksis berikut:

  • Untuk pengujian unit lokal: 
    ./gradlew testVariantNameUnitTest
  • Untuk pengujian berinstrumen: 
    ./gradlew connectedVariantNameAndroidTest

Menjalankan metode atau class pengujian tertentu

Saat menjalankan pengujian unit lokal, Gradle memungkinkan Anda menargetkan pengujian tertentu menggunakan flag --tests. Misalnya, perintah berikut hanya menjalankan pengujian sampleTestMethod untuk varian build tertentu. Untuk mempelajari lebih lanjut penggunaan flag --tests, baca dokumentasi Gradle di pemfilteran pengujian.


./gradlew testVariantNameUnitTest --tests '*.sampleTestMethod'

Menjalankan pengujian dengan adb

Jika Anda menjalankan pengujian dari command line dengan Android Debug Bridge (adb), akan ada lebih banyak opsi untuk memilih pengujian yang akan dijalankan daripada dengan metode lainnya. Anda dapat memilih metode pengujian satu per satu, memfilter pengujian sesuai dengan anotasi kustom, atau menentukan opsi pengujian. Karena jalannya pengujian dikendalikan sepenuhnya dari command line, Anda dapat menyesuaikan pengujian dengan skrip shell dalam berbagai cara.

Untuk menjalankan pengujian dari command line, jalankan adb shell untuk memulai shell command line di perangkat atau emulator Anda. Di dalam shell tersebut, Anda dapat berinteraksi dengan pengelola aktivitas menggunakan perintah am dan menggunakan subperintah instrument untuk menjalankan pengujian.

Untuk mempermudah, Anda dapat memulai shell adb, memanggil am instrument, dan menentukan flag command line dalam satu baris input. Shell akan terbuka di perangkat atau emulator, menjalankan pengujian, menghasilkan output, lalu kembali ke command line di komputer Anda.

Untuk menjalankan pengujian dengan am instrument:

  1. Build atau build ulang aplikasi utama dan paket pengujian Anda.
  2. Instal file paket pengujian dan paket aplikasi utama Android Anda (file APK) ke emulator atau perangkat Android saat ini.

  3. Di command line, masukkan:

    adb shell am instrument -w <test_package_name>/<runner_class>

    Dengan <test_package_name> sebagai nama paket Android aplikasi pengujian, dan <runner_class> sebagai nama class test runner Android yang digunakan. Nama paket Android adalah nilai atribut paket dari elemen manifes dalam file manifes (AndroidManifest.xml) paket pengujian Anda.

    Class test runner Android biasanya AndroidJUnitRunner:

    adb shell am instrument -w com.android.example/androidx.test.runner.AndroidJUnitRunner

Hasil pengujian Anda muncul di STDOUT.

flag am instrument

Untuk menemukan daftar semua flag yang akan digunakan dengan perintah am instrument, jalankan adb shell am help. Beberapa flag penting dijelaskan dalam tabel berikut:

Tabel 2. Flag am instrument penting

Flag Nilai Deskripsi
-w (tidak ada) Memaksa am instrument untuk menunggu sampai instrumentasi dihentikan sebelum berhenti sendiri. Tindakan ini akan membuat shell tetap terbuka sampai pengujian selesai. Flag ini diperlukan untuk melihat hasil pengujian Anda.
-r (tidak ada) Output menghasilkan format raw. Gunakan flag ini saat Anda ingin mengumpulkan hasil pengukuran performa sehingga tidak diformat sebagai hasil pengujian. Tanda ini dirancang untuk digunakan dengan tanda -e perf true (didokumentasikan dalam bagian opsi am instrument).
-e <test_options> Memberikan opsi pengujian sebagai key-value pair. Alat am instrument meneruskan kode ini ke class instrumentasi yang ditentukan menggunakan metode onCreate(). Anda dapat menentukan beberapa kemunculan -e <test_options>. Kunci dan nilai dijelaskan di bagian opsi am instrument. Anda hanya dapat menggunakan key-value pair ini dengan AndroidJUnitRunner atau dengan InstrumentationTestRunner dan subclass-nya. Menggunakannya dengan class lain tidak berpengaruh apa pun.
--no-hidden-api-checks (tidak ada) Menonaktifkan pembatasan penggunaan API tersembunyi. Untuk mengetahui informasi selengkapnya tentang API tersembunyi dan pengaruhnya terhadap aplikasi Anda, baca Pembatasan antarmuka non-SDK.

Opsi am instrument

Alat am instrument meneruskan opsi pengujian ke AndroidJUnitRunner atau InstrumentationTestRunner dalam bentuk key-value pair, menggunakan tanda -e, dengan sintaksis ini:

-e <key> <value>

Sebagian kunci menerima beberapa nilai. Tentukan beberapa nilai dalam daftar yang dipisahkan koma. Misalnya, pemanggilan AndroidJUnitRunner memberikan beberapa nilai untuk kunci package:

adb shell am instrument -w -e package com.android.test.package1,com.android.test.package2 \
> com.android.test/androidx.test.runner.AndroidJUnitRunner

Tabel berikut mencantumkan key-value pair yang dapat Anda gunakan dengan test runner:

Tabel 3. Key-value pair flag -e untuk digunakan dengan test runner

Kunci Nilai Deskripsi
package <Java_package_name> Nama paket Java yang sepenuhnya memenuhi syarat untuk salah satu paket dalam aplikasi pengujian. Setiap class kasus pengujian yang menggunakan nama paket ini dieksekusi. Perhatikan bahwa ini bukan nama paket Android; paket pengujian memiliki satu nama paket Android, tetapi mungkin memiliki beberapa paket Java di dalamnya.
class <class_name> Nama class Java yang sepenuhnya memenuhi syarat untuk salah satu class kasus pengujian. Hanya class kasus pengujian ini yang dieksekusi.
<class_name>#method name Nama class kasus pengujian yang sepenuhnya memenuhi syarat, dan salah satu metodenya. Hanya metode ini yang dieksekusi. Perhatikan tanda pagar (#) di antara nama class dan nama metode.
func true Menjalankan semua class pengujian yang memperluas InstrumentationTestCase.
unit true Menjalankan semua class pengujian yang tidak memperluas InstrumentationTestCase atau PerformanceTestCase.
size [small | medium | large] Menjalankan metode pengujian yang dianotasi berdasarkan ukuran. Anotasi tersebut adalah @SmallTest, @MediumTest, dan @LargeTest.
perf true Menjalankan semua class pengujian yang menerapkan PerformanceTestCase. Saat Anda menggunakan opsi ini, tentukan flag -r untuk am instrument sehingga output disimpan dalam format raw dan tidak diformat ulang sebagai hasil pengujian.
debug true Menjalankan pengujian dalam mode debug.
log true Memuat dan mencatat semua pengujian yang ditentukan, tetapi tidak menjalankannya. Informasi pengujian muncul di STDOUT. Gunakan kode ini untuk memverifikasi kombinasi spesifikasi filter dan pengujian lainnya.
emma true Menjalankan analisis cakupan kode EMMA dan menulis output ke /data/<app_package>/coverage.ec di perangkat. Untuk mengganti lokasi file, gunakan kunci coverageFile yang dijelaskan dalam entri berikut.

Catatan: Opsi ini memerlukan build aplikasi pengujian berinstrumen EMMA, yang dapat Anda buat dengan target coverage.

coverageFile <filename> Mengganti lokasi default file cakupan EMMA pada perangkat. Tentukan nilai ini sebagai jalur dan nama file dalam format UNIX. Nama file default dijelaskan dalam entri untuk kunci emma.

Saat menggunakan flag -e, perhatikan hal-hal berikut:

  • am instrument memanggil onCreate(Bundle) dengan Bundle yang berisi key-value pair.
  • Kunci package lebih diutamakan daripada kunci class. Jika Anda menentukan paket, lalu menentukan class dalam paket tersebut secara terpisah, Android akan menjalankan semua pengujian dalam paket dan mengabaikan kunci class.
  • Kunci func dan kunci unit tidak dapat terjadi bersamaan.

Contoh penggunaan

Bagian berikut memberikan contoh penggunaan am instrument untuk menjalankan pengujian. Pengujian didasarkan pada struktur berikut:

  • Paket pengujian memiliki nama paket Android com.android.demo.app.tests.
  • Dua class pengujian berinstrumen:
    • TestClass1, yang berisi metode pengujian testMethod1.
    • TestClass2, yang berisi metode pengujian testMethod2 dan testMethod3.
  • Test runner-nya adalah AndroidJUnitRunner.

Menjalankan semua paket pengujian

Untuk menjalankan semua class pengujian dalam paket pengujian, masukkan:

adb shell am instrument -w com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Menjalankan semua pengujian dalam class kasus pengujian

Untuk menjalankan semua pengujian di class TestClass1, masukkan:

adb shell am instrument -w  \
> -e class com.android.demo.app.tests.TestClass1 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Memilih subset pengujian

Untuk menjalankan semua pengujian di class TestClass1 dan metode testMethod3 di TestClass2, masukkan:

adb shell am instrument -w \
> -e class com.android.demo.app.tests.TestClass1,com.android.demo.app.tests.TestClass2#testMethod3 \
> com.android.demo.app.tests/androidx.test.runner.AndroidJUnitRunner

Anda dapat menemukan lebih banyak kasus penggunaan di referensi API AndroidJUnitRunner.