O que é o Fakecloud

O Fakecloud e um emulador local da AWS criado para facilitar testes de integração sem depender da nuvem de verdade. Em vez de criar recursos reais na sua conta AWS - e pagar por isso - você sobe um servidor local que imita o comportamento dos principais serviços da Amazon.

O projeto surgiu da necessidade clássica de qualquer time que usa AWS: como testar o código que interage com S3, SQS ou DynamoDB sem precisar de internet, de credenciais reais ou de um ambiente de staging caro? A resposta e emular esses serviços na própria máquina do desenvolvedor ou no CI/CD.

O Fakecloud se posiciona como uma alternativa mais leve e focada em testes de integração do que ferramentas similares. Ele é open source, roda como um processo local e expõe endpoints compatíveis com o SDK oficial da AWS - o que significa que você não precisa mudar uma linha do seu código de produção para usar nos testes.

Como funciona

O funcionamento e simples: o Fakecloud sobe um servidor HTTP na sua máquina local que responde as mesmas chamadas de API que a AWS real responderia. Quando o seu código faz s3.putObject(), a requisição vai para http://localhost:4566/ em vez de https://s3.amazonaws.com/.

Você configura o endpoint personalizado nas variáveis de ambiente do SDK da AWS. O SDK não sabe a diferença - ele só ve um endpoint que responde no formato correto. O Fakecloud mantem o estado em memoria (ou em disco, conforme configuração), processa as chamadas e retorna respostas com o mesmo formato JSON/XML que a AWS original usaria.

A arquitetura interna e baseada em handlers por serviço: cada endpoint do S3, SQS, DynamoDB, Lambda e outros e implementado separadamente. Quando uma requisição chega, o router identifica o serviço e a operação (ex: PutObject, SendMessage) e delega para o handler correspondente. O resultado e guardado em memoria e retornado ao cliente.

Principais recursos

O Fakecloud cobre os serviços AWS mais usados no dia a dia de desenvolvimento:

  • Amazon S3: upload, download, listagem de buckets, pre-signed URLs e controle de ACL.
  • Amazon SQS: criação de filas, envio e recebimento de mensagens, dead-letter queues e visibilidade de mensagens.
  • Amazon DynamoDB: tabelas, índices secundários, operações de leitura/escrita e scan.
  • AWS Lambda: invocação síncrona e assíncrona de funções, com suporte a payloads customizados.
  • Amazon SNS: tópicos, subscrições e publicação de mensagens com fanout para SQS.
  • AWS SSM Parameter Store: leitura e escrita de parâmetros, útil para gerenciar configurações nos testes.

O diferencial e a zero configuração de nuvem: nenhuma conta AWS, nenhuma IAM key, nenhum custo. Tudo roda localmente com credenciais fictícias que o próprio SDK aceita no modo de endpoint customizado.

Como começar: instalação passo a passo

O Fakecloud pode ser iniciado de varias formas. A mais comum e via Docker, que não requer instalação adicional além do próprio Docker:

Docker run -p 4566:4566 fakecloud/fakecloud:latest

Com o container rodando, configure o seu SDK para apontar para o endpoint local. Em Python com boto3:

import boto3

client = boto3.client(
    's3',
    endpoint_url='http://localhost:4566',
    aws_access_key_id='test',
    aws_secret_access_key='test',
    region_name='us-east-1'
)

Em JavaScript/TypeScript com o AWS SDK v3:

import { S3Client } from '@aws-sdk/client-s3';

const client = new S3Client({
  endpoint: 'http://localhost:4566',
  credentials: { accessKeyId: 'test', secretAccessKey: 'test' },
  region: 'us-east-1',
  forcePathStyle: true,
});
💡
Dica

Use variáveis de ambiente para trocar o endpoint sem mudar o código. Defina AWS_ENDPOINT_URL=http://localhost:4566 nos testes e remova nos builds de produção.

Exemplo prático

Imagine que você tem um serviço que salva relatórios em PDF no S3 e dispara uma mensagem SQS para processar async. O teste de integração ficaria assim com o Fakecloud:

import boto3
import pytest

@pytest.fixture(autouse=True)
def setup_aws():
    s3 = boto3.client('s3', endpoint_url='http://localhost:4566', ...)
    sqs = boto3.client('sqs', endpoint_url='http://localhost:4566', ...)
    s3.create_bucket(Bucket='meus-relatórios')
    sqs.create_queue(QueueName='fila-processamento')
    yield

def test_salvar_e_enfileirar_relatorio():
    serviço = RelatorioService()
    resultado = serviço.salvar_relatorio(dados={'tipo': 'mensal'})
    
    assert resultado['status'] == 'enfileirado'
    mensagens = sqs.receive_message(QueueUrl=fila_url)
    assert len(mensagens['Messages']) == 1

Esse teste roda em menos de um segundo, sem internet e sem custo. Você pode rodar no CI/CD normal (GitHub Actions, GitLab CI) só adicionando o serviço do Fakecloud como container paralelo no pipeline.

