Workflow verifikasi berganda Laravel mengutamakan serangkaian ujian yang saling melengkapi agar flaky API dan job queue tidak merusak rilis. Dengan menjalankan contract test, smoke test, dan regression suite secara berlapis di pipeline CI, kita dapat mendeteksi regresi lebih cepat dan menjaga kondisi layanan tetap konsisten.

Artikel ini menunjukkan konfigurasi testing, alur otomatisasi, gating, monitoring hasil, serta strategi rollback dan penonaktifan suite bermasalah. Setiap langkah dibuat praktis agar dapat langsung diterapkan oleh tim Laravel Anda.

Menerapkan workflow verifikasi berganda Laravel

Mengatasi flaky API berarti menganggap setiap permukaan sistem—API, database, job queue—perlu diverifikasi dari berbagai level. Workflow verifikasi berganda Laravel membagi proses tersebut menjadi tiga kategori utama. Setiap kategori menyasar skenario berbeda: contract test menangani ekspektasi kontrak API dan queue, smoke test memastikan layanan utama naik, dan regression suite mengecek fungsionalitas secara mendalam setelah perubahan besar.

Penekanan utama ada pada urutan dan dependensi: contract test harus sukses sebelum smoke test berjalan (karena contract test mengecek interfacing paling awal), dan smoke test menjadi gerbang sebelum regression suite yang lebih berat. Gagal di salah satu level berarti proses deployment ditunda hingga investigasi selesai.

Konstelasi testing: contract, smoke, regression

Contract test untuk API dan job queue

Contract test memverifikasi bahwa API eksternal dan job queue memenuhi kontrak yang dijanjikan. Untuk API, pastikan response schema, header penting, dan kode status stabil. Untuk job queue, ujilah handler queue dengan bus yang mencatat job yang dipanggil.

Contoh test menggunakan Pest untuk contract API:

it('memenuhi kontrak response produk', function () {
    $this->getJson(route('api.products.index'))
         ->assertStatus(200)
         ->assertJsonStructure([
             'data' => [
                 '*' => ['id', 'name', 'price']
             ]
         ]);
});

it('menjalankan job pembayaran sesuai kontrak', function () {
    Queue::fake();
    event(new PaymentCompleted($order));

    Queue::assertPushed(ProcessReceipt::class, fn ($job) => $job->invoiceId === $order->invoice_id);
});

Jalankan contract test secara terpisah dari suite lain:

php artisan test --testsuite=contract

Pastikan contract test hanya mengeksekusi logika deterministik dan menggunakan mocking untuk dependensi eksternal agar tidak flaky.

Smoke test untuk layanan inti

Smoke test memastikan layanan paling kritis—misalnya endpoint login, queue worker, dan cache—stabil setelah deploy. Karena spektrum cenderung kecil, smoke test disusun agar cepat dieksekusi tetapi sudah mencakup alur end-to-end sederhana.

Contoh smoke test bisa memanggil endpoint `/health` yang melakukan pemeriksaan database, Redis, dan koneksi job queue.

it('mengembalikan status sehat', function () {
    $this->getJson('/health')
         ->assertStatus(200)
         ->assertJson(['status' => 'ok']);
});

Smoke test biasanya dijalankan setelah contract test, di lingkungan staging yang memuat konfigurasi job queue sama dengan production.

Regression suite untuk cakupan lengkap

Regression suite mencakup fungsionalitas mendalam: validasi API yang kompleks, integrasi queue, dan proses backend lain seperti scheduled job. Karena suite ini lebih berat, letakkan di tahap akhir pipeline CI dan jalankan hanya jika contract dan smoke test sukses.

Gunakan data test yang konsisten (factory yang reproduceable) dan hindari dependency real-time sehingga regression suite tidak menjadi sumber flaky test.

Otomatisasi CI, gating, dan monitoring

Automasi CI harus mencerminkan urutan testing dan memberikan gating yang jelas. Berikut contoh snippet GitHub Actions:

jobs:
  contract-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Run contract tests
        run: php artisan test --testsuite=contract

  smoke-test:
    needs: contract-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run smoke tests
        run: php artisan test --testsuite=smoke

  regression-suite:
    needs: smoke-test
    runs-on: ubuntu-latest
    if: ${{ success() }}
    steps:
      - uses: actions/checkout@v4
      - name: Run regression suite
        run: php artisan test --testsuite=regression

Setiap job dilengkapi gating: jika contract test gagal, smoke test tidak akan dijalankan, sehingga indikasi awal kegagalan langsung terlihat. Dalam GitLab atau Jenkins, gunakan fitur conditional execution yang sama untuk menghindari pemborosan waktu.

Kriteria gating konkret:

  • Contract test harus 100% lolos; kegagalan berarti blocking merge karena API tidak sesuai kontrak.
  • Smoke test wajib sebelum regression suite. Jika smoke gagal, batch regression ditunda dan alert dikirim.
  • Regression suite dapat dikonfigurasi hanya pada branch release atau saat ada tag karena durasinya lebih panjang.

Untuk job queue, tambahkan langkah verifikasi bahwa worker horizon atau queue:work aktif di environment staging, lalu bandingkan job count sebelum dan sesudah deploy untuk mendeteksi job yang tersendat.

Monitoring hasil test dan menangani suite bermasalah

Monitoring hasil testing membantu memahami tren flaky. Simpan metrik hasil test di sistem observability (misalnya Prometheus atau Grafana) dengan menulis log kesalahan ke file yang diambil oleh collector. Kirim juga notifikasi Slack/Teams jika contract atau smoke test gagal.

Jika regression suite menjadi sumber false negatif, gunakan strategi rollback atau disabled gate:

  • Rollback berarti revert commit terakhir dan analisa log para error. Pastikan git revert terjadi sebelum re-run pipeline.
  • Penonaktifan suite (mode degraded) cocok saat regression suite mengalami downtime eksternal. Gunakan flag seperti ENABLE_REGRESSION_SUITE=false di pipeline CI agar hanya contract dan smoke yang dijalankan sementara tim menyelidiki.

Catat juga versi queue worker dan queue timeout di monitoring. Jika job queue selalu gagal pada stage tertentu, periksa backlog dan optimasi job (misalnya limit concurrency atau extend timeout) sebelum menganggap itu flaky test.

Tips mengurangi false positive

  • Stabilkan data test: Gunakan seed dan factory deterministik sehingga test tidak gagal karena data berubah.
  • Mock dependensi eksternal: Tutup panggilan HTTP dan job queue nyata dengan fake service agar test tidak bergantung ke layanan luar yang tidak stabil.
  • Isolasi test: Pastikan contract, smoke, dan regression berjalan di environment terpisah (misalnya contract di sqlite memory, regression di database testing berlapis) agar satu suite tidak mempengaruhi yang lain.
  • Cek timeout dan retry: Gunakan built-in mekanisme Laravel untuk retry (misalnya retry(3)) pada job queue supaya fluktuasi jaringan tidak langsung membuat test gagal.
  • Verifikasi gating secara manual: Sesekali jalankan regression suite secara lokal sebelum push untuk mengetahui apakah ada flake yang muncul hanya di pipeline.

Dengan menyusun workflow verifikasi berganda seperti ini, tim akan mendapatkan sinyal kegagalan yang lebih jelas, mengurangi regression, dan memastikan API serta job queue tetap sehat saat menghadapi perubahan baru.