翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# プラグインテストガイド
<a name="sbomgen-plugin-testing-guide"></a>

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

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

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

## クイックスタート
<a name="sbomgen-plugin-testing-guide-quick-start"></a>

### 1. テストファイルを作成する
<a name="sbomgen-plugin-testing-guide-1-create-a-test-file"></a>

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

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

### 2. テスト関数の書き込み
<a name="sbomgen-plugin-testing-guide-2-write-test-functions"></a>

 で始まるすべてのグローバル関数`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. テストを実行する
<a name="sbomgen-plugin-testing-guide-3-run-tests"></a>

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

## ディレクトリレイアウト
<a name="sbomgen-plugin-testing-guide-directory-layout"></a>

### プラグイン構造
<a name="sbomgen-plugin-testing-guide-plugin-structure"></a>

 テストファイルとテストデータは プラグインと同じ場所にあります。

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

### テストファイルの命名
<a name="sbomgen-plugin-testing-guide-test-file-naming"></a>
+ デフォルト: プラグイン`init_test.lua`の `init.lua`
+ プラグインごとに複数のテストファイル: ファイルマッチング`*_test.lua`が検出されました
+ 例: `init_test.lua`、`parsing_test.lua`、`discovery_test.lua`

### テストデータ: `_testdata/`
<a name="sbomgen-plugin-testing-guide-test-data-testdata"></a>

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

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

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

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

## `testing.*` API
<a name="sbomgen-plugin-testing-guide-the-testing-api"></a>

### スキャン関数
<a name="sbomgen-plugin-testing-guide-scan-functions"></a>

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

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

 各スキャン関数: 
+ 呼び出しごとに新しいアーティファクトを作成します (呼び出し間で状態リークなし)
+ 現在のプラグインの検出とコレクションのペアのみをロードします
+ 結果テーブルを返します。

### 結果テーブル
<a name="sbomgen-plugin-testing-guide-result-table"></a>

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

### アサーション
<a name="sbomgen-plugin-testing-guide-assertions"></a>

```
-- 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
<a name="sbomgen-plugin-testing-guide-standard-sbomgen-api"></a>

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

## テストを実行する
<a name="sbomgen-plugin-testing-guide-running-tests"></a>

```
# 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/`) または単一のエコシステムディレクトリ (自動検出) を受け入れます。テストが失敗すると、コマンドはゼロ以外の値で終了します。

### 出力形式
<a name="sbomgen-plugin-testing-guide-output-format"></a>

 では`-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
```

## プラグインヘルパーのテスト
<a name="sbomgen-plugin-testing-guide-testing-plugin-helpers"></a>

 テストファイルは、プラグインの と同じ 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 スコープです。

## 動作と不変
<a name="sbomgen-plugin-testing-guide-behavior-and-invariants"></a>

### 共有 VM、共有状態
<a name="sbomgen-plugin-testing-guide-shared-vm-shared-state"></a>

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

### 非決定的な実行順序
<a name="sbomgen-plugin-testing-guide-non-deterministic-execution-order"></a>

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

### スキャン呼び出しあたりの新しいアーティファクト
<a name="sbomgen-plugin-testing-guide-fresh-artifact-per-scan-call"></a>

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

### プラグインのロード
<a name="sbomgen-plugin-testing-guide-plugin-loading"></a>

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

### アサーション動作
<a name="sbomgen-plugin-testing-guide-assertion-behavior"></a>

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

## 制限事項
<a name="sbomgen-plugin-testing-guide-limitations"></a>
+ **`local` 関数はテストできません。**テストファイルには`init.lua`、 のグローバル関数のみが表示されます。テストが必要な場合は、モジュールテーブルを介してヘルパーを公開します。
+ **スキャン呼び出しの外部に`sbomgen.*`ファイル I/O がない。**のような関数には、`testing.scan_*`呼び出し内のみに存在するアーティファクトコンテキスト`sbomgen.read_file()`が必要です。
+ **ライフサイクルフックはありません。**`before_each`、、`after_each`、`setup`または はありません`teardown`。各テスト関数は独自の状態を管理します。
+ **テストタイムアウトはありません。**永久にループするテスト関数は、ランナーをハングします。
+ **カバレッジレポートはありません。**どの行が実行され`init.lua`たかを測定する方法はありません。
+ **ベンチマークはありません。**テストフレームワークはパフォーマンスベンチマークをサポートしていません。

## 開発者の責任
<a name="sbomgen-plugin-testing-guide-developer-responsibilities"></a>

### 新しい Lua プラグインを記述する場合
<a name="sbomgen-plugin-testing-guide-when-writing-a-new-lua-plugin"></a>
+ `init_test.lua` の横に を作成する `init.lua`
+ プラグインのロジックを実行する最小限のフィクスチャ`_testdata/`で を作成する
+ 検出の成功、バージョン抽出、エッジケース、一致しないシナリオをカバーする`test_*`関数を記述する
+ 送信する前にテストをローカルで実行する

### テストデータのガイドライン
<a name="sbomgen-plugin-testing-guide-test-data-guidelines"></a>
+ フィクスチャを最小限に抑える — 動作を実行する最小のファイルを使用します。
+ 小さなテキストフィクスチャで十分`_testdata/`である場合は、大きなバイナリを にコミットしない
+ 各プラグインの は自己完結型`_testdata/`である必要があります。プラグインディレクトリ外のファイルへの参照はありません。