Package Exports

chrome-extension-test-framework
chrome-extension-test-framework/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (chrome-extension-test-framework) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

GitHubからインストール

# 最新版をインストール
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 - 開発ファイルチェックで許可される

設定ファイルの作成

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

CI/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,html

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

API リファレンス