Panduan pengujian plugin

Penulis plugin menulis dan menguji plugin Lua sepenuhnya di Lua - tidak diperlukan rantai alat Go. Pengujian ditempatkan bersama dengan plugin di bawah init_test.lua dan dijalankan melalui inspector-sbomgen plugin test perintah.

Untuk penulisan plugin umum, lihat. Panduan pengembang plugin Untuk katalog fungsi lengkap (termasuk testing.* API), lihatReferensi API Plugin.

-- init_test.lua (next to init.lua)
function test_discovers_curl_version()
    local result = testing.scan_directory("_testdata/include/curl")
    testing.assert_equals(1, #result.findings)
    testing.assert_equals("libcurl", result.findings[1].name)
    testing.assert_equals("8.14.1", result.findings[1].version)
end

# Run every test under a plugin directory
inspector-sbomgen plugin test --path ./my-plugins

# Verbose output — show each test name and result
inspector-sbomgen plugin test --path ./my-plugins -v

Mulai Cepat

1. Buat file pengujian

Tempatkan di init_test.lua sebelah plugin Andainit.lua:

my-plugin/
├── discovery/cross-platform/extra-ecosystems/curl/
│   ├── init.lua
│   ├── init_test.lua
│   └── _testdata/
│       └── include/curl/curlver.h

2. Tulis fungsi uji

Setiap fungsi global yang dimulai dengan test_ ditemukan dan dijalankan:

function test_finds_libcurl()
    local result = testing.scan_directory("_testdata/include/curl")
    testing.assert_equals(1, #result.findings)
    testing.assert_equals("libcurl", result.findings[1].name)
end

function test_no_findings_for_empty_dir()
    local result = testing.scan_directory("_testdata/empty")
    testing.assert_equals(0, #result.findings)
end

3. Jalankan tes

inspector-sbomgen plugin test --path ./my-plugin

Tata Letak Direktori

Struktur plugin

File uji dan data uji ditempatkan bersama dengan plugin:

my-plugins/
├── discovery/
│   └── cross-platform/
│       └── extra-ecosystems/
│           └── curl/
│               ├── init.lua          # plugin source
│               ├── init_test.lua     # test file
│               └── _testdata/        # test fixtures
│                   ├── include/curl/curlver.h
│                   └── binaries/unix/curl
├── collection/
│   └── cross-platform/
│       └── extra-ecosystems/
│           └── curl-installation/
│               ├── init.lua
│               └── init_test.lua

Uji penamaan file

• Default: di init_test.lua sebelah plugin init.lua

• Beberapa file uji per plugin: pencocokan *_test.lua file apa pun ditemukan

• Contoh:init_test.lua,parsing_test.lua, discovery_test.lua

Data uji: _testdata/

Data uji tinggal di _testdata/ sebelah plugin. Garis bawah utama adalah konvensi yang membuat perlengkapan terpisah secara visual dari sumber plugin; plugin test perintah tidak turun ke _testdata/ saat mencari *_test.lua file, sehingga perlengkapan tidak pernah disalahartikan sebagai file uji.

Perlengkapan referensi file uji dengan jalur relatif:

local result = testing.scan_directory("_testdata/include/curl")

Jalur diselesaikan relatif terhadap direktori yang berisi file uji.

testing.*API

Fungsi Pindai

Setiap fungsi pemindaian membuat artefak, menjalankan pipeline discovery → collection plugin, dan mengembalikan temuan. Penulis pengujian tidak pernah secara manual membuat artefak, bus acara, atau pendaftar.

-- Scan a directory of test fixtures (most common)
local result = testing.scan_directory("_testdata/curl")

-- Alias for scan_directory (archives use the same backend)
local result = testing.scan_archive("_testdata/app.tar.gz")

-- Scan as a localhost artifact
local result = testing.scan_localhost("_testdata/curl")

-- Scan a compiled binary
local result = testing.scan_binary("_testdata/binaries/curl")

-- Scan a mounted volume
local result = testing.scan_volume("_testdata/volume-root")

-- Scan a container image tarball
local result = testing.scan_container("_testdata/images/alpine.tar")

Setiap fungsi pemindaian:

• Membuat artefak baru untuk setiap panggilan (tidak ada kebocoran status di antara panggilan)

• Hanya memuat pasangan koleksi discovery + plugin saat ini

• Mengembalikan tabel hasil

Tabel Hasil

result.findings              -- array of finding tables
result.findings[1].name      -- package name (string)
result.findings[1].version   -- package version (string)
result.findings[1].purl      -- package URL (string)
result.findings[1].component_type -- component type (string)
result.findings[1].properties    -- table<string, string>
result.findings[1].children      -- array of nested finding tables (same shape)

Pernyataan

-- Equality
testing.assert_equals(expected, actual, message?)
testing.assert_not_equals(expected, actual, message?)

-- Truthiness
testing.assert_true(value, message?)
testing.assert_false(value, message?)

-- Nil checks
testing.assert_nil(value, message?)
testing.assert_not_nil(value, message?)

-- String
testing.assert_contains(haystack, needle, message?)
testing.assert_matches(string, pattern, message?)

-- Tables
testing.assert_length(table, expected_length, message?)

-- Control flow
testing.fail(message)    -- immediately fail the current test
testing.skip(message)    -- skip the current test (not a failure)

sbomgen.*API standar

sbomgen.*API lengkap (file I/O, regex, info sistem, logging, dll.) Tersedia dalam file pengujian, sama seperti di plugin produksi. Namun, sbomgen.* fungsi yang memerlukan artefak (misalnya,sbomgen.read_file()) hanya berfungsi di dalam testing.scan_* panggilan balik — fungsi tersebut tidak tersedia di tingkat atas fungsi pengujian.

Menjalankan Tes

# Run all tests under a plugin directory
inspector-sbomgen plugin test --path ./my-plugins

# Filter by regex pattern
inspector-sbomgen plugin test --path ./my-plugins --run curl

# Verbose output (show each test name and result)
inspector-sbomgen plugin test --path ./my-plugins -v

# Stop on the first failing test
inspector-sbomgen plugin test --path ./my-plugins --fail-fast

--pathBendera menerima direktori root plugin (berisi discovery/ and/or collection/) atau direktori ekosistem tunggal (terdeteksi otomatis). Perintah keluar bukan nol jika ada tes yang gagal.

Format output

Dengan-v, setiap tes mencetak === RUN garis dan garis hasil (--- PASS,--- FAIL, atau--- SKIP). Tanpa-v, hanya tes yang gagal dicetak. Baris ringkasan dicetak di bagian akhir:

=== RUN   curl/discovery/init_test/test_discovers_libcurl_header
--- PASS: curl/discovery/init_test/test_discovers_libcurl_header (0.04s)
=== RUN   curl/discovery/init_test/test_discovers_curl_binary_unix
--- PASS: curl/discovery/init_test/test_discovers_curl_binary_unix (0.04s)
=== RUN   curl/discovery/init_test/test_no_findings_for_unrelated_files
--- PASS: curl/discovery/init_test/test_no_findings_for_unrelated_files (0.04s)
ok    3 tests passed

Pembantu Plugin Pengujian

File pengujian dimuat ke Lua VM yang sama dengan plugin. init.lua Fungsi global yang didefinisikan dalam plugin dapat dipanggil dari pengujian. Untuk menguji fungsi pembantu, paparkan mereka sebagai global atau dalam tabel modul:

-- init.lua
M = {}
function M.parse_version(raw)
    return string.match(raw, "(%d+%.%d+%.%d+)")
end

function collect(file_path)
    local ver = M.parse_version(...)
    -- ...
end

-- init_test.lua
function test_parse_version_extracts_semver()
    testing.assert_equals("1.2.3", M.parse_version("curl/1.2.3"))
end

function test_parse_version_returns_nil_for_garbage()
    testing.assert_nil(M.parse_version("not-a-version"))
end

Fungsi yang local init.lua dideklarasikan tidak terlihat oleh file uji. Ini adalah pelingkupan Lua standar.

Perilaku dan Invarian

VM bersama, status bersama

Fungsi uji dalam satu file berbagi VM Lua. Variabel global yang ditetapkan dalam satu test_* fungsi terlihat oleh fungsi selanjutnya. Jika dua fungsi mendefinisikan global yang sama, yang kedua menimpa yang pertama. Setiap tes harus mandiri dan tidak bergantung pada keadaan dari tes lain.

Perintah eksekusi non-deterministik

Fungsi pengujian ditemukan dengan mengulangi tabel global Lua, yang menggunakan pemesanan berbasis hash. Pengujian tidak dijamin berjalan sesuai urutan yang ditentukan. Jangan menulis tes yang bergantung pada perintah eksekusi.

Artefak segar per panggilan pemindaian

Setiap panggilan ke testing.scan_directory() (atau fungsi pemindaian apa pun) menciptakan artefak yang sama sekali baru. Tidak ada status yang dilakukan antara pemindaian panggilan dalam tes atau di seluruh tes.

Pemuatan plugin

Plugin dimuat sekali per uji coba, tidak sekali per file pengujian. Pelari uji memuat semua plugin dari sistem file yang disediakan, lalu mencocokkan setiap file pengujian dengan plugin VM yang sesuai berdasarkan fase, platform, kategori, dan ekosistem.

Perilaku penegasan

Ketika pernyataan gagal, kegagalan dicatat tetapi fungsi pengujian terus mengeksekusi — pernyataan dan pernyataan berikutnya masih berjalan. Jika lebih dari satu pernyataan gagal dalam tes yang sama, kegagalan terbaru adalah pesan yang dilaporkan dalam ringkasan; kegagalan sebelumnya ditimpa. Untuk menghentikan pengujian pada kegagalan pertamanya, kembali dari fungsi setelah pernyataan gagal (atau gunakan testing.fail() di dalam kondisional).

Batasan

• localfungsi tidak dapat diuji. Hanya fungsi global dari init.lua yang terlihat ke file pengujian. Paparkan pembantu melalui tabel modul jika mereka membutuhkan pengujian.

• Tidak ada sbomgen.* file I/O di luar panggilan pemindaian. Fungsi seperti sbomgen.read_file() memerlukan konteks artefak, yang hanya ada di dalam testing.scan_* panggilan.

• Tidak ada kait siklus hidup. Tidak adabefore_each,after_each,setup, atauteardown. Setiap fungsi pengujian mengelola statusnya sendiri.

• Tidak ada batas waktu tes. Fungsi pengujian yang loop selamanya akan menggantung pelari.

• Tidak ada pelaporan cakupan. Tidak ada cara untuk mengukur garis mana init.lua yang dilakukan.

• Tidak ada tolok ukur. Kerangka pengujian tidak mendukung tolok ukur kinerja.

Tanggung Jawab Pengembang

Saat menulis plugin Lua baru

• Buat init_test.lua di sebelah Anda init.lua

• Buat _testdata/ dengan perlengkapan minimal yang menggunakan logika plugin Anda

• Menulis test_* fungsi yang mencakup: deteksi berhasil, ekstraksi versi, kasus tepi, dan skenario tanpa kecocokan

• Jalankan pengujian secara lokal sebelum mengirimkan

Pedoman data uji

• Pertahankan perlengkapan minimal - gunakan file terkecil yang menjalankan perilaku

• Hindari melakukan binari besar _testdata/ ketika perlengkapan teks kecil sudah cukup

• Setiap plugin _testdata/ harus mandiri - tidak ada referensi ke file di luar direktori plugin