Testes com emulador AWS: 5 mitos que doem em produção
O emulador oficial da AWS é útil, mas os mitos sobre testes com emulador AWS custam caro. Veja onde a fidelidade falha e o que exige a AWS real.

O pior problema de integração que já enfrentei estava verde. Todas as verificações passaram no CI, o deploy foi para produção e vinte minutos depois um engenheiro de plantão encarava uma fila cheia de mensagens envenenadas, porque o comportamento real do SQS diferia do stub em exatamente um ponto que ninguém tinha pensado em checar. Então, quando a AWS lançou o próprio emulador, um workspace Rust com um crate por serviço, gerado a partir dos mesmos modelos Smithy que alimentam os SDKs reais, minha primeira reação não foi empolgação. Foi: ótimo, agora vamos descobrir onde ele mente. Todo emulador mente em algum ponto, e testes com emulador AWS só funcionam se você souber onde estão as mentiras.
Mito 1: “Testes verdes contra um emulador AWS significam que funciona na AWS”
Essa é a crença que machuca as pessoas, e a documentação do próprio projeto é surpreendentemente honesta sobre isso. A AWS publica pontuações de fidelidade por serviço a cada versão e registra as lacunas em um diretório literal, issues/things-that-do-not-work/, dentro do repositório. Esse diretório é a primeira coisa que você deve ler antes de escrever qualquer teste. Early adopters já bateram nesses limites: definições do Step Functions que usam o campo Assign não funcionam, e o suporte ao Lambda para código Python está incompleto a ponto de um workflow que roda sem problemas no MiniStack travar no emulador oficial. Nada disso é escândalo, é o estado normal de um emulador jovem. O escândalo é tratar uma suíte verde como prova de qualquer coisa além de “seu código funciona contra a interpretação que o emulador faz da API”.
O modelo mental certo é cobertura, não verdade. O emulador cobre os formatos de requisição que seu SDK envia e devolve respostas plausíveis. Ele não cobre o comportamento de throttling, os atrasos de propagação entre serviços nem as mil peculiaridades não documentadas de um sistema distribuído globalmente. Esta é a mesma lacuna entre especificação e implementação que aparece em toda infraestrutura: o modelo Smithy diz qual é o formato no fio, mas não consegue dizer que o SQS real às vezes entrega uma mensagem duas vezes dentro do visibility timeout, ou que a propagação real do IAM leva segundos e que sua role recém-criada vai falhar nas três primeiras invocações. Seus testes passaram porque o emulador nunca teve a chance de ser eventualmente consistente.
Mito 2: “Consigo validar políticas IAM e controles de segurança localmente”
Não, e a AWS diz isso em linguagem simples na página de segurança do emulador. Não o use para testar políticas IAM ou limites de permissão, políticas baseadas em recurso como bucket policies, políticas de chaves KMS, acesso entre contas ou entre regiões, nem qualquer outro controle de segurança. Alguns serviços avaliam IAM para usuários e roles criados dentro do emulador, mas não do jeito que a AWS faz. O emulador nunca nega uma requisição assinada com a própria chave. Uma requisição que a AWS negaria pode ser bem-sucedida localmente, o que significa que o emulador não é apenas inútil para testes de segurança, ele é ativamente enganoso. Ele vai te entregar um falso negativo com a maior naturalidade.
Já vi times aprenderem isso do jeito caro. Um desenvolvedor aperta uma bucket policy, roda a suíte local, vê tudo verde e faz o deploy. Aí o job noturno contra a conta sandbox quebra, porque a política agora bloqueia a role de replicação. Ou o caso inverso, bem pior: a política fica permissiva demais, tudo passa em todo lugar, e você descobre meses depois, numa auditoria, que seu bucket “privado” era legível por qualquer principal autenticado. A lógica de políticas é um dos pontos onde a autenticação na nuvem tem pontos cegos reais, e nenhum emulador vai te salvar deles. Se você quer verificar o comportamento de políticas, precisa de avaliação real do IAM. Isso significa uma conta real, de preferência um sandbox dedicado com SCPs restringindo o que ele pode alcançar, e testes que afirmam negações, não apenas sucessos:
import boto3
import pytest
from botocore import UNSIGNED
from botocore.config import Config
from botocore.exceptions import ClientError
def test_private_bucket_denies_anonymous_read():
# Runs only in the nightly job, against a dedicated sandbox account.
s3 = boto3.client("s3")
s3.put_object(Bucket=SANDBOX_BUCKET, Key="probe.txt", Body=b"x")
anon = boto3.client("s3", config=Config(signature_version=UNSIGNED))
with pytest.raises(ClientError) as err:
anon.get_object(Bucket=SANDBOX_BUCKET, Key="probe.txt")
assert err.value.response["Error"]["Code"] == "AccessDenied"
Mais uma coisa antes de apontar toda a sua frota de CI para essa ferramenta: a telemetria vem ativada por padrão. A AWS diz que ela é mínima e nunca inclui conteúdo de requisições ou credenciais, e não tenho motivo para duvidar disso, mas minha regra é que ferramentas de desenvolvimento não enviam dados para lugar nenhum a menos que eu tenha pedido. Rode com --telemetry off ou defina EMULATOR_TELEMETRY=off no ambiente de CI e siga em frente.
Mito 3: “A fidelidade do protocolo de rede é a parte difícil”

