API daftar terlihat sederhana, tetapi mengandung banyak defect menyulitkan. Hanya memeriksa bahwa daftar terbuka dapat melewatkan record duplikat atau hilang, urutan tidak stabil, total salah, filter rusak, dan ketidakkonsistenan antarhalaman.
Daftar muncul hampir di mana-mana: pengguna, pesanan, pembayaran, log, peristiwa, produk, tugas, dan komentar. Paginasi, filter, atau pengurutan yang buruk membuat produk terasa kacau: record hilang atau muncul dua kali, filter tidak terduga, urutan berubah, dan halaman berikutnya tidak konsisten.
Mengapa API membutuhkan fitur ini
Server dapat mengembalikan semua record ketika jumlahnya sedikit. Saat data bertambah, respons menjadi berat, rendering klien sulit, dan backend menghabiskan sumber daya yang tidak perlu.
- →Paginasi mengembalikan data secara bertahap
- →Filter mengembalikan subset yang diperlukan
- →Pengurutan menentukan urutan item
Mekanisme ini hampir selalu bekerja bersama. Pengguna membuka daftar pesanan, menyaring berdasarkan status, mengurutkan tanggal, dan berpindah halaman. Ketidakstabilan satu lapisan mengganggu seluruh pengalaman.
Paginasi
Paginasi membagi dataset besar menjadi halaman atau batch.
- →Paginasi berbasis offset: page=2, limit=20 atau offset=20&limit=20
- →Paginasi berbasis cursor: cursor=..., starting_after=..., next_page_token=...
QA perlu memahami perbedaannya.
Paginasi offset mudah dibaca dan umum pada antarmuka administrasi serta API CRUD biasa. Kelemahannya, isi halaman dapat bergeser ketika data berubah antarrequest. Pengguna melihat 20 record pada halaman pertama; seseorang menambah record; halaman kedua kemudian memuat duplikat atau melewatkan record.
Paginasi cursor umumnya lebih tahan terhadap data yang berubah. Cocok untuk daftar besar yang sering diperbarui, feed peristiwa, transaksi, dan sistem beban tinggi. Pengujian visual lebih sulit karena QA harus melacak cursor dan urutan item, bukan nomor halaman biasa.
Implikasi utama bagi QA: uji paginasi dengan data berubah maupun dataset statis.
Filter
Filter membatasi dataset menurut kondisi.
- →status = active
- →created_at >= tanggal
- →price antara X dan Y
- →owner_id = pengguna saat ini
- →Pencarian berdasarkan nama atau email
- →Beberapa filter diterapkan bersama
Fitur bermanfaat ini juga sering menjadi sumber defect logika.
- →Sebagian filter diabaikan
- →Dua filter berperilaku berbeda saat digabung dibandingkan secara terpisah
- →Filter kosong dan filter yang tidak disertakan diperlakukan berbeda
- →Sensitivitas huruf besar/kecil tidak sesuai harapan
- →Filter tanggal gagal karena zona waktu
- →Filter backend berbeda dari ekspektasi UI
- →Izin menyembunyikan sebagian record sehingga pengguna mengira filter rusak
Pengujian filter lebih dari memeriksa kondisi SQL atau parameter kueri. Pengujian memastikan sistem mengembalikan tepat subset yang dijanjikan kontraknya.
Pengurutan
Pengurutan menentukan urutan hasil, biasanya berdasarkan tanggal, nama, status, prioritas, harga, atau kolom lain.
Kesalahan paling umum adalah pemeriksaan dangkal bahwa urutan tampak kira-kira benar. Dalam praktik, pengurutan harus:
- →Benar
- →Stabil
- →Dapat diprediksi
- →Kompatibel dengan paginasi
Urutan stabil sangat penting. Mengurutkan hanya berdasarkan kolom bernilai sama, seperti timestamp created_at identik atau nilai status, dapat membuat urutan record yang seri tidak konsisten. Dengan paginasi, pengguna lalu dapat melihat record duplikat atau hilang antarhalaman.
QA perlu menguji nilai seri selain pengurutan satu kolom biasa.
Hal penting bagi QA
Beberapa pemeriksaan berguna dalam hampir setiap kasus.
Untuk paginasi:
- →Halaman pertama
- →Halaman terakhir
- →Halaman kosong
- →Ukuran halaman = 1
- →Ukuran halaman pada maksimum yang diizinkan
- →Ukuran halaman melebihi batas
- →Perpindahan antarhalaman berdekatan
- →Tidak ada duplikat atau record terlewat antarhalaman
- →Nilai has_more, next_cursor, dan total_count benar jika disediakan
Untuk filter:
- →Satu filter
- →Beberapa filter bersama
- →Nilai batas
- →Nilai kosong
- →Filter tidak disertakan
- →Nilai filter tidak valid
- →Filter pada kolom yang tunduk pada kontrol akses
- →Filter tanggal dan waktu
Untuk pengurutan:
- →Urutan naik dan turun
- →Pengurutan menurut kolom berbeda
- →Beberapa record dengan nilai sama
- →Pengurutan bersama filter
- →Pengurutan bersama paginasi
- →Kolom pengurutan yang tidak didukung
Pola kegagalan umum
- →Item muncul pada halaman pertama dan kedua
- →Item hilang antarhalaman
- →total_count berbeda dari jumlah sebenarnya
- →Filter berlaku pada record tetapi tidak pada jumlah
- →Urutan terlihat berubah antara request identik
- →Record baru menggeser posisi dan mengganggu navigasi offset
- →Backend diam-diam mengabaikan filter atau opsi pengurutan tidak dikenal
- →UI mengharapkan satu urutan tetapi API mengembalikan urutan lain
- →Filter tanggal memberi hasil berbeda karena zona waktu
- →Filter dan kontrol akses berinteraksi secara tidak terduga
Ini sangat penting ketika daftar merupakan antarmuka kerja utama produk. Ketidakstabilan kecil pun cepat merusak kepercayaan pengguna.
Contoh praktis
Pertimbangkan API daftar pesanan:
- →GET /orders?status=paid&sort=created_at_desc&limit=20
QA perlu memeriksa:
- →Hanya pesanan dibayar yang dikembalikan
- →Pesanan diurutkan menurut tanggal dalam arah yang diminta
- →Dua pesanan dengan created_at sama mempertahankan urutan relatif stabil
- →Halaman berikutnya tidak memiliki duplikat atau record terlewat
- →total_count, jika ada, sesuai dengan dataset setelah filter
- →Paginasi dapat diprediksi jika pesanan baru muncul saat navigasi
- →Nilai sort atau status tidak valid ditangani dengan jelas tanpa merusak layanan
Daftar dapat tampak hampir berfungsi, tetapi detail ini membuatnya tidak andal dalam praktik.
Hal penting bagi QA
- →Uji paginasi, filter, dan pengurutan bersama maupun secara terpisah.
- →API daftar sering gagal pada batas dan kombinasi kondisi, bukan hanya happy path.
- →Paginasi offset sederhana tetapi sensitif terhadap perubahan data antarrequest.
- →Paginasi cursor lebih tahan terhadap data berubah tetapi memerlukan pendekatan uji berbeda.
- →Pengurutan stabil penting untuk paginasi yang benar.
- →Periksa total_count, has_more, cursor, dan batas halaman secermat record itu sendiri.
Bacaan lanjutan
- →Dalam basis pengetahuan ini: Pengujian API negatif
- →Dalam basis pengetahuan ini: Metode, kode status, dan header
- →Sumber eksternal: Paginasi Stripe
Dataset 12 record dengan halaman yang hasilnya diketahui
Fixture lokal dimulai dengan ID 1–12. Score adalah floor((id−1)/3), sehingga tiga record berturut-turut memiliki score sama. ID genap berstatus open dan ID ganjil closed. Pengurutan score menggunakan ID sebagai kunci sekunder agar nilai seri deterministik. Jalankan pemeriksaan berikut pada fixture baru tanpa operasi tulis antarrequest halaman.
Query ID yang diharapkan Total
?sort=score&limit=5&offset=0 1,2,3,4,5 12
?sort=score&limit=5&offset=5 6,7,8,9,10 12
?sort=score&limit=5&offset=10 11,12 12
?sort=score&limit=5&offset=12 (kosong) 12
?status=open&sort=score&limit=5&offset=0 2,4,6,8,10 6
?status=open&sort=score&limit=5&offset=5 12 6Gabungkan tiga halaman pertama dan pastikan tepat ID 1–12, tanpa duplikat atau celah. Periksa bahwa total menjelaskan dataset setelah filter sebelum paginasi, bukan panjang halaman saat ini. Dalam kontrak ini limit harus 1–5, offset bilangan bulat nonnegatif, dan nilai sort/filter tidak didukung menghasilkan 400.
Pemecah seri yang stabil tidak membuat snapshot. Jika data berubah antarrequest offset, record dapat berpindah melewati batas. Eksperimen terpisah harus menetapkan kontrak konsistensi lalu menyisipkan/menghapus data antarrequest; paginasi cursor juga memerlukan urutan dan kebijakan validitas cursor yang jelas. Fixture ini melatih perilaku offset statis, bukan jaminan tambahan tersebut.