Secção Mocks

A secção Mocks é onde define as respostas simuladas que o Aseptic serve quando uma dependência é resolvida como mock. Permite-lhe trabalhar sem ligação à cloud e sem iniciar o core que o seu micro chama.

Não precisa de iniciar nada para editar mocks: o catálogo vive no disco (.aseptic/mocks/<serviço>.json) e é servido com recarga a quente, por isso uma alteração aplica-se ao instante mesmo com o cenário em execução.

A árvore: serviços → endpoints

O lateral mostra uma árvore de serviços (os cores mockáveis) e, dentro de cada um, os seus endpoints numa lista plana, por ordem alfabética de caminho. Cada linha mostra o caminho completo relativo à base do serviço, para que dois endpoints com o mesmo final (/orders/lines e /invoices/lines) não se confundam. Para reduzir um catálogo grande, a pesquisa do lateral filtra por nome de serviço ou por caminho.

Um serviço é mockável se for uma dependência de algum micro (ou se criar o seu ficheiro em .aseptic/mocks). Pode mostrar ou ocultar os serviços que ainda não têm stubs.

Criar um stub

Prima Novo stub (ou o menu «⋮») e escolha o serviço de destino —um do catálogo ou um novo que se cria ao guardar—. Um endpoint define-se com:

Método e caminho (relativo ao caminho base do serviço).
Uma ou várias variantes de resposta.

Há duas formas de preencher o corpo:

A partir de OpenAPI: se o serviço declarar uma especificação OpenAPI (no manifesto do micro, ou derivada do seu URL cloud), selecione a operação e o Aseptic gera um modelo do corpo.
Manual: se não houver OpenAPI, escreve o corpo JSON à mão.

O ícone de OpenAPI junto ao serviço abre a especificação num visor próprio, com as suas operações navegáveis, em vez de lhe deixar o ficheiro cru à frente.

Grupos e serviços

Cada serviço da árvore tem a sua ficha («Editar serviço» no seu menu, ou a engrenagem do editor de um stub). Num grupo criado à mão —para juntar stubs que não são de nenhuma dependência, como todos os /notice/...— editam-se o nome, o prefixo, o URL base (o endereço real a que o prefixo corresponde, para onde vai a chamada real) e o OpenAPI. De uma dependência edita-se tudo menos o nome, que é o seu id nos manifestos: o prefixo e o URL base guardam-se no manifesto de cada micro que a declara, e os stubs sob o prefixo anterior passam para o novo.

Ao escolher uma operação do OpenAPI, o Aseptic deduz o caminho que o cliente chama mesmo que a especificação declare outro prefixo (os seus servers, o context-path, um troço em comum com o prefixo do serviço). Se essa operação já tem stub, não se cria outro ao lado: abre-se o existente com uma variante nova a partir do OpenAPI.

Ao criar um stub, além de partir de uma operação do OpenAPI, podes partir de uma chamada que já chegou ao mock sem stub: fica com o seu método e o seu caminho.

A porta do servidor de mocks e o token para OpenAPI (enviado como Authorization: Bearer ao transferir especificações protegidas) estão em Configuração do mock, no menu «⋮» da secção.

Variantes: a unidade de trabalho

Um endpoint pode ter várias variantes (por exemplo uma 200 e uma 500). Cada variante tem a sua etiqueta, código de estado, corpo, cabeçalhos e uma latência opcional em milissegundos para simular lentidão.

A variante selecionada expande-se em linha com o seu corpo, cabeçalhos e ajustes juntos. A variante que se serve marca-se à parte com um comutador (é independente da que está a editar): é a resposta que o Aseptic devolverá a quem chamar esse endpoint.

Sobre o corpo há três botões: Formatar indenta-o (e guarda essa indentação), Preencher modelo gera-o a partir do OpenAPI e Ver com formato abre-o num visor grande, que não edita nada e serve para ler uma resposta que não cabe no quadro.

Pode duplicar uma variante para partir de uma parecida. Um endpoint que já não quer servir apaga-se a partir do seu menu.

Corpos de qualquer tipo: imagens, PDF, ficheiros

Por cima do corpo de cada variante escolhes Texto, Sem corpo, Ficheiro ou Fluxo:

Texto: com um seletor de formato —JSON, texto simples, HTML, XML, JavaScript, CSS, CSV, YAML, Markdown ou formulário— que define o Content-Type servido e dá a cada um o seu realce e o seu Formatar (um formulário é compactado em a=1&b=2). Um tipo escrito à mão nas definições da variante cai na sua família (application/problem+json é JSON).
Ficheiro: uma imagem, um PDF, um zip, um áudio… o que for. Carrega em Escolher ficheiro ou larga-o por cima, e é servido byte a byte. Se for uma imagem pequena, verás a miniatura.
Sem corpo: só o código e os cabeçalhos, para um 204 ou um 304; não se inventa nenhum Content-Type.
Fluxo: a resposta chega em fragmentos, cada um após a sua pausa, para testar um cliente que mostra ou conta enquanto recebe. Escolhes como se escreve cada fragmento: Eventos SSE (text/event-stream, com nome de evento e id opcionais), NDJSON (um JSON por linha) ou Texto fragmentado.

