Belajar Cypress - Custom Plugins & Extensions

#Pendahuluan

Setiap project punya kebutuhan yang tidak tercakup Cypress secara bawaan. Episode 18 membahas ekosistem plugin: memakai plugin komunitas, membuat plugin custom, memperluas commands dan task APIs, serta menyusun pola plugin yang bisa dipakai ulang lintas project.

Plugin adalah garis antara suite yang kaku dan suite yang dibangun sesuai kebutuhan tim.

#Menggunakan Cypress Plugins dan Community Modules

#Mencari dan Memasang Plugin

Ekosistem plugin Cypress dikatalogkan di situs resmi dan npm. Pola pemasangannya konsisten:

npm install -D cypress-file-upload

npm install -D cypress-file-upload menambahkan plugin upload. Sebagian plugin berupa command yang di-import di support, sebagian berupa modul Node yang didaftarkan di konfigurasi.

#Mendaftarkan Plugin di Konfigurasi

Plugin level Node didaftarkan lewat blok setupNodeEvents:

Mendaftarkan plugin di setupNodeEvents

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require("cypress-watch-and-reload")(on, config);
      return config;
    },
  },
});

setupNodeEvents(on, config) adalah titik masuk plugin sisi Node. Fungsi on dipakai plugin untuk mendaftarkan event handler; objek config boleh diubah dan dikembalikan.

#Membuat Plugin Custom

#Plugin Sisi Node dengan Task API

Plugin custom paling umum memakai task API — memanggil kode Node dari browser:

Mendaftarkan task custom

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        seedDatabase() {
          return seedDatabase();
        },
      });
    },
  },
});

on("task", { seedDatabase() { ... } }) mendaftarkan task bernama seedDatabase. Task ini bisa dipanggil dari test dengan cy.task("seedDatabase") seperti yang kita singgung di episode 10.

#Task Sederhana yang Berguna

Contoh task yang bisa langsung dipakai: mengembalikan nilai yang konsisten dari sisi Node:

Task untuk data uji

on("task", {
  timestampSekarang() {
    return Date.now();
  },
});

timestampSekarang() mengembalikan waktu server. Task semacam ini membuat test bisa memakai nilai yang konsisten dari sisi Node, bukan dari browser yang bisa disetel ulang.

#Extending Commands dan Task APIs

#Memperluas Custom Commands

Command Cypress dan task API saling melengkapi: command berjalan di browser, task di Node. Gabungkan keduanya untuk helper yang kuat:

Command yang memanggil task

Cypress.Commands.add("seedDanKunjungi", (fixtureName) => {
  cy.task("seedDatabase", fixtureName);
  cy.visit("/");
});

cy.task("seedDatabase", fixtureName) mengirim argumen ke task Node. Command seedDanKunjungi mengemas pola siapkan data lalu buka halaman menjadi satu panggilan — komposisi command dan task.

#Menjaga Task Tetap Aman

Task berjalan di Node dengan akses sistem file dan environment. Batasi apa yang bisa dipanggil task — jangan pernah menerima path atau perintah arbitrer dari spec:

Task dengan whitelist

on("task", {
  readFixture(name) {
    const whitelist = ["produk", "users"];
    if (!whitelist.includes(name)) {
      throw new Error("fixture tidak diizinkan");
    }
    return readFile(`cypress/fixtures/${name}.json`, "utf-8");
  },
});

whitelist.includes(name) membatasi nama fixture yang boleh dibaca. Memvalidasi input task mencegah spec yang dikompromikan menjalankan operasi berbahaya di Node.

#Reusable Plugin Patterns

#Struktur Plugin yang Dapat Dipakai Ulang

Plugin yang baik bisa dipindahkan antar project. Pisahkan sebagai modul tersendiri:

Struktur plugin reusable

const { defineConfig } = require("cypress");
const seedPlugin = require("./plugins/seed");
 
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      seedPlugin(on, config);
      return config;
    },
  },
});

require("./plugins/seed") memuat modul plugin yang terpisah. seedPlugin(on, config) mendaftarkan task dari modul tersebut — pola ini membuat plugin bisa dibagikan dan diuji sendiri.

#Dokumentasi dan Versi

Berikan plugin custom dokumentasi singkat: apa yang didaftarkan, argumen yang diterima, dan contoh pemakaian. Jika plugin dipakai lintas project, rilis sebagai package npm dengan versioning sendiri agar perubahan tidak mengejutkan tim lain.

#Penutup

Episode 18 membuka pintu ekosistem: memakai plugin komunitas, membuat plugin custom melalui task API dan setupNodeEvents, memperluas commands dan task, serta menyusun pola plugin yang bisa dipakai ulang dengan validasi dan dokumentasi.

Inti yang harus dibawa pulang:

• Plugin command di-import di support; plugin Node didaftarkan di setupNodeEvents.
• Task API memanggil kode Node dari browser lewat cy.task.
• Task bisa menerima argumen; kombinasikan dengan custom commands.
• Validasi input task agar operasi Node tetap aman.
• Pisahkan plugin sebagai modul agar bisa dipakai ulang lintas project.

Di episode 19 selanjutnya kita akan membahas operational readiness dan runbooks — runbook untuk flaky tests dan environment drift, incident response untuk failing CI runs, menjaga test coverage dan health, serta team ownership dan maintenance routines.