Descrição do Conteúdo / Informações:
-------------------------------------------------------------------------
Bilingual post · Post bilíngue

Jump to: English · Português



English {#english}




Testing Horse APIs with Postman


The IDE story from post 034–035 gets you compiling Pascal. But CrabPascal's killer demos are HTTP servers — Horse routes, JSON bodies, middleware. How do you verify them without writing another Pascal test harness every time?

Answer: usage/postman-guide plus the living example at examples/crud/ in the repo.



Three reference APIs


The Postman guide catalogs three starter projects:

Project
Port
Endpoints
Path

Time Server
9001
3
examples/time-server/

CRUD Produtos
9000
5
examples/crud/

Agenda
9000
2
examples/agenda/

Each runs with crab-pascal run (interpreter) or build-exe for a native binary. Pick one server per port — don't run CRUD and Agenda simultaneously on 9000.



Start the CRUD server


The CRUD walkthrough (blog post 029) shows structure; here's the minimal boot:

program CrudAPI;
uses System.SysUtils, Horse, System.JSON, ProdutoService;
begin
THorse.Get('/produtos',
procedure(Req: THorseRequest; Res: THorseResponse; Next: TNextProc)
begin
Res.Send<TJSONObject>(TProdutoService.ListarProdutos);
end);
THorse.Listen(9000);
end.

Terminal:

cd examples/crud
crab-pascal run crud.dpr
# Server listening on port 9000...

Keep this terminal open. Use Postman or cURL in another window.



Import the collection


Fastest path from postman-guide:

• Copy the JSON collection from the doc (full CRUD + time-server requests)

• Postman → Import → Raw text → paste → Import

• Set environment variable baseUrl = http://localhost:9000

Alternative: import individual cURL snippets — Postman converts them automatically.



Example requests


List products:

curl -s http://localhost:9000/produtos | jq

Create product:

curl -X POST http://localhost:9000/produtos \
-H "Content-Type: application/json" \
-d '{"nome":"Widget","preco":19.99}'

Time server (port 9001):

curl http://localhost:9001/horaservidor

Expected JSON includes ISO timestamp and server label — proves SysUtils date helpers and Horse routing both work.



What Postman testing validates


Unlike unit tests that mock HTTP, this flow exercises:

• Horse Get/Post/Put/Delete registration

• Anonymous procedure handlers (Delphi closure style)

•
System.JSON serialization

• Generic collections inside ProdutoService.pas

• Long-running process stability

When a sprint breaks Horse parity, Postman turns red before users file vague "API broken" issues.



CI and local smoke


Full Postman collections in CI need Newman or a script wrapper. Locally, tests/test_exemplos_completo.ps1 runs broader example smoke (Horse servers noted as environment-dependent in Sprint 1 review).

Pragmatic split:

•
Developer loop: Postman + crab-pascal run

•
CI gate: cargo test + Horse E2E where headless mocks exist (Sprint 16+)



Troubleshooting


Symptom
Fix

Connection refused
Server not started or wrong port

Empty JSON array
Fresh in-memory store — POST first

404 on route
Check route string vs collection path

Compiler error on Horse unit
Verify crabpascal.toml search paths

Deep reference: usage/postman-guide. Source: examples/crud/ in Bitbucket.



Environment variables and team sharing


Export Postman environments with fixed ports per developer machine:

{
"name": "CrabPascal Local",
"values": [
{ "key": "crudBase", "value": "http://localhost:9000" },
{ "key": "timeBase", "value": "http://localhost:9001" }
]
}

Share collection + environment JSON in your team wiki — the Mintlify guide includes copy-paste blocks. For automated regression later, Newman (newman run collection.json) can gate releases once Horse headless mocks land in CI; until then, manual Postman remains the honest integration test Delphi developers already know.



Next in series


Post 037 — Nova Arquitetura v2.0.1 Explained covers why we stopped hardcoding every RTL call in Rust and started loading real .pas units from .dproj search paths.



Português {#portugus}




Testando APIs Horse com Postman


A história de IDE dos posts 034–035 leva você a compilar Pascal. Mas os demos matadores do CrabPascal são servidores HTTP — rotas Horse, corpos JSON, middleware. Como verificar sem escrever outro harness de teste em Pascal toda vez?

Resposta: usage/postman-guide mais o exemplo vivo em examples/crud/ no repositório.



Três APIs de referência


O guia Postman cataloga três projetos iniciais:

Projeto
Porta
Endpoints
Caminho

Time Server
9001
3
examples/time-server/

CRUD Produtos
9000
5
examples/crud/

Agenda
9000
2
examples/agenda/

Cada um roda com crab-pascal run (interpretador) ou build-exe para binário nativo. Um servidor por porta — não rode CRUD e Agenda juntos na 9000.



Subir o servidor CRUD


O walkthrough CRUD (post 029) mostra a estrutura; boot mínimo:

program CrudAPI;
uses System.SysUtils, Horse, System.JSON, ProdutoService;
begin
THorse.Get('/produtos',
procedure(Req: THorseRequest; Res: THorseResponse; Next: TNextProc)
begin
Res.Send<TJSONObject>(TProdutoService.ListarProdutos);
end);
THorse.Listen(9000);
end.

Terminal:

cd examples/crud
crab-pascal run crud.dpr
# Server listening on port 9000...

Mantenha este terminal aberto. Use Postman ou cURL em outra janela.



Importar a collection


Caminho mais rápido a partir de postman-guide:

• Copie a collection JSON do doc (CRUD + time-server completos)

• Postman → Import → Raw text → colar → Import

• Variável de ambiente baseUrl = http://localhost:9000

Alternativa: importar cURLs individuais — o Postman converte automaticamente.



Requisições de exemplo


Listar produtos:

curl -s http://localhost:9000/produtos | jq

Criar produto:

curl -X POST http://localhost:9000/produtos \
-H "Content-Type: application/json" \
-d '{"nome":"Widget","preco":19.99}'

Time server (porta 9001):

curl http://localhost:9001/horaservidor

JSON esperado inclui timestamp ISO e rótulo do servidor — prova helpers de data SysUtils e roteamento Horse.



O que o teste Postman valida


Diferente de unit tests que mockam HTTP, este fluxo exercita:

• Registro Horse Get/Post/Put/Delete

• Handlers em procedures anônimas (estilo closure Delphi)

• Serialização System.JSON

• Collections genéricas em ProdutoService.pas

• Estabilidade de processo longo

Quando um sprint quebra paridade Horse, o Postman fica vermelho antes de issues vagas "API quebrou".



CI e smoke local


Collections Postman completas em CI precisam Newman ou script wrapper. Localmente, tests/test_exemplos_completo.ps1 roda smoke mais amplo (servidores Horse marcados como dependentes de ambiente no review Sprint 1).

Divisão pragmática:

•
Loop do dev: Postman + crab-pascal run

•
Gate CI: cargo test + E2E Horse onde mocks headless existem (Sprint 16+)



Troubleshooting


Sintoma
Correção

Connection refused
Servidor não iniciado ou porta errada

Array JSON vazio
Store in-memory fresh — POST primeiro

404 na rota
Conferir string da rota vs path da collection

Erro de compilação na unit Horse
Verificar search paths em crabpascal.toml

Referência: usage/postman-guide. Fonte: examples/crud/ no Bitbucket.



Variáveis de ambiente e compartilhamento em time


Exporte environments Postman com portas fixas por máquina:

{
"name": "CrabPascal Local",
"values": [
{ "key": "crudBase", "value": "http://localhost:9000" },
{ "key": "timeBase", "value": "http://localhost:9001" }
]
}

Compartilhe collection + environment JSON na wiki do time — o guia Mintlify traz blocos copy-paste. Para regressão automatizada depois, Newman (newman run collection.json) pode gatear releases quando mocks Horse headless entrarem no CI; até lá, Postman manual continua sendo o teste de integração honesto que devs Delphi já conhecem.



Próximo da série


Post 037 — Nova arquitetura v2.0.1 explicada cobre por que paramos de hardcodar cada chamada RTL em Rust e passamos a carregar units .pas reais dos search paths do .dproj.

Published on dev.to/@crabpascal · Código em CrabPascal