kos322/testrail-skill

Habilidad de API de TestRail

Integración directa con la API REST de TestRail a través de wrappers bash locales al repositorio.

Instalación

Clone el repositorio primero:

git clone https://github.com/kos322/testrail-skill.git
cd testrail-skill

Configuración

Establezca estas variables de entorno:

• TESTRAIL_URL
• TESTRAIL_USER
• TESTRAIL_API_KEY

URL base:

${TESTRAIL_URL}/index.php?/api/v2

Árbol de decisión

• PROJECT_ID conocido + pregunta simple de solo lectura: llame al wrapper directo inmediatamente.
• PROJECT_ID desconocido: llame a ./scripts/get_projects.sh.
• Problema de entorno/autenticación/configuración o instalación por primera vez: llame a ./scripts/doctor.sh.

Consultas comunes

# ID de proyecto conocido: recuento total de casos
./scripts/count_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# ID de proyecto conocido: lista completa de casos con paginación automática
./scripts/list_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# ID de proyecto conocido: página de casos paginada en bruto
./scripts/get_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# En cualquier momento: leer un caso
./scripts/get_case.sh CASE_ID | jq -r .title

# Campo único sin análisis manual de JSON
./scripts/get_case_field.sh CASE_ID FIELD

# Atajo para precondición
./scripts/get_case_precondition.sh CASE_ID

# ID de proyecto desconocido: descubrir proyectos accesibles
./scripts/get_projects.sh | jq '(.projects // .) | map({id, name})'

# Problema de autenticación/configuración: validar entorno y acceso
./scripts/doctor.sh

Wrappers preferidos

• scripts/count_cases.sh — recuento fiable de casos totales
• scripts/list_cases.sh — lista completa de casos con paginación automática
• scripts/get_cases.sh — respuesta de casos paginada en bruto
• scripts/get_case.sh — búsqueda de un caso único
• scripts/get_case_field.sh — búsqueda de un campo único
• scripts/get_case_precondition.sh — atajo para precondición
• scripts/get_projects.sh — descubrir proyectos accesibles
• scripts/doctor.sh — comprobación rápida de entorno/autenticación
• scripts/create_run.sh, scripts/add_result*.sh, scripts/close_run.sh — flujos de ejecución/resultados
• scripts/get_reference_data.sh — estados, campos, plantillas, usuarios

Contratos de salida

Intención	Comando	Salida
recuento total de casos	count-cases	entero simple
lista de casos	list-cases	texto plano por defecto: C{id}: {title}
lista de casos estructurada	list-cases --format json	objeto JSON con count y cases
un caso	get-case	objeto JSON del caso
un campo de caso	get-case-field	escalar/cadena simple o JSON compacto para arrays/objetos
precondición de caso	get-case-precondition	texto plano / valor de campo en bruto

Paginación

• Los puntos finales get_cases, get_runs, get_results* y similares pueden estar paginados.
• No asuma que .size es un total seguro a menos que _links.next esté vacío.
• Use ./scripts/count_cases.sh cuando la pregunta sea "¿cuántos casos hay?"

Windows

• Preferido: Git Bash / WSL.
• Entorno solo PowerShell: use wrappers delgados en powershell/.
• Los wrappers de PowerShell solo ejecutan scripts bash; no leen .env por sí mismos.

.\powershell\count-cases.ps1 1
.\powershell\list-cases.ps1 1
.\powershell\list-cases.ps1 1 --format json
.\powershell\get-case.ps1 93
.\powershell\get-case-field.ps1 2 custom_preconds
.\powershell\get-case-precondition.ps1 2
.\powershell\get-cases.ps1 1 10 --suite 1
.\powershell\get-sections.ps1 1 1
.\powershell\get-runs.ps1 1

Documentación bajo demanda

• scripts/README.md — uso script por script
• docs/api-reference.md — notas de puntos finales y formas de carga útil
• docs/troubleshooting.md — fallos de configuración y autenticación
• docs/agent-guide.md — guía de ejecución específica para el agente
• docs/maintenance/endpoint-status.md — instantánea de mantenimiento, no guía en tiempo de ejecución

Ejemplos

• examples/workflow_ci.sh
• examples/workflow_plans_milestones.sh
• examples/workflow_attachments.sh

Documentación oficial de la API: https://support.testrail.com/hc/en-us/categories/7076541806228-API-Manual