Monte um teste de API encadeado

Esse tutorial monta um runbook multi-bloco que simula um check de API end-to-end real: autentica, usa o token, verifica que o resultado é o esperado. É o fluxo que você vai querer toda vez que debugar staging ou escrever um smoke test pro CI.

Tempo: ~15 minutos · Pré-requisitos: terminou o Quickstart.

O que você vai montar

No fim você vai ter um runbook com 3 blocos encadeados:

graph LR
  A[login] -- token --> B[me]
  B -- user.id --> C[assert]

login → POST /auth/login, captura o JWT
me → GET /users/me com o bearer token de login
assert → uma seção # expect: que falha o runbook se time ou status saírem do esperado

O httui resolve o grafo de dependências automaticamente — rodar me roda login primeiro; rodar assert roda os dois.

1. A API que você vai bater

Vamos usar httpbin e um helperzinho fake-auth — ambos públicos, sem signup. O “login” retorna o que você mandar como “token” fake, e “/anything” ecoa sua request pra você confirmar que o header bearer chegou no servidor.

Pra assertion vamos mirar um endpoint /json de formato fixo pra poder dar assert em campos reais.

2. Crie o runbook

Em runbooks/, crie auth-flow.md. Abra ele e adicione uma intro curta no topo:

# Smoke test do auth flow

Uma cadeia login → me → assert pra verificar que o gateway de
staging não tá dropando bearer tokens.

Embaixo da intro, cole esse bloco HTTP. O alias=login na linha do fence nomeia o bloco pra que possamos referenciá-lo depois:

```http alias=login
POST https://httpbin.org/post
Content-Type: application/json

{
  "user": "alice",
  "device": "laptop-42"
}
```

Aperte Cmd+Enter. Você deve ver a response echo do httpbin com seu JSON no campo json.

4. Bloco 2 — me (usa o token)

Agora a cadeia. Adicione embaixo:

```http alias=me
GET https://httpbin.org/anything
Authorization: Bearer {{login.body.json.user}}-{{login.body.json.device}}
Accept: application/json
```

A referência {{login.body.json.user}}-{{login.body.json.device}} lê alice e laptop-42 da response de login e usa eles como bearer token fake. (Em produção você referenciaria um campo de JWT real tipo {{login.body.access_token}}.)

Clique em qualquer lugar do corpo do bloco me.
Aperte Cmd+Enter.
O httui vê que me depende de login → roda login primeiro (cacheado do passo 3 — instantâneo).
Resolve as referências, envia me, mostra a response.
No painel de response, expanda o campo headers — confirme que Authorization: Bearer alice-laptop-42 chegou no httpbin.

Você acabou de encadear duas chamadas de API reais juntas dentro de um único arquivo markdown.

5. Bloco 3 — assert

Adicione um terceiro bloco, mas dessa vez use o endpoint /json de formato fixo e uma seção # expect::

```http alias=assert
GET https://httpbin.org/json

# expect:
#   status == 200
#   time &lt; 1500ms
#   body.slideshow.title contains "Sample"
```

A seção # expect: transforma o bloco de “me mostra a response” em “falhe o runbook se qualquer um desses não for verdadeiro”.

Aperte Cmd+Enter em assert. Você deve ver as três asserts passarem (check verde do lado de cada linha).

6. Rode o runbook inteiro

Aperte Cmd+Shift+Enter (ou clique no botão Run all na status bar). O httui:

Monta a DAG de dependências (login → me, assert standalone).
Roda em ordem topológica, em paralelo onde possível.
Mostra contagens de pass/fail na status bar.

Pros nossos 3 blocos leva ~600ms no total. Num runbook real com 20 blocos contra staging, você ia ver as runs paralelas se abrirem em leque visualmente no painel.

E agora

Você agora tem o loop dominado: bloco → captura → referência → assert. Isso é 80% do que o httui serve. Daqui:

Adicione um banco no seu runbook — mesma ideia de cadeia mas com SQL: pega uma linha, usa o id numa request HTTP, assert da response.
Referências entre blocos — a sintaxe {{...}} completa, regras de escopo e como {{$prev}} funciona.
Ambientes — {{BASE_URL}} e parecidos: variáveis por env pra que o mesmo runbook bata em staging, prod ou no túnel do seu laptop.