O tamanho decide onde fica guardado: até 256 KB vai dentro do catálogo, e viaja com ele; se for maior é copiado para .aseptic/mocks/files/<serviço>/ e a variante referencia-o. Sem Content-Type, é deduzido da extensão (.png → image/png, .pdf → application/pdf); os restantes cabeçalhos —Content-Disposition para forçar uma transferência, Cache-Control…— põem-se em Cabeçalhos como sempre. Ao exportar um serviço ou um cenário, os ficheiros vão incorporados, por isso o que partilhas não depende dessa pasta.

Regras: responder consoante o pedido

Por cima das variantes há um bloco Regras. Cada regra diz «quando se cumprirem estas condições, serve esta variante», e avaliam-se por ordem: ganha a primeira que casa. Se não casar nenhuma, serve-se a variante ativa — portanto um endpoint sem regras comporta-se tal como antes. A última linha do bloco, fixa, lembra exatamente isso.

Uma condição olha para um dado do pedido, sem sintaxe para aprender: query ou cabeçalho pelo nome, ou corpo por um caminho com pontos (pedido.cliente.tipo; um número entra numa lista, pedido.linhas.0.sku). Compara com é igual a, é diferente de, existe ou não existe. Todas as condições de uma regra têm de cumprir-se em conjunto; para um «ou», acrescenta-se uma segunda regra — é para isso que a lista está ordenada. A ordem muda-se com as setas de cada regra: mover uma regra é mudar a sua prioridade.

A regra aponta para a variante pela sua etiqueta, não pela posição, para que reordenar variantes não mude em silêncio o que se serve. Por isso, num endpoint com regras, duas variantes não se podem chamar igual. Se mudar o nome a uma variante para a qual apontava uma regra, a regra fica marcada em atenção e deixa de se servir até a corrigir.

Testar simula um pedido ali mesmo — query, cabeçalhos e corpo — e diz que variante sairia e que regra a escolheu. Não é preciso ter o cenário em marcha. E quando está, o dock Chamadas mock marca cada chamada com a regra que a decidiu, de modo que duas chamadas iguais com respostas diferentes se explicam sozinhas.

A partir do terminal é o mesmo: aseptic mock probe POST "/v1/pedidos?tipo=premium", com -H 'X-Vip: 1' para os cabeçalhos e -d '{...}' para o corpo.

Guardado automático

O editor de mocks guarda sozinho, com um pequeno atraso, enquanto escreve; verá um indicador «Guardado». Salvaguardas:

Só se persistem estados válidos: um corpo JSON a meio não quebra o mock servido —mantém-se o último válido no disco e o erro marca-se em linha—.
Um stub novo não se persiste até ter método e caminho utilizáveis.
A eliminação é sempre explícita, com confirmação.

Mock Studio: de uma chamada real a um stub

Quando um cenário corre e um micro chama um mock que ainda não tem resposta, essa chamada aparece no dock Chamadas mock. A partir daí pode criar um stub com um clique a partir da chamada observada: vai direto ao endpoint que quer completar, sem o procurar. Também pode testar o que o mock responderia sem iniciar nada.

Chamada real: capturar a resposta do serviço

Às vezes não queres inventar o corpo: queres o que o serviço verdadeiro devolve. Cada endpoint tem um interruptor Chamada real. Enquanto estiver ligado, esse endpoint deixa de servir a sua variante: o pedido sai para o serviço real, a resposta é devolvida tal e qual a quem chamou e é gravada como variante «Real» com o seu código, que fica ativa. Ao desligá-lo, o mock responde o último que o serviço disse, já sem sair para a rede.

Para onde chama: o microserviço do cenário se estiver em execução e, caso contrário, o URL de nuvem da dependência. O ícone «i» do interruptor diz o destino exato; se o serviço não tiver nenhum, o interruptor fica desligado e explica porquê.
Verbos que alteram dados: ligá-lo num POST, PUT ou DELETE pede confirmação indicando o destino. Não está proibido —capturar a resposta de uma criação é um caso legítimo— mas ali executa-se mesmo.
Uma variante por código: Real 200, Real 404… Capturar mil chamadas não cria mil variantes; atualiza a do código que chegar.
O que não for texto (uma imagem, um PDF) é gravado como ficheiro da variante; o que passar de 1 MB é servido mas não gravado.

Os endpoints em captura são marcados com a etiqueta real na árvore, para que não te fique nenhum a sair para a rede sem dares por isso.

Importar e exportar

Com os ícones de importar/exportar do painel:

Exportar os endpoints de um serviço (ou de vários) para um ficheiro JSON.
Importar um JSON próprio ou uma coleção Postman (as suas pastas mapeiam para serviços).

Útil para partilhar um catálogo de mocks ou reutilizá-lo entre cenários.

O mesmo a partir do CLI

Tudo isto existe também no CLI: aseptic mock services, mock catalog, mock save, mock set-active, mock skeleton, mock from-call, mock probe, mock capture, mock put-file, mock import / export. Ver a referência do CLI.