Skills ユニットテスト

Skill を書き終えた後、実際に期待どおりに動作することをどう確認するのでしょうか?手動テストでは時間がかかる上に見落としがちです。

この記事では、スクリプトのユニットテストからエンドツーエンドのトリガーテストまで、Skill の体系的なテストケースを構築する方法を紹介します。


Skill テストの2つのレベル

レベルテスト対象方法
スクリプトのユニットテストscripts/ 配下の Python/JS スクリプトpytest / 標準 unittest
トリガーエンドツーエンドテストSkill が正しくトリガーされるか、出力が期待どおりかskill-creator の eval フレームワーク

レベル1: スクリプトのユニットテスト

スクリプトは Skill の中で最も決定的な部分であり、標準のユニットテストフレームワークによるカバレッジに適しています。

例

# 文件路径:scripts/tests/test_clean_data.py
import pytest
import os
import tempfile
import csv

# テスト対象のモジュール
import sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from clean_data import remove_duplicates, fill_nulls, strip_whitespace

# ── 测试:去重 ──────────────────────────────────────────
def test_remove_duplicates_basic():
    """正常情况:有重复行时应删除"""
    rows = [
        {"name": "サンプル", "score": "90"},
        {"name": "サンプル", "score": "90"},   # 重复行
        {"name": "サンプル", "score": "80"},
    ]
    result = remove_duplicates(rows)
    assert len(result) == 2, "应删除 1 条重复行"

def test_remove_duplicates_empty():
    """边界情况:空列表不应报错"""
    result = remove_duplicates([])
    assert result == []

# ── 测试:空值填充 ──────────────────────────────────────
def test_fill_nulls_numeric():
    """数値列の欠損値は0で埋めるべきである"""
    rows = [{"value": "10"}, {"value": ""}, {"value": "20"}]
    result = fill_nulls(rows, col="value", fill_with="0")
    assert result[1]["value"] == "0"

# ── 测试:去空格 ──────────────────────────────────────
def test_strip_whitespace():
    "“文字列の先頭と末尾のスペースは削除されるべきです”"
    rows = [{"name": "  サンプル  "}, {"name": "サンプル"}]
    result = strip_whitespace(rows, col="name")
    assert result[0]["name"] == "サンプル"
    assert result[1]["name"] == "サンプル"

# ── 集成测试:读取真实文件 ──────────────────────────────
def test_process_real_file():
    """创建临时 CSV 文件并测试完整处理流程"""
    with tempfile.NamedTemporaryFile(mode="w", suffix=".csv",
                                    delete=False, newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["name", "score"])
        writer.writeheader()
        writer.writerow({"name": "  サンプル  ", "score": "90"})
        writer.writerow({"name": "  サンプル  ", "score": "90"})  # 重复
        writer.writerow({"name": "サンプル",     "score": ""})    # 空值
        tmp_path = f.name

    try:
        from clean_data import process_file
        result = process_file(tmp_path)
        assert result["removed_rows"] == 1
        assert result["fixed_values"] == 1
    finally:
        os.unlink(tmp_path)

テストを実行:

# 进入 Skill 目录后运行所有测试
cd my-skill/
pytest scripts/tests/ -v

# 生成覆盖率报告
pytest scripts/tests/ --cov=scripts --cov-report=term-missing

出力:

scripts/tests/test_clean_data.py::test_remove_duplicates_basic  PASSED
scripts/tests/test_clean_data.py::test_remove_duplicates_empty  PASSED
scripts/tests/test_clean_data.py::test_fill_nulls_numeric       PASSED
scripts/tests/test_clean_data.py::test_strip_whitespace         PASSED
scripts/tests/test_clean_data.py::test_process_real_file        PASSED

5 passed in 0.12s

レベル2: トリガーエンドツーエンドテスト

トリガーテストが検証するのは、ユーザーがリクエストを送信したときに、Claude がこの Skill を使用するかどうかです。

テストケースは JSON 形式で定義され、ユーザーのプロンプトと期待される動作のアサーションを含みます。

例

[
  {
    "id": "trigger_basic",
    "prompt": この販売データCSVを分析し、月次トレンドを特定して統計サマリーを生成してください。,
    "assertions": [
      {
        "type": "skill_triggered",
        "skill": "csv-analyzer",
        "description": "复杂分析请求应触发 csv-analyzer"
      }
    ]
  },
  {
    "id": "trigger_with_file",
    "prompt": サンプル_sales.csv をアップロードしました。各列のデータ分布を分析してください。,
    "assertions": [
      {
        "type": "skill_triggered",
        "skill": "csv-analyzer"
      },
      {
        "type": "output_contains",
        "keyword": "统计",
        "description": "输出中应包含统计信息"
      }
    ]
  },
  {
    "id": "no_trigger_simple",
    "prompt": "CSV はどんな形式ですか?",
    "assertions": [
      {
        "type": "skill_not_triggered",
        "skill": "csv-analyzer",
        "description": "简单知识问题不应触发 Skill"
      }
    ]
  }
]

トリガーテストを実行(skill-creator が提供する eval ツールが必要):

例

# 运行测试集并生成可视化报告
python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path csv-analyzer/ \
  --model claude-sonnet-4-20250514

# 生成 HTML 报告供人工审阅
python eval-viewer/generate_review.py \
  --results evals/results/ \
  --output evals/review.html

テストケースのプロンプトは十分に複雑である必要があります。単純な「CSVを読む」といったリクエストは、トリガーに失敗しても Skill に問題があるとは限りません。Claude 自体が処理できるからです。良いテストケースは、ユーザーが実際に投げるような複数ステップで明確な出力要件があるリクエストであるべきです。


テストケースのカバレッジ範囲

タイプカバーすべきシナリオ
正のトリガー複雑なタスク、キーワードを含む、明確な出力形式の要件
負のトリガー簡単なQ&A、関連語に言及するだけで Skill を必要としない
境界入力空ファイル、巨大なファイル、未対応フォーマットのファイル
エラーリカバリファイルパスが間違っている場合のメッセージが明確かどうか
その他の拡張