🚀
Pro tip

No GitHub Actions, adicione o Fakecloud como service container: services: fakecloud: image: fakecloud/fakecloud:latest ports: ['4566:4566']. Assim ele sobe automaticamente antes dos testes e encerra depois.

Comparação com alternativas

O principal concorrente do Fakecloud e o LocalStack, que é mais antigo, mais completo e também muito popular. A diferença principal esta no escopo e na complexidade: o LocalStack tem versão Pro com dezenas de serviços AWS emulados, mas requer mais configuração e tem limitações na versão gratuita. O Fakecloud aposta na leveza e foco nos serviços mais usados.

Outra alternativa e usar o DynamoDB Local da própria Amazon para o banco, combinado com o MinIO para S3. Essa abordagem funciona, mas exige subir e configurar cada ferramenta separadamente - o Fakecloud unifica tudo em um único processo.

Resumo de quando usar cada um:

  • Fakecloud: projetos que usam S3, SQS, DynamoDB, Lambda e SNS - setup rápido, zero configuração.
  • LocalStack Pro: precisou de serviços menos comuns (Kinesis, Glue, Redshift) ou suporte comercial.
  • MinIO + DynamoDB Local: equipes que já tem infraestrutura Docker Compose estabelecida e preferem ferramentas dedicadas por serviço.

Pontos positivos e limitações

O ponto mais forte do Fakecloud e a compatibilidade direta com o SDK AWS oficial. Você não precisa de bibliotecas wrapper nem de mocks manuais - o mesmo código de produção roda nos testes. Isso reduz drasticamente a chance de o teste passar mas o código falhar em produção por uma diferença de comportamento entre o mock e a AWS real.

Outro ponto positivo e a velocidade: sem latência de rede, os testes de integração que normalmente levam vários segundos por requisição passam a rodar em milissegundos. Pipelines de CI ficam notavelmente mais rápidos.

⚠️
Atenção

O Fakecloud não emula 100% das nuances da AWS real. Regras de IAM, limites de throttling e comportamentos de consistência eventual do DynamoDB podem diferir. Use para testes de lógica de negócio, não para validar políticas de segurança.

As limitações existem: a cobertura de API não e 100% - funcionalidades avançadas de cada serviço podem não estar implementadas. Antes de adotar, verifique no repositório oficial quais endpoints do serviço que você usa estão cobertos.

Casos de uso reais

O Fakecloud serve bem para vários perfis de desenvolvimento:

  • Desenvolvedor backend individal: quer rodar testes de integração no laptop sem depender de um ambiente de staging na nuvem. Com o Fakecloud, o pytest ou jest local já cobre toda a lógica que interage com S3 e SQS.
  • Time com CI/CD no GitHub Actions ou GitLab CI: adiciona o Fakecloud como service container no pipeline e ganha testes de integração rápidos sem precisar de uma conta AWS dedicada para o CI.
  • Desenvolvedor de bibliotecas open source: quer que contribuidores rodem os testes sem precisar de credenciais AWS. O Fakecloud resolve o problema de onboarding de contributors externos.
  • Time de DevOps: quer validar scripts de infraestrutura (ex: Terraform, CDK) em ambiente local antes de aplicar na nuvem real, reduzindo custos de experimentação.

Dicas e boas práticas

💡
Dica

Crie um arquivo Docker-compose.yml na raiz do projeto com o Fakecloud configurado. Assim qualquer desenvolvedor do time sobe o ambiente com um único Docker compose up.

💡
Dica

Use fixtures de setup/teardown para criar e destruir os recursos (buckets, filas) antes e depois de cada teste. Isso garante isolamento entre os testes e evita estado compartilhado que causa falhas intermitentes.

🔴
Cuidado

Nunca commite credenciais reais da AWS no código pensando que é seguro porque o teste usa o Fakecloud. O SDK pode acabar se conectando na AWS real se as variáveis de ambiente não estiverem configuradas corretamente no ambiente de CI.

🚀
Pro tip

Combine o Fakecloud com o testcontainers (disponível em Java, Python, Go e Node.js) para subir e derrubar o container automaticamente durante a suite de testes, sem precisar de Docker Compose separado.

Vale a pena?

Se o seu projeto usa AWS - mesmo que só S3 para armazenar arquivos - o Fakecloud vale a pena ser avaliado. A proposta e simples e o ganho e imediato: testes de integração mais rápidos, sem custo de infraestrutura para o ambiente de desenvolvimento e CI/CD.

Para times pequenos e projetos open source, e especialmente vantajoso porque remove a dependência de contas AWS compartilhadas ou segredos de CI expostos. O setup inicial e questão de minutos com Docker.

O próximo passo e acessar o repositório oficial do projeto em fakecloud.dev, verificar quais serviços AWS que você usa estão cobertos e tentar integrar em um teste de integração já existente. A curva de aprendizado e mínima se você já usa o AWS SDK.