Antes de começar
O que é preciso
- O módulo Connections no seu workspace: está incluído nos planos Team, Business, Partner e Enterprise, e como o módulo Integrations for one UAT com o plano Project.
- Direitos de administrador no projeto do UAT Studio.
- Uma ferramenta que consiga enviar pedidos HTTPS: um script, o seu pipeline de CI, o Postman ou uma plataforma de integração.
Usa o Zapier ou o Make? Então não precisa de chamar a API diretamente: veja Zapier e Make.
Configuração · uma vez por projeto
Conecte a sua ferramenta
1
Crie uma API key
- Entre em app.uat.studio, abra o projeto e vá a Setup.
- No cartão API keys, escreva um nome como Release pipeline e clique em Create API key.
- Clique em Copy. O UAT Studio só mostra a chave uma vez. Guarde-a como segredo na sua ferramenta, por exemplo
UAT_STUDIO_KEY.
2
Faça uma chamada
Envie a chave em cada pedido como Authorization: Bearer, um espaço e a chave. Por exemplo, as ocorrências mais recentes:
curl -H "Authorization: Bearer $UAT_STUDIO_KEY" "https://app.uat.studio/api/v1/issues?order=created&limit=10"Uma nova ocorrência, com JSON no body:
curl -X POST "https://app.uat.studio/api/v1/issues" \
-H "Authorization: Bearer $UAT_STUDIO_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Save fails on a new quote", "severity": "High", "test_number": 12}'A resposta é JSON. Cada ocorrência vem com a chave (ISS-012), título, descrição, gravidade, prioridade, estado, responsável, o teste e o tester que a encontrou, o ticket no Jira ou no Azure DevOps e um link para o UAT Studio.
O que pode usar · https://app.uat.studio/api/v1
Os endereços da API
| Tipo | Pedido | O que faz |
|---|---|---|
| Ler | GET /me | O projeto a que a chave pertence. |
| Ler | GET /issues?order=created | As ocorrências mais recentes. order=updated: as últimas alteradas. Também since (uma data e hora), status e limit (até 100). |
| Ler | GET /issues/ISS-012 | Uma ocorrência, com o passo a que diz respeito e o seu histórico. |
| Criar | POST /issues | Uma nova ocorrência: title e, opcionalmente, description, severity, priority, test_number, step_number, assignee, record_url. Sem test_number (e com group para o grupo que a testa), a ocorrência recebe um caso de teste próprio assim que passa a Pronta para reteste. |
| Alterar | PATCH /issues/ISS-012 | status, severity, assignee ou record_url, com um comment opcional. Definir o status de uma ocorrência sem caso de teste como Ready for retest cria o seu caso de teste; a resposta inclui então "test_case": "created". |
| Alterar | POST /issues/ISS-012/comments | Um comment no histórico. |
| Ler | GET /cases | Os casos de teste com os seus passos e quantos resultados são Pass, Fail, etc. Também epic, since e limit (até 1000). |
| Criar | POST /cases | Um caso de teste: title, steps (uma lista de action, expected e, opcionalmente, data) e, opcionalmente, external_id, epic, group, links, priority (Must, Should ou Could) e risk (High, Medium ou Low). Envie de novo o mesmo external_id para o atualizar; os passos na mesma posição mantêm os seus resultados. |
| Criar | POST /testers | Um tester: name e, opcionalmente, email e group. O convite é enviado a partir de Setup. |
| Ler | GET /signoffs | Os sign-offs, os mais recentes primeiro. |
| Ler | GET /groups | Os grupos do projeto. |
| Ler | GET /status | Go ou no-go para uma release: ver abaixo. |
Para o seu pipeline
Release gate: fazer deploy quando o negócio deu o sign-off
GET /status responde com uma decision: go quando o ciclo atual tem sign-off e não há nenhuma ocorrência Critical aberta, no-go quando um sign-off é rejeitado ou há uma ocorrência Critical aberta, e open quando ainda não está decidido. Com ?gate=1, tudo o que não seja go responde com HTTP 409, e o passo no seu pipeline falha.
- name: UAT signed off?
run: curl --fail-with-body -sS -H "Authorization: Bearer ${{ secrets.UAT_STUDIO_KEY }}" "https://app.uat.studio/api/v1/status?gate=1"Use uma chave própria para o pipeline, para a poder revogar separadamente.
Se algo falhar
Respostas e o que fazer
| Resposta | O que fazer |
|---|---|
| 401: the API key is not valid | A chave foi revogada ou foi mal escrita. Crie uma nova chave em Setup › API keys. |
| 403: não faz parte do plano, ou só de leitura | O workspace não tem o módulo Connections, ou o plano terminou. Ler continua a funcionar quando está só de leitura. |
| 404: there is no issue ISS-… | A chave pertence a outro projeto, ou a ocorrência foi fundida. |
| 400: um campo não está correto | A mensagem indica qual o campo, por exemplo uma gravidade que não existe. |
409 com ?gate=1 | A release ainda não pode avançar: a resposta contém os motivos. |
Segurança
Como a chave é protegida
- Uma chave dá acesso a um projeto, a nada mais no seu workspace.
- O UAT Studio guarda apenas uma impressão digital da chave, nunca a própria chave. Setup mostra os últimos quatro caracteres e quando foi usada pela última vez.
- Revoke em Setup desativa uma chave de imediato.
- Cada ocorrência ou tester criado ou alterado através de uma chave aparece no histórico da ocorrência e no audit log, com o nome da chave.
- Nunca coloque uma chave num email, num chat ou em código; guarde-a como segredo na sua ferramenta.