プラグインテストガイド

プラグイン作成者は、完全に Lua で Lua プラグインを記述してテストします。Go ツールチェーンは必要ありません。テストは のプラグインと共存init_test.luaし、 inspector-sbomgen plugin test コマンドを介して実行されます。

一般的なプラグインの作成については、「」を参照してくださいプラグイン開発者ガイド。完全な関数カタログ ( testing.* API を含む) については、「」を参照してくださいプラグイン API リファレンス。

-- 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

クイックスタート

1. テストファイルを作成する

プラグインの init_test.luaの横に を配置しますinit.lua。

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

2. テスト関数の書き込み

で始まるすべてのグローバル関数test_が検出され、実行されます。

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. テストを実行する

inspector-sbomgen plugin test --path ./my-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

テストファイルの命名

• デフォルト: プラグインinit_test.luaの init.lua

• プラグインごとに複数のテストファイル: ファイルマッチング*_test.luaが検出されました

• 例: init_test.lua、parsing_test.lua、discovery_test.lua

テストデータ: _testdata/

テストデータはプラグイン_testdata/の横にあります。先頭のアンダースコアは、フィクスチャをプラグインソースから視覚的に分離する規則です。*_test.luaファイルを検索する_testdata/ときに plugin test コマンドが に下がらないため、フィクスチャがテストファイルと間違えられることはありません。

テストファイルは、相対パスを持つフィクスチャを参照します。

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

パスは、テストファイルを含むディレクトリに対して解決されます。

testing.* API

スキャン関数

各スキャン関数はアーティファクトを作成し、プラグインの検出 → コレクションパイプラインを実行し、検出結果を返します。テスト作成者がアーティファクト、イベントバス、またはレジストリを手動で作成することはありません。

-- 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")

各スキャン関数:

• 呼び出しごとに新しいアーティファクトを作成します (呼び出し間で状態リークなし)

• 現在のプラグインの検出とコレクションのペアのみをロードします

• 結果テーブルを返します。

結果テーブル

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)

アサーション

-- 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

完全な sbomgen.* API (ファイル I/O、正規表現、システム情報、ログ記録など) は、本番プラグインと同様に、テストファイルで使用できます。ただし、アーティファクトを必要とするsbomgen.*関数 (例: sbomgen.read_file()) はtesting.scan_*コールバック内でのみ機能します。テスト関数の最上位レベルでは使用できません。

テストを実行する

# 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

--path フラグは、プラグインルートディレクトリ ( discovery/および/または を含むcollection/) または単一のエコシステムディレクトリ (自動検出) を受け入れます。テストが失敗すると、コマンドはゼロ以外の値で終了します。

出力形式

では-v、各テストは=== RUN行と結果行 (--- PASS、--- FAIL、または ) を出力します--- SKIP。がない場合-v、失敗したテストのみが出力されます。概要行が末尾に出力されます。

=== 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

プラグインヘルパーのテスト

テストファイルは、プラグインの と同じ Lua VM にロードされますinit.lua。プラグインで定義されたグローバル関数は、テストから呼び出すことができます。ヘルパー関数をテストするには、それらをグローバルとして、またはモジュールテーブルに公開します。

-- 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

local で宣言された関数init.luaは、テストファイルに表示されません。これは標準の Lua スコープです。

動作と不変

共有 VM、共有状態

1 つのファイル内のテスト関数は Lua VM を共有します。1 つのtest_*関数に設定されたグローバル変数は、後続の関数に表示されます。2 つの関数が同じグローバルを定義する場合、2 番目の関数は最初の関数を上書きします。各テストは自己完結型で、他のテストの状態に依存しないようにする必要があります。

非決定的な実行順序

テスト関数は、ハッシュベースの順序を使用する Lua のグローバルテーブルを繰り返すことで検出されます。テストは定義された順序で実行されるとは限りません。実行順序に依存するテストを記述しないでください。

スキャン呼び出しあたりの新しいアーティファクト

(testing.scan_directory()またはスキャン関数) を呼び出すたびに、まったく新しいアーティファクトが作成されます。テスト内のスキャン呼び出し間、またはテスト間で状態が伝達されることはありません。

プラグインのロード

プラグインは、テストファイルごとに 1 回ではなく、テスト実行ごとに 1 回ロードされます。テストランナーは、提供されたファイルシステムからすべてのプラグインをロードし、フェーズ、プラットフォーム、カテゴリ、エコシステムごとに各テストファイルを対応するプラグイン VM と照合します。

アサーション動作

アサーションが失敗した場合、失敗は記録されますが、テスト関数は実行を継続します。後続のアサーションとステートメントは引き続き実行されます。同じテストで複数のアサーションが失敗した場合、最新の失敗は概要で報告されたメッセージです。以前の失敗は上書きされます。最初の失敗時にテストを停止するには、失敗したアサーションの後に関数から を返します (または条件付きtesting.fail()で を使用します）。

制限事項

• local 関数はテストできません。テストファイルにはinit.lua、 のグローバル関数のみが表示されます。テストが必要な場合は、モジュールテーブルを介してヘルパーを公開します。

• スキャン呼び出しの外部にsbomgen.*ファイル I/O がない。のような関数には、testing.scan_*呼び出し内のみに存在するアーティファクトコンテキストsbomgen.read_file()が必要です。

• ライフサイクルフックはありません。before_each、、after_each、setupまたは はありませんteardown。各テスト関数は独自の状態を管理します。

• テストタイムアウトはありません。永久にループするテスト関数は、ランナーをハングします。

• カバレッジレポートはありません。どの行が実行されinit.luaたかを測定する方法はありません。

• ベンチマークはありません。テストフレームワークはパフォーマンスベンチマークをサポートしていません。

開発者の責任

新しい Lua プラグインを記述する場合

• init_test.lua の横に を作成する init.lua

• プラグインのロジックを実行する最小限のフィクスチャ_testdata/で を作成する

• 検出の成功、バージョン抽出、エッジケース、一致しないシナリオをカバーするtest_*関数を記述する

• 送信する前にテストをローカルで実行する

テストデータのガイドライン

• フィクスチャを最小限に抑える — 動作を実行する最小のファイルを使用します。

• 小さなテキストフィクスチャで十分_testdata/である場合は、大きなバイナリを にコミットしない

• 各プラグインの は自己完結型_testdata/である必要があります。プラグインディレクトリ外のファイルへの参照はありません。