cli-testing-specialist 1.0.10

# CLI Testing Specialist

**言語**: [English](README.md) | [日本語](README.ja.md)

[![Crates.io](https://img.shields.io/crates/v/cli-testing-specialist)](https://crates.io/crates/cli-testing-specialist)
[![Downloads](https://img.shields.io/crates/d/cli-testing-specialist)](https://crates.io/crates/cli-testing-specialist)
[![License: MIT](https://img.shields.io/crates/l/cli-testing-specialist)](LICENSE)
[![Docs.rs](https://docs.rs/cli-testing-specialist/badge.svg)](https://docs.rs/cli-testing-specialist)

**バージョン**: 1.0.10
**最終更新**: 2025-11-16
**ステータス**: 本番環境対応
**ライセンス**: MIT

CLIツールの品質とセキュリティを自動検証する包括的なテストフレームワーク。Rustで構築され、最高のパフォーマンスと信頼性を提供します。

---

## 📑 目次

- [概要](#概要)
- [クイックスタート](#クイックスタート)
- [インストール](#インストール)
- [対象ツール](#対象ツール)
- [機能一覧](#機能一覧)
- [レポート形式](#レポート形式)
- [CI/CD統合](#cicd統合)
- [セキュリティ機能](#セキュリティ機能)
- [設定](#設定)
- [ファイル構造](#ファイル構造)
- [ライセンス](#ライセンス)
- [貢献](#貢献)
- [サポート](#サポート)

---

## 概要

CLI Testing Specialistは、CLIツールの包括的なテストスイートを自動生成・実行する本番環境対応のテストフレームワークです。

### 主要機能

- 🎯 **100%推定精度**: 実行ベース引数なし動作検出（v1.0.9）
- 🔒 **セキュリティテスト**: OWASP準拠の自動セキュリティスキャン
- ✅ **包括的検証**: 9テストカテゴリ、45-55テストケース（設定可能）
- 🎯 **入力検証**: 数値/パス/列挙型オプションの自動検証
- 🛡️ **破壊的操作テスト**: 確認プロンプト・安全性検証
- 🐚 **マルチシェル対応**: bash/zsh互換性テスト
- 📊 **詳細レポート**: Markdown/JSON/HTML/JUnit XML形式（インタラクティブHTMLフィルタリング）
- 🔄 **CI/CD対応**: GitHub Actions & GitLab CI統合例
- ⚡ **高性能**: Rust実装による超高速実行
- 📦 **単一バイナリ**: ランタイム依存関係なし

---

## クイックスタート

```bash
# 1. cli-testing-specialistをインストール
cargo install --git https://github.com/sanae-abe/cli-testing-specialist

# 2. CLIツールを解析
cli-testing-specialist analyze /usr/bin/curl -o curl-analysis.json

# 3. テストを生成（全カテゴリ）
cli-testing-specialist generate curl-analysis.json -o curl-tests -c all

# 4. テストを実行してレポート生成
cli-testing-specialist run curl-tests -f all -o curl-reports

# 5. HTMLレポートを表示
open curl-reports/curl-tests-report.html  # macOS
# xdg-open curl-reports/curl-tests-report.html  # Linux
```

---

## インストール

### Crates.ioからインストール（推奨）

```bash
# crates.ioからインストール
cargo install cli-testing-specialist

# インストール確認
cli-testing-specialist --version
```

### ソースからインストール

```bash
# GitHubからインストール
cargo install --git https://github.com/sanae-abe/cli-testing-specialist

# インストール確認
cli-testing-specialist --version
```

### 依存関係

#### テスト実行に必要
- **BATS (Bash Automated Testing System)**: テスト実行フレームワーク
  ```bash
  # macOS
  brew install bats-core

  # Ubuntu/Debian
  sudo apt-get install bats

  # 手動インストール
  git clone https://github.com/bats-core/bats-core.git
  cd bats-core
  sudo ./install.sh /usr/local
  ```

#### CLI Testing Specialistバイナリ
- **ランタイム依存関係なし**: 単一の自己完結型バイナリ

---

## 対象ツール

cli-testing-specialistは**標準的なCLIツール**向けに最適化されています。詳細は[docs/TARGET-TOOLS.md](./docs/TARGET-TOOLS.md)を参照してください。

### ✅ 高適用度（成功率70-90%）
- 標準的なCLIツール（curl、git、ls、cat）
- 標準的なオプション体系（--help、--version）
- 非インタラクティブツール
- **例**: package-publisher（Node.js CLI）

### ⚠️ 中適用度（成功率30-60%）
- 設定ファイル依存型ツール（commands.toml必須のcmdrun）
- カスタムUI実装（dialoguer、i18n対応のcldev）
- **推奨**: CI環境では「情報提供モード」を使用

### ❌ 低適用度（非推奨）
- インタラクティブシェル（mysql、psql、redis-cli）
- コンテナ管理（docker、podman）
- カスタムプロトコルを持つドメイン特化型ツール

### 🌐 言語サポート状況

**✅ テスト済み・サポート**:
- C/C++ (getopt、カスタムパーサー) - curl、git
- Rust (clap) - backup-suite、cmdrun、cldev
- Node.js (commander) - package-publisher
- **Python (argparse)** - test_argparse.py (16/16テスト、100%)

**⚠️ 未テスト（推定70-80%互換）**:
- **Go** (cobra、urfave/cli) - gh、kubectl、docker
- **Python** (click、typer) - 互換性見込み、未テスト
- **Ruby** (thor、gli)

**📋 テスト予定**: v1.1.0以降

**完全なガイドライン、言語別詳細、ベストプラクティスは[docs/TARGET-TOOLS.md](./docs/TARGET-TOOLS.md)を参照してください。**

### 🎯 検証済み成功事例

実環境で100%成功率を達成したCLIツール：

| ツール | 言語 | フレームワーク | テスト数 | 成功率 | 備考 |
|------|------|--------------|---------|--------|------|
| **package-publisher** | Node.js | commander.js | 17/17 | 100% | マルチコマンド対応のNPMパッケージ公開ツール |
| **backup-suite** | Rust | clap | 15/15 | 100% | 暗号化機能付きバックアップ自動化ツール |
| **cmdrun** | Rust | clap | 14/14 | 100% | TOML設定対応のコマンド実行ツール |
| **cldev** | Rust | clap | 15/15 | 100% | i18n対応の対話型開発CLI |

**フレームワーク互換性検証済み**:
- ✅ **commander.js** (Node.js): エラー時はexit code 1 (clapのexit 2と異なる)
- ✅ **clap** (Rust): 標準Unix終了コード (0=成功、1=エラー、2=使用法エラー)
- ✅ **カスタムパーサー**: getoptベースツール (curl、git)

---

## 機能一覧

| カテゴリ | 説明 | デフォルト |
|---------|------|---------|
| **基本検証** | ヘルプ、バージョン、終了コード | ✅ 有効 |
| **ヘルプ** | サブコマンドヘルプの包括的検証 | ✅ 有効 |
| **セキュリティ** | コマンドインジェクション、null byte、パストラバーサル | ✅ 有効 |
| **パス処理** | 特殊文字、深い階層、Unicode | ✅ 有効 |
| **マルチシェル** | bash/zsh互換性 | ✅ 有効 |
| **入力検証** | 数値/パス/列挙型オプション検証 | ✅ 有効 |
| **破壊的操作** | 確認プロンプト、--yes/--forceフラグ | ✅ 有効 |
| **パフォーマンス** | 起動時間、メモリ使用量 | ✅ 有効 |
| **ディレクトリ走査** | 大量ファイル、深いネスト、シンボリックリンクループ | ⚠️ オプトイン* |

\* ディレクトリ走査テストは、CI環境での問題（ディスク容量、リソース制限）を防ぐため、`--include-intensive`フラグで**オプトイン**です。

### テスト生成オプション

```bash
# デフォルト: ディレクトリ走査を除く全カテゴリ
cli-testing-specialist generate analysis.json -c all

# リソース集約型テストを含める
cli-testing-specialist generate analysis.json -c all --include-intensive

# 特定のカテゴリのみ
cli-testing-specialist generate analysis.json -c basic,security,path
```

---

## パフォーマンスベンチマーク

Rustで構築され、最大のパフォーマンスを実現 - **シェルベース実装の10倍以上高速**。

### ベンチマーク結果

Criterion.rsで本番環境ハードウェアにて測定：

| CLIツール | 複雑度 | 解析時間 | Bashプロトタイプ比 |
|----------|--------|---------|-------------------|
| curl | 小規模 (~50-100オプション) | **109 ms** | 11倍高速 |
| docker | 中規模 (~100+オプション) | **224 ms** | 11倍高速 |
| kubectl | 大規模 (100+サブコマンド) | **230 ms** | 17倍高速 |
| npm | 中規模 (多数のサブコマンド) | **329 ms** | 7倍高速 |

### 主要パフォーマンス指標

- **小規模CLI**: 1秒未満の解析 (~110ms for curl)
- **中規模CLI**: ~200-350ms範囲 (docker、kubectl、npm)
- **大規模CLI**: 100+サブコマンドでも500ms未満
- **メモリ使用量**: 一般的なワークロードで50MB未満
- **Bash比の高速化**: 11-17倍高速 (目標10倍を達成)

### 最適化技術

- **LTO**: リンク時最適化 (`lto = "thin"`)
- **並列処理**: rayonによる並行テスト生成
- **効率的I/O**: 64KBバッファのBufReader/BufWriter
- **バイナリストリップ**: 最小バイナリサイズ

**詳細なベンチマークと手法については[docs/PERFORMANCE.md](./docs/PERFORMANCE.md)を参照してください。**

---

## レポート形式

### 1. Markdown形式（`.md`）
GitHub/GitLab表示用の人間が読める形式

```bash
cli-testing-specialist run ./tests -f markdown -o ./reports
```

### 2. JSON形式（`.json`）
CI/CD統合とプログラム処理に最適

```bash
cli-testing-specialist run ./tests -f json -o ./reports

# jqで解析
jq '[.suites[].tests[] | select(.status == "passed")] | length' reports/tests-report.json
```

### 3. HTML形式（`.html`）
検索とフィルタリング機能付きのインタラクティブなブラウザ表示

```bash
cli-testing-specialist run ./tests -f html -o ./reports
open reports/tests-report.html
```

**HTML機能**:
- 📊 視覚的な統計カード（Passed/Failed/Skipped/Duration）
- 📈 成功率を表示するプログレスバー
- 📋 テストスイート別の詳細な結果表示
- 🎨 クリーンでプロフェッショナルなデザイン（Bootstrap 5）
- 🚀 CDN依存なし（埋め込みCSS）
- 📱 完全レスポンシブレイアウト
- ⚡ 自己完結型HTMLによる高速ロード

### 4. JUnit XML形式（`.xml`）
CI/CD統合（GitHub Actions、GitLab CI、Jenkins）

```bash
cli-testing-specialist run ./tests -f junit -o ./reports
```

### 5. 全形式一括生成

```bash
cli-testing-specialist run ./tests -f all -o ./reports
```

詳細は[`docs/REPORT-FORMATS.md`](docs/REPORT-FORMATS.md)を参照してください。

---

## CI/CD統合

### GitHub Actions（推奨 - たった3行！）

**v1.1.0の新機能**: 公式GitHub Actionで最も簡単に統合できます：

```yaml
name: CLI Testing

on: [push, pull_request]

jobs:
  cli-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: CLIをビルド
        run: cargo build --release

      - name: CLIをテスト
        uses: ./.github/actions/cli-testing-specialist
        with:
          binary: ./target/release/your-cli
          categories: all
          format: all

      - name: テストレポートをアップロード
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cli-test-reports
          path: cli-test-reports/
```

**高度な設定**:

```yaml
      - name: カスタム設定でCLIをテスト
        uses: ./.github/actions/cli-testing-specialist
        with:
          binary: ./target/release/your-cli
          categories: 'basic,security,path'  # 特定のカテゴリのみ
          format: 'junit'                    # CI向けフォーマット
          output: 'test-results'             # カスタム出力ディレクトリ
          include-intensive: 'false'         # リソース集約的テストをスキップ
          version: '1.1.0'                   # 特定バージョン
```

### GitHub Actions（手動セットアップ）

手動セットアップがお好みの場合：

```yaml
name: CLI Testing

on: [push, pull_request]

jobs:
  cli-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install cli-testing-specialist
        run: |
          cargo install --git https://github.com/sanae-abe/cli-testing-specialist

      - name: Build your CLI
        run: cargo build --release

      - name: Analyze CLI
        run: |
          cli-testing-specialist analyze \
            ./target/release/your-cli \
            -o analysis.json

      - name: Generate tests
        run: |
          cli-testing-specialist generate \
            analysis.json \
            -o tests \
            -c all

      - name: Install BATS
        run: sudo apt-get install -y bats

      - name: Run tests
        run: |
          cli-testing-specialist run \
            tests \
            -f all \
            -o reports

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: reports/
```

### GitLab CI

```yaml
cli-test:
  image: rust:latest
  script:
    - cargo install --git https://github.com/sanae-abe/cli-testing-specialist
    - cargo build --release
    - cli-testing-specialist analyze ./target/release/your-cli -o analysis.json
    - cli-testing-specialist generate analysis.json -o tests -c all
    - apt-get update && apt-get install -y bats
    - cli-testing-specialist run tests -f all -o reports
  artifacts:
    paths:
      - reports/
```

---

## セキュリティ機能

### セキュリティテストの哲学

**重要**: セキュリティテストは、ツールが**不正入力を拒否**すること（非ゼロ終了コード）を期待します。

```rust
// コマンドインジェクションテスト
cli-test --name 'test; rm -rf /'
// 期待: 終了コード1（拒否） ✅
// 期待しない: 終了コード0（成功） ❌
```

### セキュリティテストカテゴリ

1. **インジェクション攻撃**: コマンドインジェクション、null byteインジェクション
   - 期待される動作: ツールが終了コード1で**拒否**
   - タグ: `injection`、`critical`

2. **パストラバーサル**: ディレクトリ走査攻撃
   - 期待される動作: ツールが終了コード1で**拒否**
   - タグ: `path-traversal`、`critical`

3. **バッファオーバーフロー**: 極端に長い入力
   - 期待される動作: 適切な処理（情報提供）
   - タグ: `buffer-overflow`、`informational`

### 入力検証

- CLIバイナリパスの検証
- パス正規化（パストラバーサル防止）
- タイムアウト強制（ハング防止）
- 安全なコマンド実行

---

## 設定

### コマンドラインオプション

```bash
# カスタム出力で解析
cli-testing-specialist analyze /usr/bin/curl -o custom-analysis.json

# 特定カテゴリを生成
cli-testing-specialist generate analysis.json -c basic,security,path

# リソース集約型テストを含める
cli-testing-specialist generate analysis.json -c all --include-intensive

# タイムアウト指定で実行
cli-testing-specialist run tests --timeout 120 -f all -o reports

# 特定カテゴリをスキップ
cli-testing-specialist run tests --skip destructive-ops,directory-traversal
```

### 環境変数

```bash
# ディレクトリ走査テストをスキップ
export SKIP_DIRECTORY_TRAVERSAL_TESTS=1
cli-testing-specialist run tests -f all -o reports
```

---

## ファイル構造

```
cli-testing-specialist/
├── Cargo.toml              # Rustプロジェクト設定
├── Cargo.lock
├── README.md               # 英語版README
├── README.ja.md            # このファイル
├── LICENSE                 # MITライセンス
├── src/
│   ├── main.rs             # エントリーポイント
│   ├── lib.rs              # ライブラリエクスポート
│   ├── cli/                # CLIインターフェース（clap）
│   ├── analyzer/           # CLI解析エンジン
│   ├── generator/          # テストケース生成
│   ├── runner/             # BATSテスト実行
│   ├── reporter/           # レポート生成（MD/JSON/HTML/JUnit）
│   ├── types/              # 型定義
│   ├── error.rs            # エラー型
│   └── utils/              # ユーティリティ
├── tests/                  # 統合テスト
├── benches/                # パフォーマンスベンチマーク
└── docs/
    ├── RUST_V1_DESIGN.md   # 設計ドキュメント
    ├── TARGET-TOOLS.md     # 対象ツールガイドライン
    └── REPORT-FORMATS.md   # レポート形式ガイド
```

---

## ライセンス

MITライセンス - 詳細は[LICENSE](LICENSE)ファイルを参照してください。

---

## 貢献

貢献を歓迎します！以下の手順に従ってください：

1. リポジトリをフォーク
2. フィーチャーブランチを作成
3. テスト付きで変更を実装
4. プルリクエストを提出

大きな変更の場合は、まずissueを開いて提案を議論してください。

---

## サポート

- **ドキュメント**: [`docs/`](docs/)ディレクトリ
  - [設計ドキュメント](docs/RUST_V1_DESIGN.md) - アーキテクチャと実装
  - [対象ツールガイド](docs/TARGET-TOOLS.md) - 互換性ガイドライン
  - [レポート形式](docs/REPORT-FORMATS.md) - レポート形式リファレンス
- **Issues**: [GitHub Issues](https://github.com/sanae-abe/cli-testing-specialist/issues)
- **Discussions**: [GitHub Discussions](https://github.com/sanae-abe/cli-testing-specialist/discussions)

---

## 変更履歴

### v1.0.10 (2025-11-16) - CI/CDインフラ修正 🔧

**CI/CD改善**:
- **setrlimitテスト分離**: Linux CI環境で5つのsetrlimit関連テストを無視
  - テストがプロセス全体のメモリ制限（100MB）を設定し、並列テストに影響
  - Code Coverageでの「failed to allocate an alternative stack」エラーを防止
  - ローカル開発およびmacOS/Windows環境では引き続きテスト実行
- **マルチシェルテスト対応**: Ubuntu CI環境にzshインストールを追加
  - 不足していたzshパッケージのインストールで2/3から3/3の成功率に改善
  - すべてのマルチシェルテスト（bash/zsh/sh）が正常に通過

**Windowsプラットフォーム**:
- Job Object対応のため`Win32_System_Threading`機能を追加

**ドキュメント**:
- rustdocサンプルとHTMLタグエスケープを修正
- 作者メールアドレスを実際のアドレスに更新

**すべてのCI/CDパイプラインが正常に通過** ✅

### v1.0.9 (2025-11-12) - 実行ベース推定 🎯

**革新的な引数なし動作検出**:
- **100%推定精度**: バイナリを直接実行して実際の終了コードを測定
- **cldev型CLI問題を解決**: 同一のUsageパターン（`[OPTIONS] <COMMAND>`）で異なる動作
- **安全性対策**: 1秒タイムアウト、出力破棄、非TTYモード、対話ツール検出
- **テスト成功率**: 93.3% → **100%**（cldev/cmdrun/backup-suiteで15/15テスト成功）

**HTMLレポート改善**:
- フィルターバグ修正: Skippedフィルターでエラー詳細行が正しく非表示に
- All/Passed/Failed/Skippedすべての状態で完璧なインタラクティブフィルタリング

**技術詳細**:
- 新メソッド: `BehaviorInferrer::execute_and_measure()`
- 依存関係: `wait-timeout = "0.2"`（プロセスタイムアウト処理）
- 109単体テスト全て通過（100%成功率）

### v1.0.8 (2025-11-12)

**引数なしテストの主張緩和**:
- 厳格な出力主張を削除（終了コードのみ）
- テスト成功率: 86.7% → 93.3%
- 理由: CLIが異なるエラー形式を表示（短いメッセージ vs 完全ヘルプ）

### v1.0.7 (2025-11-12)

**Clippy警告修正**:
- `TestCategory::default()` を `standard_categories()` に改名
- `.claude/CLAUDE.md` にGit Hooks設定追加

### v1.0.6 (2025-11-12)

**必須引数検出**:
- Usage行からの自動抽出（`<ID>`, `<FILE>`）
- テストテンプレート改善（ダミー引数、動的オプション選択）
- テスト成功率: 85.0% → 92.9%（cmdrun）

### v1.0.5 (2025-11-12)

**依存関係更新**:
- Dependabot PR全7件マージ（GitHub Actions、indicatif 0.18、thiserror 2.0、colored 3.0、criterion 0.7）
- MSRV Rust 1.80にバンプ
- `cargo audit` 脆弱性0件

### v1.0.4 (2025-01-12)

**ドキュメント改善** 📚:
- 包括的な `docs/TARGET-TOOLS.md` ガイド追加（ツール適用度判定）
- ツール分類システム: 高/中/低適用度と成功率の見積もり

### v1.0.3 (2025-01-12)

**重大なセキュリティテスト修正** 🔒:
- セキュリティテストが**任意の非ゼロ終了コード**を受け入れるように修正
- Unix慣例に正しく対応: exit code 2 = 使用エラー

### v1.0.2 (2025-01-12)

**セキュリティ修正** 🔒:
- セキュリティテストが正しく攻撃を**拒否**するように修正
- ディレクトリ走査テストが`--include-intensive`フラグで**オプトイン**に

### v1.0.1 (2025-01-11)

- 初回本番リリース
- 9テストカテゴリ、45-55テストケース
- 4レポート形式（Markdown/JSON/HTML/JUnit）

---

**Rustで❤️を込めて構築**