AWS Emulator testa aplicações AWS localmente sem custo de nuvem

O que é o AWS Emulator

A AWS↳AWS20 conteúdosE-mails de verificação com AWS SES + Lambda (Node.js) e Terraform: do zero ao envioDevSecOps · out 2025Codex na AWS: chegada do agente da OpenAI à nuvem da AmazonDevSecOps · abr 2026Salesforce e AWS ampliam colaboração em IA, CRM e marketplaceDevSecOps · nov 2023Ver tudo em DevSecOps → anunciou o AWS Emulator, um emulador local dos serviços da AWS que roda inteiramente na sua máquina. Ele expõe um endpoint HTTPS local que fala as mesmas APIs que o AWS CLI, os AWS SDKs e agentes de código (como Kiro ou Claude Code) já usam contra a nuvem real. A diferença é que as chamadas nunca saem do seu laptop.

Não existe taxa adicional de serviço para rodar o emulador: você só paga por recursos da AWS quando efetivamente faz deploy na nuvem. O código-fonte está no GitHub, e a instalação é via pacote RPM ou Debian no Linux; em macOS e Windows, a Amazon não publica imagem pronta e você precisa construir uma imagem Docker a partir de um Dockerfile disponível na documentação.

Instalando e subindo o emulador

Em Amazon Linux 2023, a instalação é direta via dnf, puxando o pacote de um endereço de downloads da AWS:

PKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest
sudo dnf install -y $PKG/aws-emulator-x86_64.rpm

aws-emulator -v

O pacote registra o binário aws-emulator em /usr/bin/, então ele já entra no PATH. Para efetivamente subir o servidor, rode o comando sem a flag:

aws-emulator

O processo sobe um servidor HTTPS em 127.0.0.1:9297, gera credenciais próprias, um arquivo de configuração e um certificado, e grava tudo em ~/.aws/emulator/9297/. O log sai em JSON lines e mostra o endereço, o arquivo de config e o certificado. Separadamente, o emulador expõe o endpoint /__admin/health, que scripts de CI podem usar para esperar o serviço ficar pronto antes de rodar os testes.

Para apontar o AWS CLI para o emulador em vez da nuvem real, é preciso exportar um conjunto de variáveis de ambiente e, principalmente, remover qualquer credencial real do shell:

export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

As chaves de acesso geradas pelo emulador começam com EMULATOR, de propósito, para que ninguém confunda com uma chave real da AWS. Qualquer requisição assinada com outra chave é rejeitada. Para confirmar que o shell está falando com o emulador e não com a nuvem, dá pra checar o endpoint de saúde e a identidade do chamador:

curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

O emulador trabalha com uma única conta fixa, 000000000000. É assim que você sabe, sem ambiguidade, que está testando local e não em produção.

Rodando comandos reais contra o emulador

Com o endpoint configurado, os comandos do AWS CLI que você já usa continuam funcionando sem alteração de código de aplicação. Um teste que cria um bucket, sobe um objeto e lista o conteúdo roda exatamente como rodaria na nuvem:

aws s3 mb s3://local-getting-started

echo "hello from the emulator" > hello.txt
aws s3 cp hello.txt s3://local-getting-started/

aws s3 ls s3://local-getting-started/

O mesmo vale para fluxos mais elaborados com DynamoDB, inclusive os que um agente de código executa sozinho. No próprio anúncio, a AWS mostra o Kiro criando uma tabela, gravando um item e lendo de volta, tudo contra o emulador em vez da conta real:

aws dynamodb create-table --table-name kiro-demo \
 --attribute-definitions AttributeName=id,AttributeType=S \
 --key-schema AttributeName=id,KeyType=HASH \
 --billing-mode PAY_PER_REQUEST

aws dynamodb put-item --table-name kiro-demo \
 --item '{"id": {"S": "item-1"}, "msg": {"S": "hello from kiro"}}'

aws dynamodb get-item --table-name kiro-demo \
 --key '{"id": {"S": "item-1"}}'

Para quem já tem suite de testes, o caminho é o mesmo: subir o emulador antes do job, exportar as mesmas variáveis no script de CI que roda os testes, e deixar a suíte seguir sem mudança de código.

Modo embutido para testes de verdade

Rodar o emulador como processo separado funciona bem para explorar comandos manualmente, mas em uma suíte de testes automatizados↳Testes automatizados4 conteúdosComo migrei meus testes automatizados de Java para Ruby… Será que fiz bem?Dev (Back & Front) · jun 2019TDD em Nodejs: conhecendo o JestDev (Back & Front) · mar 2019Arquitetura Hexagonal na prática com exemplos em PythonDev (Back & Front) · mai 2025Ver tudo em Dev (Back & Front) → o ideal é não depender de um servidor externo. Para isso existe o modo embutido (embedded), que instancia o emulador dentro do próprio processo de teste e conecta direto no cliente HTTP do SDK, sem passar pela rede.

Cada instância embutida mantém seu próprio estado isolado, então testes não compartilham bucket, tabela ou fila entre si, e dá pra rodar vários em paralelo sem interferência. Hoje esse modo está disponível só para o AWS SDK for Rust, via o crate aws-emulator-embedded, adicionado em [dev-dependencies] no Cargo.toml:

use aws_emulator_embedded::{AwsEmulatorEmbedded, EmbeddedOptions};
use aws_sdk_dynamodb::types::{
 AttributeDefinition, AttributeValue, KeySchemaElement, KeyType,
 ScalarAttributeType, BillingMode,
};