Acertar o formato no fio é o mínimo, e é a parte que a AWS sempre ia acertar. Os SDKs deles são gerados a partir de modelos Smithy, o emulador é gerado a partir dos mesmos modelos, então cada operação, cada campo opcional e cada formato de erro correspondem à API documentada. Um comentador do HN resumiu bem: a geração guiada por especificação cobre todas as variantes de todo endpoint, enquanto emuladores da comunidade historicamente implementam o subconjunto mais usado e aproximam o resto. Essa é uma vantagem real da ferramenta oficial.
Mas a fidelidade de formato é a parte fácil. A parte difícil é a fidelidade comportamental, e ninguém a tem: nem o emulador da AWS, nem o LocalStack, nem o moto, nem o Floci. A fidelidade comportamental é aquilo que não está em nenhum modelo: um cold start do Lambda muda o tempo observável o suficiente para estourar o timeout do seu cliente? O throttling do DynamoDB aparece como erro retentável na taxa que o seu tráfego de produção realmente atinge? O teardown do CloudFormation trava por vinte minutos quando os recursos foram criados numa ordem legal, mas infeliz? Um profissional perguntou se dava para apontar um projeto CDK inteiro para o emulador e testar o cdk deploy de ponta a ponta. Minha resposta: dá, e você deve fazer isso, mas só para pegar erros de síntese e de formato de API. A dinâmica de deploy, como comportamento de rollback, ordem de substituição de recursos e detecção de drift, são exatamente as partes em que um emulador é pior, porque são propriedades emergentes do plano de controle real.
- Fidelidade de formato — formatos de requisição e resposta, códigos de erro, serialização. Emuladores são bons nisso, e o gerado a partir do Smithy deveria ser o melhor da categoria.
- Fidelidade de estado — ciclos CRUD, listagem, filtragem, paginação. Em geral bom entre os emuladores, com lacunas por serviço que você precisa checar.
- Fidelidade comportamental — tempo de consistência, throttling, falhas parciais, peculiaridades do ciclo de vida dos recursos. Ninguém tem isso. Planeje de acordo.
Mito 4: “Emuladores são drop-in, basta trocar o endpoint”
O discurso de marketing de todo emulador é “defina uma variável de ambiente e pronto”. Para um smoke test rápido, isso é verdade. O modo servidor escuta em 127.0.0.1:9297 via HTTPS com um certificado autoassinado, e apontar a CLI para ele fica assim:
export AWS_ENDPOINT_URL=https://localhost:9297
export AWS_ACCESS_KEY_ID=emulator
export AWS_SECRET_ACCESS_KEY=emulator
export AWS_REGION=us-east-1
# self-signed cert: don't disable verification globally, scope it
aws s3 ls --no-verify-ssl
A história do drop-in desmorona na escala de uma suíte de testes. Os problemas práticos que as pessoas encontram na primeira semana: não existe reset rápido de estado. Se sua suíte precisa de um estado limpo entre os testes (e quem usa o moto está acostumado exatamente a isso, um decorator e o mundo está novo), sua opção atual é reiniciar o processo. Isso é tolerável para dez testes e doloroso para dez mil. Também não há emulação de multi-conta nem de Organizations, o que inviabiliza qualquer teste que modele a estrutura real de contas. E se você estiver tentado pelo modo Rust embarcado, uma instância isolada em processo para cada teste, sem endpoint nem certificados para gerenciar, que é um design genuinamente bom, leia primeiro a seção de custo de build. O workspace tem um crate por serviço da AWS, um build de debug completo quer algo na ordem de 100 GB de espaço em target/, e seu primeiro cargo test compila o emulador junto com o seu código. O conselho deles de compartilhar um CARGO_TARGET_DIR, cachear o target/ no CI e fixar um commit de release não é enfeite opcional. É a diferença entre um job de CI de cinco minutos e um de cinquenta.
use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions, Telemetry};
let emulator = AwsEmulatorEmbedded::new(
EmbeddedOptions::default().telemetry(Telemetry::Off),
);
let http_client = emulator.http_client();
// wire http_client into your SDK client config — no endpoint,
// no env vars, one isolated instance per test
Mito 5: “O emulador próprio da AWS acaba com o LocalStack, o moto e o resto”
Ouvi versões disso poucas horas depois do anúncio, e isso entende mal o que os concorrentes de fato vendem. O valor do LocalStack nunca foi apenas “reimplementamos a API do S3”. São anos de ajuste comportamental por serviço, gerenciamento de estado, integração com testcontainers, ergonomia de CI e uma comunidade que já registrou o bug em que você está prestes a bater. O reset de estado por teste do moto, via decorators, é uma funcionalidade de fluxo de trabalho, não de API, e o emulador da AWS ainda não tem resposta para isso. Os fãs do Floci apontaram que ele também cobre GCP e Azure. Se o seu ambiente é multi-nuvem, um ambiente local unificado vale mais do que uma nuvem única com fidelidade maior.
Também existe uma questão legítima de confiança sobre longevidade. O primeiro comentário da thread fez a pergunta que todo mundo estava pensando: isso é um produto real que a AWS vai manter, ou um exercício? O repositório aceita relatórios de issues, mas não pull requests, o que é uma escolha defensável para uma base guiada por especificação, mas também significa que a comunidade não pode corrigir lacunas por conta própria. Se o time for realocado, você fica com um snapshot licenciado sob CC0. Minha posição: avalie como qualquer dependência com um único mantenedor. É razoável adotar, imprudente apostar tudo nela. O mesmo ceticismo vale para a enxurrada de comentários eufóricos do tipo “agentes escreveram isso em Rust, o fosso acabou”. O fosso nunca foi a superfície da API. É a excelência operacional, e emular a API sempre foi a parte barata. Vimos essa dinâmica acontecer com SQLite distribuído e raft também: copiar a interface leva semanas, igualar a semântica de falhas leva anos.
O que ainda precisa rodar contra a infraestrutura real da AWS

