Pruebas unitarias de Skills

Después de escribir una Skill, ¿cómo confirmar que realmente funciona según lo esperado? Las pruebas manuales son lentas y propensas a omitir casos.

Este artículo explica cómo establecer casos de prueba sistemáticos para una Skill, desde pruebas unitarias de scripts hasta pruebas de activación de extremo a extremo.


Los dos niveles de pruebas de Skill

NivelObjeto de pruebaMétodo
Pruebas unitarias de scriptsScripts de Python/JS en scripts/pytest / unittest estándar
Pruebas de activación de extremo a extremoSi la Skill se activa correctamente y si la salida es la esperadaEl framework eval de skill-creator

Nivel 1: Pruebas unitarias de scripts

Los scripts son la parte más determinista de una Skill, por lo que conviene cubrirlos con un framework estándar de pruebas unitarias.

Ejemplo

# Ruta del archivo: scripts/tests/test_clean_data.py
import pytest
import os
import tempfile
import csv

# Módulo bajo prueba
import sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
from clean_data import remove_duplicates, fill_nulls, strip_whitespace

# ── Prueba: deduplicación ──────────────────────────────────────────
def test_remove_duplicates_basic():
    """Caso normal: debe eliminar las líneas duplicadas"""
    rows = [
        {"name": "ejemplo", "score": "90"},
        {"name": "ejemplo", "score": "90"},   # Líneas duplicadas
        {"name": "EJEMPLO", "score": "80"},
    ]
    result = remove_duplicates(rows)
    assert len(result) == 2, "Debería eliminar 1 línea duplicada"

def test_remove_duplicates_empty():
    """Caso límite: una lista vacía no debe generar error"""
    result = remove_duplicates([])
    assert result == []

# ── Prueba: relleno de valores nulos ──────────────────────────────────────
def test_fill_nulls_numeric():
    """Los valores nulos de las columnas numéricas deben rellenarse con 0"""
    rows = [{"value": "10"}, {"value": ""}, {"value": "20"}]
    result = fill_nulls(rows, col="value", fill_with="0")
    assert result[1]["value"] == "0"

# ── Prueba: eliminación de espacios ──────────────────────────────────────
def test_strip_whitespace():
    """Los espacios al inicio y al final de las cadenas deben eliminarse"""
    rows = [{"name": "  ejemplo  "}, {"name": "EJEMPLO"}]
    result = strip_whitespace(rows, col="name")
    assert result[0]["name"] == "ejemplo"
    assert result[1]["name"] == "EJEMPLO"

# ── Prueba de integración: leer un archivo real ──────────────────────────────
def test_process_real_file():
    """Crear un archivo CSV temporal y probar el flujo completo de procesamiento"""
    with tempfile.NamedTemporaryFile(mode="w", suffix=".csv",
                                    delete=False, newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["name", "score"])
        writer.writeheader()
        writer.writerow({"name": "  ejemplo  ", "score": "90"})
        writer.writerow({"name": "  ejemplo  ", "score": "90"})  # Duplicado
        writer.writerow({"name": "EJEMPLO",     "score": ""})    # Valores nulos
        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)

Ejecutar las pruebas:

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

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

Salida:

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

Nivel 2: Pruebas de activación de extremo a extremo

Las pruebas de activación verifican si Claude usará esta Skill cuando el usuario hace una solicitud.

Los casos de prueba se definen en formato JSON e incluyen el prompt del usuario y aserciones sobre el comportamiento esperado.

Ejemplo

[
  {
    "id": "trigger_basic",
    "prompt": "Ayúdame a analizar este CSV de datos de ventas, encontrar las tendencias mensuales y generar un resumen estadístico",
    "assertions": [
      {
        "type": "skill_triggered",
        "skill": "csv-analyzer",
        "description": "Las solicitudes de análisis complejas deben activar csv-analyzer"
      }
    ]
  },
  {
    "id": "trigger_with_file",
    "prompt": "He subido ejemplo_sales.csv, por favor analiza la distribución de datos de cada columna",
    "assertions": [
      {
        "type": "skill_triggered",
        "skill": "csv-analyzer"
      },
      {
        "type": "output_contains",
        "keyword": "Estadísticas",
        "description": "La salida debe incluir información estadística"
      }
    ]
  },
  {
    "id": "no_trigger_simple",
    "prompt": "¿Qué es el formato CSV?",
    "assertions": [
      {
        "type": "skill_not_triggered",
        "skill": "csv-analyzer",
        "description": "Las preguntas simples de conocimiento no deben activar la Skill"
      }
    ]
  }
]

Ejecutar las pruebas de activación (requiere la herramienta eval proporcionada por skill-creator):

Ejemplo

# Ejecutar el conjunto de pruebas y generar un informe visual
python -m scripts.run_eval \
  --eval-set evals/trigger-eval.json \
  --skill-path csv-analyzer/ \
  --model claude-sonnet-4-20250514

# Generar un informe HTML para revisión humana
python eval-viewer/generate_review.py \
  --results evals/results/ \
  --output evals/review.html

Los prompts de los casos de prueba deben ser lo suficientemente complejos. Las solicitudes simples como «leer CSV» que fallen en la activación no significan que la Skill tenga problemas, porque Claude puede manejarlas por sí mismo. Un buen caso de prueba debe ser una solicitud real de varios pasos, con requisitos claros de salida, que el usuario haría.


Cobertura de los casos de prueba

TipoEscenarios a cubrir
Activación positivaTareas complejas, inclusión de palabras clave, requisitos claros de formato de salida
Activación negativaPreguntas y respuestas simples, solo mencionar palabras relacionadas sin necesidad de la Skill
Entradas límiteArchivos vacíos, archivos muy grandes, archivos con formato no compatible
Recuperación de erroresClaridad del mensaje cuando la ruta del archivo es incorrecta
Otras extensiones