AWS SDK를 호출하는 코드의 통합 테스트는 어디에서 실행하고 계신가요? 개발 계정에서 실행하면 리소스를 만들고 지우는 시간과 비용이 들고 CI 작업에 자격 증명도 넘겨야 합니다. SDK를 모의 객체(mock)로 바꾸면 빠르지만 조건부 쓰기 실패나 없는 객체 조회처럼 실제 서비스가 돌려주는 오류를 재현하기 어렵습니다.
2026년 11월 11일 공개된 AWS Emulator는 AWS API를 로컬 프로세스 하나로 흉내 내는 테스트 도구입니다. 이 글은 AWS Emulator의 동작 방식을 소개하고 설치와 연결 방법, 개발과 CI에서 활용하는 방법을 예제로 설명합니다.
1. AWS Emulator 소개
1.1 동작 방식
AWS Emulator는 aws-emulator 명령 하나로 실행하는 프로그램입니다. 시작하면 127.0.0.1:9297에서 HTTPS로 모든 서비스의 API를 한 개의 엔드포인트(Endpoint)로 받습니다. 개발자는 환경 변수로 AWS CLI와 SDK의 엔드포인트만 에뮬레이터로 바꾸고 코드는 그대로 실행합니다. 에뮬레이터는 요청을 메모리 안의 리소스로 처리합니다. User Guide에 따르면 요청과 응답, 리소스 데이터를 AWS로 보내지 않습니다
그림 1. AWS Emulator의 동작 구조(Linux 패키지, 기본 포트 9297). 서비스는 일부만 표시했습니다.
동작을 이해하는 데 필요한 특징은 네 가지입니다.
실행마다 새 키와 인증서: 시작할 때 이번 실행 전용 액세스 키, 설정 파일, 인증서를 ~/.aws/emulator/<포트>/ 폴더에 만듭니다. 기본 설정에서는 이 키로 SigV4 서명을 한 요청만 처리합니다.
메모리 상태: 모든 리소스는 메모리에 있어서 에뮬레이터를 멈추면 리소스와 키 파일이 함께 사라집니다. 다시 시작하면 깨끗한 상태입니다.
실행마다 독립된 계정: 에뮬레이터 하나는 AWS 계정 000000000000 하나처럼 동작합니다. 포트를 달리해 여러 개를 띄우면 서로의 리소스를 볼 수 없습니다.
명확한 미지원 응답: 아직 구현하지 않은 작업은 HTTP 501 NotImplemented를 돌려주므로 해당 테스트가 바로 실패합니다.
What’s New 발표문에 따르면 서비스는 AWS가 공개한 API 모델에서 생성하고 추가 서비스 요금은 없습니다. 소스 코드는 GitHub 저장소에 공개되어 있습니다. What is AWS Emulator? 문서는 빌드와 테스트 전용이므로 운영 워크로드에는 사용하지 말라고 밝힙니다.
1.2 시작 경로
Getting started 문서는 작업 방식과 실행 환경에 따라 네 가지 시작 경로를 안내합니다. 에뮬레이터는 Linux에서만 직접 실행되므로 macOS와 Windows는 컨테이너를 사용합니다.
그림 2. 작업 방식과 실행 환경에 따른 시작 경로
이 글은 Linux 패키지를 기준으로 설명합니다. 다른 경로도 에뮬레이터가 실행되는 위치만 다르고 연결 방법과 활용 방식은 같습니다. 임베디드 모드만 예외로 엔드포인트와 인증서를 설정하지 않고 테스트 코드가 에뮬레이터를 직접 호출합니다.
1.3 지원 범위와 충실도 점수
User Guide는 에뮬레이터가 AWS와 얼마나 같게 동작하는지를 충실도(fidelity)라고 부릅니다. AWS는 서비스별 충실도 테스트를 만들어 릴리스마다 통과 결과를 GitHub 릴리스 페이지에 scores.json.gz 파일로 공개합니다. v1.0.322에서는 서비스 355개의 테스트 중 56.5%를 통과했습니다.
그림 3. 이 글에서 사용한 서비스의 충실도 테스트 통과율(v1.0.322 scores.json.gz)
점수는 기능의 몇 퍼센트가 동작하는지를 뜻하지 않습니다. 충실도 테스트에는 오류 경로와 경계 조건이 많아서 일반적인 호출은 점수보다 잘 동작했습니다. 점수가