Esta é a divisão que eu uso em projetos reais, e até agora não me deixou na mão. Tudo que é rápido, determinístico e focado em formato roda contra o emulador a cada commit: serialização, tratamento de erros dos códigos documentados, lógica de retry, máquinas de estado que dependem apenas de ciclos CRUD. Isso é 90% da sua suíte em número de testes e talvez 10% em risco.
Os 10% restantes rodam toda noite contra uma conta sandbox real e isolada, e é a parte que pega o que de fato te acorda de madrugada:
- IAM e políticas de recurso. Afirme negações explícitas, não apenas os caminhos permitidos. O emulador estruturalmente não consegue fazer isso: ele nunca nega uma requisição assinada com a própria chave.
- Qualquer coisa com atraso de propagação. Roles novas, mudanças de DNS, concessões KMS. Se seu código cria um recurso e o usa imediatamente, só a AWS real vai dizer se você precisa de um loop de retry.
- Comportamento de at-least-once e idempotência. Entregas duplicadas do SQS, retries do Lambda por timeout, falhas parciais em lote. Emuladores são educados; a produção não é.
- Ciclo de vida da infraestrutura. Ciclos completos de
cdk deploy/terraform applye destroy, especialmente a ordem de teardown e os caminhos de rollback. - Throttling e limites de cota. Se isso importa com a carga de produção, só existe com o comportamento real da API de produção.
A conta sandbox precisa de guardrails próprios: service control policies limitando o que ela pode fazer, alertas de orçamento e um varredor que apague recursos esquecidos, porque seu job noturno vai deixar coisas vazando. Isso é overhead operacional real, e é exatamente por isso que o emulador é valioso: ele mantém 90% do seu ciclo de feedback rápido e barato, para que você possa se dar ao luxo de tornar os últimos 10% honestos.
O trabalho de um emulador é tornar seu ciclo de feedback rápido. Não é deixar você confiante. Confiança ainda custa chamadas reais à API.
O emulador oficial da AWS é uma ferramenta genuinamente boa: cobertura gerada a partir da especificação, um modo embarcado com isolamento real e uma documentação refrescantemente honesta sobre o que ele não consegue fazer. Adote-o pelo que ele é: a forma mais rápida possível de estar quase sempre certo. Depois decida, deliberadamente e por escrito, quais testes podem reivindicar o outro tipo de certeza, aquele que só vem de uma infraestrutura que de fato consegue negar sua requisição, limitar seu cliente e entregar sua mensagem duas vezes.


