kos322/testrail-skill

Skill da API do TestRail

Integração direta com a API REST do TestRail através de wrappers bash locais no repositório.

Instalação

Clone o repositório primeiro:

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

Configuração

Defina estas variáveis de ambiente:

• TESTRAIL_URL
• TESTRAIL_USER
• TESTRAIL_API_KEY

URL base:

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

Árvore de decisão

• PROJECT_ID conhecido + pergunta simples somente leitura: chame o wrapper direto imediatamente.
• PROJECT_ID desconhecido: chame ./scripts/get_projects.sh.
• Problema de ambiente/auth ou primeira instalação: chame ./scripts/doctor.sh.

Consultas comuns

# ID do projeto conhecido: contagem total de casos
./scripts/count_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# ID do projeto conhecido: lista completa de casos com paginação automática
./scripts/list_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# ID do projeto conhecido: página bruta de casos com paginação
./scripts/get_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# A qualquer momento: ler um caso
./scripts/get_case.sh CASE_ID | jq -r .title

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

# Atalho para pré-condição
./scripts/get_case_precondition.sh CASE_ID

# ID do projeto desconhecido: descobrir projetos acessíveis
./scripts/get_projects.sh | jq '(.projects // .) | map({id, name})'

# Problema de configuração/auth: validar ambiente e acesso
./scripts/doctor.sh

Wrappers preferidos

• scripts/count_cases.sh — contagem confiável de casos totais
• scripts/list_cases.sh — lista completa de casos com paginação automática
• scripts/get_cases.sh — resposta bruta de casos paginados
• scripts/get_case.sh — consulta de caso único
• scripts/get_case_field.sh — consulta de campo único
• scripts/get_case_precondition.sh — atalho para pré-condição
• scripts/get_projects.sh — descobrir projetos acessíveis
• scripts/doctor.sh — verificação rápida de configuração/auth
• scripts/create_run.sh, scripts/add_result*.sh, scripts/close_run.sh — fluxos de run/result
• scripts/get_reference_data.sh — status, campos, templates, usuários

Contratos de saída

Intenção	Comando	Saída
contagem total de casos	count-cases	inteiro simples
lista de casos	list-cases	texto simples por padrão: C{id}: {title}
lista estruturada de casos	list-cases --format json	objeto JSON com count e cases
um caso	get-case	objeto JSON do caso
um campo de caso	get-case-field	escalar/string simples ou JSON compacto para arrays/objetos
pré-condição do caso	get-case-precondition	texto simples / valor bruto do campo

Paginação

• get_cases, get_runs, get_results* e endpoints similares podem ser paginados.
• Não assuma que .size é um total seguro a menos que _links.next esteja vazio.
• Use ./scripts/count_cases.sh quando a pergunta for "quantos casos existem?".

Windows

• Preferido: Git Bash / WSL.
• Ambiente apenas PowerShell: use wrappers finos em powershell/.
• Os wrappers PowerShell apenas executam scripts bash; eles não leem .env por conta própria.

.\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

Documentação sob demanda

• scripts/README.md — uso script por script
• docs/api-reference.md — notas de endpoint e formatos de payload
• docs/troubleshooting.md — falhas de configuração e autenticação
• docs/agent-guide.md — orientação de execução específica para agentes
• docs/maintenance/endpoint-status.md — snapshot de manutenção, não orientação em tempo de execução

Exemplos

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

Documentação oficial da API: https://support.testrail.com/hc/en-us/categories/7076541806228-API-Manual