ibushimaruChrome Extension Test Framework
汎用的なChrome拡張機能テストフレームワーク - ブラウザ不要で高速な静的解析を実行
特徴
- 🚀 高速実行 - ブラウザ不要で100ms以下での実行
- 🔍 包括的な検証 - Manifest、セキュリティ、パフォーマンス、構造、多言語対応
- 📊 複数の出力形式 - コンソール、JSON、HTML、Markdown
- 🛠️ 拡張可能 - カスタムテストスイートとバリデーターの追加が可能
- 🌍 汎用性 - あらゆるChrome拡張機能に対応
- 🔧 CI/CD対応 - 終了コードによる自動化サポート
- 💡 詳細なエラーメッセージ - エラーコード、修正提案、コード例、ドキュメントリンク付き (v1.2.0+)
- 🔧 自動修正機能 - 一般的な問題を自動的に修正 (v1.3.0+)
- 👀 ウォッチモード - ファイル変更時の自動テスト (v1.4.0+)
- ⚡ 並列実行 - 複数のテストスイートを並列で実行 (v1.4.0+)
- 📋 プロファイル機能 - 事前定義された設定セットの利用 (v1.5.0+)
- 🔄 インクリメンタルテスト - 変更されたファイルのみテスト (v1.5.0+)
- 🛡️ 高度なセキュリティ分析 - APIキー検出、安全でないストレージ検出 (v1.7.0+)
- 📈 パフォーマンス分析 - メモリリーク、重い処理、DOM操作の検出 (v1.8.0+)
- ✅ Manifest V3完全対応 - 最新のChrome拡張機能仕様に準拠 (v1.8.0+)
インストール
npmからインストール（推奨）
⚠️ 重要: CLIツールとして使用する場合は、必ずグローバルインストールしてください：
# ✅ グローバルインストール（CLIコマンドとして使用）
npm install -g chrome-extension-test-framework
# 以下は特定の用途向け：
# ローカルインストール（package.jsonのscriptsで使用）
npm install chrome-extension-test-framework
# 開発依存としてインストール（CI/CDで使用）
npm install --save-dev chrome-extension-test-frameworkグローバルインストール後の確認:
# インストール確認
cext-test --version
# ヘルプ表示
cext-test --helpGitHubからインストール
# 最新版をインストール
npm install git+https://github.com/ibushimaru/chrome-extension-test-framework.git
# 特定のバージョンをインストール
npm install git+https://github.com/ibushimaru/chrome-extension-test-framework.git#v1.0.1クイックスタート
サンプル拡張機能でテスト
このフレームワークには、動作を確認できるサンプル拡張機能が含まれています：
# 良い例（すべてのテストに合格）
cext-test samples/good-extension
# 悪い例（多くの問題を検出）
cext-test samples/bad-extension
# 最小限の例
cext-test samples/minimal-extension
# すべてのサンプルをテスト
node samples/test-all.js詳細はsamples/README.mdを参照してください。
使い方
CLIとして使用
# 現在のディレクトリをテスト
cext-test
# 特定の拡張機能をテスト
cext-test /path/to/extension
# 特定のテストスイートのみ実行
cext-test -s manifest,security
# カスタム出力形式
cext-test -o json,html -d ./reports
# 問題を自動修正
cext-test --fix
# 修正内容をプレビュー（実際には変更しない）
cext-test --fix-dry-run
# ウォッチモード（ファイル変更時に自動実行）
cext-test --watch
# 並列実行（高速化）
cext-test --parallel
# 変更されたファイルのみテスト
cext-test --changed
# プロファイルを使用 (v1.9.0+)
cext-test --profile development # 開発用（緩いルール）
cext-test --profile production # 本番用（厳しいルール）
cext-test --profile quick # 高速チェック
# 現在の設定を表示 (v1.9.0+)
cext-test --show-config
# 詳細モード
cext-test --verbose
# プログレス表示を無効化
cext-test --no-progress
# ヘルプを表示
cext-test --helpプログラムとして使用
const ChromeExtensionTestFramework = require('chrome-extension-test-framework');
// クイックテスト
ChromeExtensionTestFramework.test('/path/to/extension');
// カスタム設定でテスト
const framework = new ChromeExtensionTestFramework({
extensionPath: './my-extension',
output: {
format: ['console', 'json'],
directory: './test-results'
}
});
// ビルトインテストを使用
framework.useBuiltinTests();
// カスタムテストスイートを追加
framework.addSuite({
name: 'My Custom Tests',
tests: [
{
name: 'Custom validation',
test: async (config) => {
// カスタム検証ロジック
}
}
]
});
// テスト実行
const results = await framework.run();自動修正機能 (v1.3.0+)
このフレームワークは、一般的な問題を自動的に修正する機能を提供します：
修正可能な問題
manifest.json
- Manifest V2からV3への移行
- 不正なバージョン形式の修正
- 必須フィールドの追加
- 長すぎる名前・説明の短縮
- CSPの形式変換とunsafe-eval/unsafe-inlineの削除
- browser_actionからactionへの変換
ファイル名
- スペースをアンダースコアに置換
- 特殊文字の削除
- 大文字を小文字に変換（README、LICENSE、CHANGELOGを除く）
使用方法
# 修正内容をプレビュー
cext-test --fix-dry-run
# 実際に修正を適用
cext-test --fix
# 詳細な修正内容を表示
cext-test --fix --verbose修正例
$ cext-test samples/broken-extension --fix
🔧 Running auto-fix on: samples/broken-extension
📊 Auto-fix Summary:
Total fixes: 11
By type:
- UPDATE_FIELD: 1
- FIX_VERSION: 1
- TRUNCATE_FIELD: 2
- MIGRATE_V2_TO_V3: 2
- RENAME_FILE: 2
- MIGRATE_CSP: 1
- REMOVE_UNSAFE: 2
✅ Fixes applied successfully!
💡 Run tests again to verify the fixesビルトインテストスイート
1. Manifest Validation (強化版)
- ✅ Manifest V3準拠チェック
- ✅ 必須フィールドの存在確認
- ✅ バージョン形式の検証
- ✅ アイコンファイルの存在確認
- ✅ Service Worker設定の検証
- 🆕 chrome.action API検証（browser_action廃止警告）
- 🆕 Declarative Net Request API検証
- 🆕 chrome.scripting API検証（executeScript/insertCSS廃止警告）
- 🆕 最小Chromeバージョン検証（v88以上推奨）
2. Security Validation (v1.7.0で大幅強化)
- ✅ CSP（Content Security Policy）の検証
- ✅ 外部スクリプトの検出
- ✅ eval()使用の検出
- ✅ HTTPS強制の確認
- ✅ 最小権限の原則チェック
- 🆕 詳細な権限分析 (v1.9.0+)
- 各権限の具体的な説明を表示
- 危険度レベルで分類（high/moderate/low）
- 権限使用の推奨事項を提示
- 🆕 高度なセキュリティ分析 (SecurityAnalyzer)
- APIキー・シークレットの検出（30種類以上のパターン）
- 安全でないストレージパターン検出
- 危険なJavaScriptパターン検出（eval、Function構造体）
- XSS脆弱性検出
- 安全でない通信パターン検出
- 🆕 Chrome Storage API使用分析 (StorageAnalyzer)
- localStorage/sessionStorage使用警告
- chrome.storage APIへの移行提案
3. Performance Validation (v1.8.0で大幅強化)
- ✅ ファイルサイズの制限チェック
- ✅ 画像最適化の確認
- ✅ JavaScript/CSSの最適化
- ✅ アニメーションパフォーマンス
- 🆕 包括的なパフォーマンス分析 (PerformanceAnalyzer)
- メモリリークパターン検出（15種類以上）
- 重い計算処理検出（ネストループ、再帰）
- 過剰なDOM操作検出
- バンドルサイズと最適化分析
- CSSパフォーマンス問題検出
- 重複コード検出
4. Structure Validation (v1.6.0で強化)
- ✅ ディレクトリ構造の検証
- ✅ ファイル命名規則
- ✅ 開発用ファイルの除外確認
- ✅ モジュール構造の検証
- ✅ 重複ファイルの検出
- 🆕 ファイル検証の強化
- FileSizeAnalyzer: 個別ファイル・拡張子別のサイズ分析
- FileNameValidator: プラットフォーム互換性、特殊文字検出
- DirectoryAnalyzer: ディレクトリ深度・複雑度分析
5. Localization Validation
- ✅ 多言語対応の構造確認
- ✅ messages.jsonの形式検証
- ✅ ロケール間の一貫性チェック
- ✅ RTL言語サポートの確認
- ✅ 国際化APIの使用状況
- 🆕 ハードコードされたテキストの検出
- 🆕 プレースホルダー使用の検証
カスタムテストの作成
TestSuiteクラスを使用
const { TestSuite } = require('chrome-extension-test-framework');
class MyTestSuite extends TestSuite {
constructor(config) {
super({
name: 'My Custom Suite',
description: 'カスタム検証スイート'
});
this.setupTests();
}
setupTests() {
this.test('My test', async (config) => {
// テストロジック
const manifest = await this.loadManifest(config);
if (!manifest.my_field) {
throw new Error('my_field is required');
}
});
}
}TestCaseクラスを使用
const { TestCase } = require('chrome-extension-test-framework');
// 簡単なアサーション
const myTest = TestCase.assertion(
'Check custom field',
async (config) => {
const manifest = require(path.join(config.extensionPath, 'manifest.json'));
return manifest.custom_field === 'expected_value';
}
);
// 期待値の比較
const versionTest = TestCase.expect(
'Version check',
async (config) => {
const manifest = require(path.join(config.extensionPath, 'manifest.json'));
return manifest.version;
},
'1.0.0'
);設定ファイル
設定の優先順位
設定は以下の順序で適用されます（後のものが前のものを上書き）：
- デフォルト設定 - フレームワークの組み込み設定
- 設定ファイル -
.cextrc.json、cext-test.config.jsなど - プロファイル設定 -
--profileオプションで指定 - CLIオプション - コマンドライン引数で指定
ファイルフィルタリングの順序
- exclude - 完全に除外（スキャンもテストもされない）
- ignorePatterns - 特定のテストでは無視（将来実装）
- allowedDevFiles - 開発ファイルチェックで許可される
.extensionignore ファイル (v1.16.1+)
拡張機能のルートディレクトリに .extensionignore ファイルを作成することで、プロジェクト固有の除外パターンを指定できます：
# .extensionignore の例
# デザインアセット
design-assets/
mockups/
*.psd
*.ai
# ドキュメント
docs/
*.md
# 開発ツール
.vscode/
.idea/
# カスタムビルドファイル
build-scripts/
*.config.local.js.gitignoreと同様の記法をサポート#で始まる行はコメント- 空行は無視される
- 設定ファイルの
excludeパターンと併用可能
設定ファイルの作成
cext-test.config.jsまたは.cextrc.jsonを作成:
VS Code での自動補完（v1.11.0+）
.cextrc.jsonでVS Codeの自動補完を有効にするには、ファイルの先頭に以下を追加：
{
"$schema": "./node_modules/chrome-extension-test-framework/.cextrc.schema.json",
// 以下、設定内容
}module.exports = {
extensionPath: './src',
output: {
format: ['console', 'json', 'html'],
directory: './test-reports',
filename: 'extension-test'
},
validation: {
manifest: true,
permissions: true,
csp: true,
icons: true,
locales: true
},
// 除外パターン (v1.9.0+)
exclude: [
'test/**',
'docs/**',
'*.test.js'
],
// console.log使用の閾値設定 (v1.9.0+)
consoleThresholds: {
development: 100, // 開発ファイルでの許容数
production: 10, // 本番コードでの許容数
test: Infinity // テストファイルでは無制限
},
// プロファイル設定 (v1.9.0+)
profile: 'development',
rules: [
// カスタムルール
],
timeout: 30000
};高度な機能
ウォッチモード (v1.4.0+)
ファイル変更を監視し、自動的にテストを再実行します。
# ウォッチモードで起動
cext-test --watch
# 特定のディレクトリのみ監視
cext-test --watch --watch-dirs src,manifest.json並列実行 (v1.4.0+)
複数のテストスイートを並列で実行し、テスト時間を短縮します。
# 並列実行（CPUコア数に基づく最適化）
cext-test --parallel
# ワーカー数を指定
cext-test --parallel --max-workers 4プロファイル機能 (v1.5.0+)
事前定義された設定セットを使用して、特定の観点でテストを実行します。
# セキュリティ重視のテスト
cext-test --profile security-focused
# パフォーマンス重視のテスト
cext-test --profile performance
# 最小限のテスト
cext-test --profile minimal
# CI/CD向け設定
cext-test --profile ciインクリメンタルテスト (v1.5.0+)
前回のテスト以降に変更されたファイルのみをテストします。
# 変更されたファイルのみテスト
cext-test --changed
# 特定のコミット以降の変更をテスト
cext-test --changed --since HEAD~3テストシナリオ
フレームワークには40以上の実践的なテストシナリオが含まれています：
# エッジケースのテスト
cext-test test/scenarios/edge-cases/broken-manifest
cext-test test/scenarios/edge-cases/circular-dependencies
# セキュリティ問題のテスト
cext-test test/scenarios/security/api-keys
cext-test test/scenarios/security/eval-usage
# パフォーマンス問題のテスト
cext-test test/scenarios/performance/memory-leaks
cext-test test/scenarios/performance/large-dom
# 国際化のテスト
cext-test test/scenarios/i18n/missing-messages
cext-test test/scenarios/i18n/rtl-support
# Manifest V3互換性
cext-test test/scenarios/manifest-v3/deprecated-apis
cext-test test/scenarios/manifest-v3/modern-apisCI/CD統合
GitHub Actions
- name: Test Chrome Extension
run: |
npm install chrome-extension-test-framework
npx cext-test ./extension -o json
- name: Test with Security Focus
run: npx cext-test ./extension --profile security-focused
- name: Run Parallel Tests
run: npx cext-test ./extension --parallel -o json,htmlGitLab CI
test:
script:
- npm install chrome-extension-test-framework
- npx cext-test ./extension -o json,html
artifacts:
paths:
- test-results/
security-test:
script:
- npx cext-test ./extension --profile security-focused
only:
- merge_requestsAPI リファレンス
ChromeExtensionTestFramework
Constructor
new ChromeExtensionTestFramework(config)Methods
loadConfig(configPath)- 設定ファイルを読み込みaddSuite(suite)- テストスイートを追加useBuiltinTests()- ビルトインテストを使用use(plugin)- プラグインを使用addValidator(name, validator)- カスタムバリデーターを追加run()- テストを実行
TestSuite
Methods
test(name, testFn, options)- テストケースを追加skip(name, testFn, options)- スキップするテストを追加before(fn)- beforeAllフックを設定after(fn)- afterAllフックを設定
TestCase
Static Methods
TestCase.create(name, test, options)- 基本的なテストケース作成TestCase.assertion(name, assertion, options)- アサーションテストTestCase.expect(name, getter, expected, options)- 期待値比較テストTestCase.match(name, getter, pattern, options)- パターンマッチングテスト
トラブルシューティング
Q: ブラウザがインストールされていなくても動作しますか？
A: はい、このフレームワークは静的解析のみを使用するため、ブラウザは不要です。
Q: 実際のDOM操作やchrome.* APIのテストはできますか？
A: いいえ、このフレームワークは静的解析に特化しています。実際のブラウザ環境でのテストには別のツールが必要です。
Q: カスタムルールを追加するには？
A: addValidatorメソッドを使用するか、カスタムTestSuiteクラスを作成してください。
Q: テストが遅い場合は？
A: --parallelオプションを使用して並列実行を有効にするか、--changedオプションで変更されたファイルのみをテストしてください。
Q: 特定の警告を無視したい場合は？
A: .cextignoreファイルを作成し、除外したいファイルやディレクトリを指定してください。
バージョン履歴
v1.12.0 (2025-06-16)
- 🆕 拡張console検出（すべてのconsoleメソッド、間接使用検出）
- 🆕 --initコマンド（設定ファイルの初期化）
- 🆕 --quietフラグ（CI用の静かなモード）
- 🆕 エラー/警告の視覚的区別改善
v1.11.0 (2025-06-16)
- 🆕 詳細なエラーメッセージ（console.log検出時のファイルリスト表示）
- 🆕 開発ファイルサマリー表示（ディレクトリ別の集計）
- 🆕 設定デバッグモード（--debug-config）
- 🆕 JSON Schema提供（VS Code自動補完対応）
- 🆕 設定優先順位のドキュメント化
v1.10.1 (2025-06-16)
- 🔧 開発ファイル検出バグの修正（ExcludeManagerとの競合を解決）
- 🔧 console.log閾値チェックの修正
- 🆕 設定ファイルバリデーション機能
- 🆕 --show-configの拡張（実効設定の表示）
- 🆕 allowedDevFilesのglobパターン対応
v1.10.0 (2025-06-16)
- 🆕 設定ファイルの自動検出機能
- 🆕 プロファイル設定の詳細表示
- 🆕 開発ファイル検出ルールの柔軟化（allowedDevFiles設定）
- 🔧 設定ファイル読み込みの改善
v1.9.0 (2025-06-15)
- 🆕 PermissionsAnalyzer: 詳細な権限分析と説明
- 🆕 CodeComplexityAnalyzer: 正確なネストループ検出
- 🆕 プロファイル機能の改善（意味のある違いを実装）
- 🆕 --show-configオプション
- 🆕 console.log使用の閾値設定（設定ファイルから読み込み可能）
- 🔧 設定ファイルのexcludeパターンが正しく動作するよう修正
- 🔧 Triple nested loopsの誤検出を修正
v1.8.0 (2025-06-15)
- 🆕 PerformanceAnalyzer: 包括的なパフォーマンス分析
- 🆕 Manifest V3完全対応（chrome.action、declarativeNetRequest）
- 🆕 StorageAnalyzer: 非推奨ストレージAPI検出
v1.7.0 (2025-06-15)
- 🆕 SecurityAnalyzer: 高度なセキュリティ脆弱性検出
- 🆕 APIキー・シークレット検出（30種類以上のパターン）
v1.6.0 (2025-06-15)
- 🆕 FileSizeAnalyzer: 詳細なファイルサイズ分析
- 🆕 FileNameValidator: プラットフォーム互換性チェック
- 🆕 DirectoryAnalyzer: ディレクトリ構造分析
v1.5.0 (2025-06-15)
- 🆕 プロファイル機能
- 🆕 インクリメンタルテスト
- 🆕 設定ファイルサポート強化
v1.4.0 (2025-06-15)
- 🆕 ウォッチモード
- 🆕 並列実行
- 🆕 プログレスバー表示
v1.3.0 (2025-06-15)
- 🆕 自動修正機能（--fix）
- 🆕 ドライラン機能（--fix-dry-run）
v1.2.0 (2025-06-15)
- 🆕 詳細なエラーメッセージ
- 🆕 ErrorHandlerクラス
v1.1.0 (2025-06-15)
- 🆕 プログレス表示機能
- 🆕 verboseオプション
v1.0.0 (2025-06-14)
- 🎉 初回リリース
ライセンス
MIT
貢献
プルリクエストを歓迎します。大きな変更の場合は、まずissueを作成して変更内容を議論してください。
関連リンク
🔍 トラブルシューティング
行番号の不一致問題
大きな行番号（例：ファイルが663行しかないのに1413行目でエラー）が報告される場合は、診断モードを有効にして原因を特定できます：
# 診断モードでテストを実行
CEXT_DIAGNOSTIC=true cext-test your-extension-path診断モードでは以下の情報が表示されます：
- ファイルの実際の行数
- 計算された行番号
- ファイルのエンコーディング情報
- 行末文字の種類（CRLF/LF）
考えられる原因：
- バンドルされたファイル: WebpackやRollupでバンドルされたファイルは元のソースより大きくなります
- ソースマップ: 変換されたコードを分析している可能性があります
- ファイルの結合: 複数のファイルが結合されている可能性があります
その他の問題
問題が解決しない場合は、GitHub Issuesで報告してください。