#[tokio::test]
async fn put_then_get_returns_the_item() {
 let emulator = AwsEmulatorEmbedded::new(EmbeddedOptions::default());
 let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
 .http_client(emulator.http_client())
 .region(aws_config::Region::new("us-east-1"))
 .credentials_provider(emulator.aws_credentials_provider())
 .load()
 .await;
 let ddb = aws_sdk_dynamodb::Client::new(&config);

 ddb.create_table()
 .table_name("emulator-demo-table")
 .attribute_definitions(
 AttributeDefinition::builder()
 .attribute_name("id")
 .attribute_type(ScalarAttributeType::S)
 .build().unwrap())
 .key_schema(
 KeySchemaElement::builder()
 .attribute_name("id")
 .key_type(KeyType::Hash)
 .build().unwrap())
 .billing_mode(BillingMode::PayPerRequest)
 .send().await.unwrap();

 ddb.put_item()
 .table_name("emulator-demo-table")
 .item("id", AttributeValue::S("item-1".into()))
 .item("msg", AttributeValue::S("hi".into()))
 .send().await.unwrap();

 let got = ddb.get_item()
 .table_name("emulator-demo-table")
 .key("id", AttributeValue::S("item-1".into()))
 .send().await.unwrap();

 assert_eq!(got.item().unwrap().get("msg").unwrap().as_s().unwrap(), "hi");
}

O que quebrou no caminho

Quando o emulador roda como processo separado, nem todo SDK confia no certificado gerado automaticamente de bate-pronto. O AWS SDK for Java, por exemplo, exige configurar um trust store apontando para o certificado do emulador antes de qualquer chamada funcionar, o que não é óbvio na primeira tentativa.

Outro ponto de atrito é a cobertura de operações. Se o emulador ainda não implementa uma chamada específica de um serviço, ele devolve HTTP 501 (Not Implemented), e o teste falha na hora, em vez de simular um comportamento parecido com o da AWS. Isso é bom porque evita falso positivo, mas significa que nem toda suíte roda de primeira sem ajuste.

Como a AWS mede o quanto o emulador é confiável

Um emulador só vale a pena se um teste que passa nele também passar na AWS de verdade. Para garantir isso, a equipe publica testes de fidelidade: programas curtos que usam um AWS SDK para rodar um fluxo real (por exemplo, gravar um objeto, ler e depois apagar) e comparam a resposta do emulador com a resposta da AWS real, incluindo código de status, corpo e a mensagem exata de erro.

A cada release, a AWS publica a pontuação de fidelidade por serviço no formato k de n: 40 de 50, por exemplo, significa que 40 dos 50 testes daquele serviço passam. O conjunto completo de testes está público no repositório aws-emulator-evaluation-suite no GitHub, incluindo os que ainda falham, então dá pra auditar exatamente o que foi verificado e rodar os testes você mesmo.

Em resumo: uma pontuação baixa não significa regressão, pode significar que a equipe acabou de adicionar testes mais rigorosos para um serviço que, na prática, está melhorando.

Segurança e limites que importam para quem roda isso

O emulador é construído e mantido por agentes de IA↳Agentes de IA42 conteúdosOpera passa a integrar ChatGPT, Claude e outros agentes de IADev (Back & Front) · mar 2026Operações mais inteligentes, decisões mais rápidas: o impacto da IA agêntica na rotina de TIAI · abr 2026Adobe aposta em orquestração de agentes de IA: o que muda para devsDev (Back & Front) · abr 2026Ver tudo em AI → a partir dos modelos de API da AWS, usando Amazon Bedrock AgentCore Runtime Instances, AWS CodePipeline e AWS CodeCommit. Um grupo de agentes identifica lacunas comparando o emulador com a AWS real e com os modelos Smithy publicados; outro grupo implementa a correção; e um agente de segurança independente revisa cada mudança de forma adversarial, antes e depois de ir para o pipeline de release.

Isso não dispensa cuidado de quem usa a ferramenta. Por padrão, o emulador escuta só em 127.0.0.1 e rejeita qualquer requisição que não esteja assinada com as próprias chaves geradas, mas a segurança do seu uso continua sendo responsabilidade compartilhada. Três limites merecem atenção antes de confiar demais no emulador:

• Ele não avalia políticas de IAM nem políticas baseadas em recurso da forma como a AWS faz, então uma chamada que a AWS negaria pode ter sucesso no emulador.
• Cada instância do emulador atua como uma única conta (000000000000), sem comportamento cross-account ou cross-Region.
• A fidelidade varia por serviço e por operação, então vale checar a pontuação antes de confiar cegamente em um serviço menos coberto.

A própria AWS é direta sobre isso: não use o emulador para testar se sua aplicação é segura, e mantenha credenciais reais fora do ambiente dos jobs de teste. O teste de segurança de verdade continua sendo feito contra a AWS real antes de produção.

O que muda para quem trabalha com DevOps e SRE

O ganho prático está no ciclo de feedback. Um agente de código, ou um pipeline de CI, que hoje espera um deploy em uma Region para checar se uma tabela DynamoDB foi criada corretamente passa a rodar esse mesmo teste em milissegundos, sem fila de deploy e sem custo de recurso provisionado. Isso baixa o custo de iterar: menos tempo de CI, menos recurso provisionado só para teste, menos atrito no loop de desenvolvimento local.

O trade-off é claro e está documentado pela própria AWS: fidelidade parcial e ausência de avaliação de IAM significam que o emulador reduz ciclo, mas não substitui validação de segurança e de política de acesso contra a conta real.

Para quem decide pipeline de teste, a régua prática é separar camadas: use o emulador para validar lógica de aplicação e integração com a API rapidamente, e mantenha um estágio contra a AWS real (ou pelo menos contra uma conta de staging) antes de qualquer coisa ir para produção. É o mesmo princípio de sempre: automatize o que é repetitivo e determinístico, meça o que ainda depende de comportamento real da nuvem, e não troque uma validação de segurança por velocidade de loop.

Fonte: AWS News Blog