<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Testing · 인재덕</title>
    <link>https://jared.lynskey.co.nz/ko/tags/testing/</link>
    <description>소프트웨어 엔지니어링과 개발 조직 리더십에 대한 이야기. 성과 리뷰, 채용과 팀 확장, CI/CD, 데브옵스 모니터링, 에이전틱 AI. 서울에서 씁니다.</description>
    <generator>Hugo</generator>
    <language>ko</language>
    <copyright>© 2026 인재덕</copyright>
    <lastBuildDate>Fri, 13 Nov 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/ko/tags/testing/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>AWS Emulator 사용법: 무료 LocalStack 대체 설정하기</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/aws-emulator-setup/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/aws-emulator-setup/</guid>
      <pubDate>Fri, 13 Nov 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>AWS Emulator</category>
      <category>LocalStack</category>
      <category>Moto</category>
      <category>Floci</category>
      <category>S3</category>
      <category>Testing</category>
      <category>Docker</category>
      <category>GitHub Actions</category>
      <category>Python</category>
      <category>Presigned URLs</category>
      <category>OTA Updates</category>
      <description>AWS의 무료 에뮬레이터를 Docker, Linux, GitHub Actions에 설정하고 boto3를 연결하는 법. 제 S3 로컬 테스트에서 LocalStack 4.12가 놓친 것을 이 에뮬레이터가 잡아낸 이야기도 담았습니다.</description>
      <content:encoded><![CDATA[<p>AWS가 2026년 11월 11일 <a href="https://github.com/aws/aws-emulator"  target="_blank" rel="noreferrer">AWS Emulator</a>를 공개했습니다. 내 컴퓨터에서 직접 돌리는 AWS API의 로컬 사본입니다. 무료이고, AWS 계정이 필요 없고, 코드는 퍼블릭 도메인(CC0)이며, 지원하는 서비스가 200개가 넘습니다. LocalStack이 최신 이미지에 계정과 인증 토큰을 요구하기 시작한 지 7개월 만에 나온 터라, 많은 사람이 오래 기다려 온 무료 LocalStack 대체 도구로 이걸 눈여겨보고 있습니다.</p>
<p>이 글은 대부분 설정 이야기입니다. Mac이나 Windows에서는 Docker, Linux에서는 패키지, AWS CLI와 boto3가 에뮬레이터를 바라보게 하는 환경 변수, 그리고 Docker Compose, pytest, GitHub Actions까지요. 여기 나오는 명령은 전부 버전 1.0.342에서 제가 직접 돌려 봤습니다. 설정 다음에는 제 프로젝트 두 개의 S3 테스트를 여기에 돌렸을 때 무엇을 맞히고 무엇을 틀렸는지를 LocalStack 4.12, Moto, Floci와 나란히 놓고 봅니다. 두 프로젝트는 제 마켓플레이스 앱의 업로드 흐름, 그리고 직접 호스팅하는 Codemagic Patch 서버가 OTA 번들을 보관하는 버킷입니다.</p>

<h2 class="relative group">1분 만에 보는 AWS Emulator
    <div id="1분-만에-보는-aws-emulator" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#1%eb%b6%84-%eb%a7%8c%ec%97%90-%eb%b3%b4%eb%8a%94-aws-emulator" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>AWS는 컨테이너 이미지를 배포하지 않습니다. AWS의 Linux 패키지를 설치하는 아홉 줄짜리 Dockerfile로 이미지를 직접 만들고, 9297 포트로 띄운 다음, 환경 변수 몇 개를 설정하면 됩니다. 그때부터 SDK는 AWS 대신 에뮬레이터와 이야기하고, 코드는 하나도 바뀌지 않습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker build -t aws-emulator .           <span class="c1"># the Dockerfile is below</span>
</span></span><span class="line"><span class="cl">mkdir -p ~/.aws/emulator
</span></span><span class="line"><span class="cl">docker run --rm -d --name aws-emulator -p 127.0.0.1:9297:9297 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">HOME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">&#34;</span> -v <span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator:</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  aws-emulator -p <span class="m">9297</span> --telemetry off
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ENDPOINT_URL</span><span class="o">=</span>https://127.0.0.1:9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SHARED_CREDENTIALS_FILE</span><span class="o">=</span>~/.aws/emulator/9297/emulator_credentials
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CONFIG_FILE</span><span class="o">=</span>~/.aws/emulator/9297/config
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CA_BUNDLE</span><span class="o">=</span>~/.aws/emulator/9297/ca.pem
</span></span><span class="line"><span class="cl">aws sts get-caller-identity              <span class="c1"># &#34;Account&#34;: &#34;000000000000&#34;</span></span></span></code></pre></div></div>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-setup.jpg" style="background:url('data:image/webp;base64,UklGRloAAABXRUJQVlA4IE4AAACQBACdASogABIAPw1yskwmIyIhKAqoxiGJ6QDG9BPdK4I2hDwC1QaVpF521UAA/ui2Gzha/NBVWRJqzq2oTgehY/P2cqAeQAizoM8AAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: Dockerfile, AWS Emulator 컨테이너 시작, ok로 답하는 헬스 체크, 계정 000000000000을 돌려주는 aws sts get-caller-identity, S3 업로드, 그리고 HTTP 501로 답하는 CORS preflight">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-setup.mp4" type="video/mp4">
  </video><figcaption>제 Mac에서 녹화한 설정 전 과정입니다. 시작, 헬스 체크, 에뮬레이터의 계정, S3 업로드, 그리고 아직 못 하는 한 가지(CORS preflight가 501로 답합니다. 아래에서 자세히 다룹니다).</figcaption>
</figure>

<p>준비되기까지 0.5초 정도 걸리고, 가만히 있을 때 메모리를 175 MiB쯤 씁니다. 모든 게 메모리에 있어서 컨테이너를 멈추면 싹 지워집니다.</p>

<h2 class="relative group">계정이 필요할까? (LocalStack 무료 플랜 vs AWS Emulator)
    <div id="계정이-필요할까-localstack-무료-플랜-vs-aws-emulator" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ea%b3%84%ec%a0%95%ec%9d%b4-%ed%95%84%ec%9a%94%ed%95%a0%ea%b9%8c-localstack-%eb%ac%b4%eb%a3%8c-%ed%94%8c%eb%9e%9c-vs-aws-emulator" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>아니요. AWS Emulator, Moto, Floci는 모두 아무 데도 가입하지 않고 돌아갑니다. AWS Emulator는 AWS 자격 증명조차 원하지 않습니다. 시작할 때마다 자기 액세스 키를 새로 만들고, 그 키로 서명한 요청만 받습니다.</p>
<p>달라진 건 LocalStack입니다. 2026년 3월부터 최신 이미지는 <code>LOCALSTACK_AUTH_TOKEN</code>이 있어야 하는데, 이 토큰은 무료 계정(무료 플랜은 취미와 비상업적 용도를 겨냥합니다)이나 유료 계정에서 받습니다. 토큰이 없으면 컨테이너가 시작 단계에서 멈춥니다. 둘 다 시험해 봤습니다. <code>latest</code> 태그 이미지(2026.10.7, 11월 11일 빌드)는 종료 코드 55로 끝나고, 마지막 커뮤니티 릴리스이자 LocalStack이 직접 고정해 쓰라고 권하는 버전인 4.12는 토큰 없이도 아직 시작됩니다.</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/localstack-needs-account.jpg" style="background:url('data:image/webp;base64,UklGRlYAAABXRUJQVlA4IEoAAABQBACdASogABIAPw10pUymIyGhKA1QxiGJ6QDJTPgAtfKr5WoM7/AUVx4AAP7ozNYDExNyKOZLAQjfzKlQvzdAcPxaBgAGLrjAAA==') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: localstack/localstack:latest가 &#39;License activation failed&#39;와 종료 코드 55로 끝나고, 이어서 localstack/localstack:4.12가 시작돼 헬스 체크에서 버전 4.12.0과 사용 가능한 S3를 보고함">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/localstack-needs-account.mp4" type="video/mp4">
  </video><figcaption>토큰 없이 띄운 LocalStack 최신 이미지, 그다음 버전을 고정한 4.12. 지금은 고정으로 버틸 수 있지만, 4.12에는 앞으로 수정이 나오지 않습니다.</figcaption>
</figure>

<p>AWS Emulator가 원하는 게 하나 있긴 합니다. 기본으로 켜져 있는 텔레메트리입니다. AWS는 요청, 코드, 자격 증명은 절대 포함되지 않는다고 하지만, 아무것도 보내지 않게 하고 싶다면 스위치가 세 가지 있습니다. 명령줄의 <code>--telemetry off</code>, 환경 변수 <code>EMULATOR_TELEMETRY=off</code>, 아니면 <code>~/.aws/emulator/config.toml</code>에 이렇게 적는 겁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-toml" data-lang="toml"><span class="line"><span class="cl"><span class="p">[</span><span class="nx">telemetry</span><span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="nx">enabled</span> <span class="p">=</span> <span class="kc">false</span></span></span></code></pre></div></div>

<h2 class="relative group">macOS·Windows에서 Docker로 AWS Emulator 설정하기
    <div id="macoswindows에서-docker로-aws-emulator-설정하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#macoswindows%ec%97%90%ec%84%9c-docker%eb%a1%9c-aws-emulator-%ec%84%a4%ec%a0%95%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Mac이나 Windows에서는 Docker로 갑니다. 빈 폴더에 아래 내용을 <code>Dockerfile</code>로 저장하세요. AWS가 직접 만든 것으로, <a href="https://docs.aws.amazon.com/emulator/latest/userguide/getting-started-docker.html"  target="_blank" rel="noreferrer">AWS의 Docker 가이드</a>에 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-dockerfile" data-lang="dockerfile"><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="s">public.ecr.aws/amazonlinux/amazonlinux:2023-minimal</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ADD</span> https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">RUN</span> rpm -i /tmp/aws-emulator.rpm <span class="o">&amp;&amp;</span> rm /tmp/aws-emulator.rpm <span class="se">\
</span></span></span><span class="line"><span class="cl">    <span class="o">&amp;&amp;</span> mkdir -p /home/emulator <span class="o">&amp;&amp;</span> chown <span class="m">1000</span> /home/emulator<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">USER</span><span class="w"> </span><span class="s">1000</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ENV</span> <span class="nv">HOME</span><span class="o">=</span>/home/emulator<span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">EXPOSE</span><span class="w"> </span><span class="s">9297</span><span class="err">
</span></span></span><span class="line"><span class="cl"><span class="k">ENTRYPOINT</span> <span class="p">[</span><span class="s2">&#34;aws-emulator&#34;</span><span class="p">,</span> <span class="s2">&#34;-b&#34;</span><span class="p">,</span> <span class="s2">&#34;0.0.0.0&#34;</span><span class="p">]</span></span></span></code></pre></div></div>
<p>Apple silicon이나 다른 ARM 머신에서는 <code>x86_64.rpm</code>을 <code>aarch64.rpm</code>으로 바꾸세요. 그다음 빌드하고 띄웁니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">docker build -t aws-emulator .
</span></span><span class="line"><span class="cl">mkdir -p ~/.aws/emulator
</span></span><span class="line"><span class="cl">docker run --rm -d --name aws-emulator --memory<span class="o">=</span>2g --memory-swap<span class="o">=</span>2g <span class="se">\
</span></span></span><span class="line"><span class="cl">  -p 127.0.0.1:9297:9297 <span class="se">\
</span></span></span><span class="line"><span class="cl">  -e <span class="nv">HOME</span><span class="o">=</span><span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">&#34;</span> -v <span class="s2">&#34;</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator:</span><span class="nv">$HOME</span><span class="s2">/.aws/emulator&#34;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">  aws-emulator -p <span class="m">9297</span> --telemetry off</span></span></code></pre></div></div>
<p>제 Mac에서 빌드는 88초 걸렸고 이미지는 1.67 GB입니다. 이 <code>docker run</code> 줄에서 보기보다 중요한 부분이 세 군데 있습니다.</p>
<ul>
<li><strong><code>-p 9297:9297</code>이 아니라 <code>-p 127.0.0.1:9297:9297</code>.</strong> 짧게 쓰면 에뮬레이터가 네트워크 전체에 열립니다.</li>
<li><strong>볼륨과 <code>-e HOME</code>.</strong> 에뮬레이터는 시작할 때 <code>~/.aws/emulator/9297/</code>에 파일 네 개를 씁니다. 자격 증명, AWS <code>config</code> 파일, 인증서(<code>ca.pem</code>), 그리고 Java 트러스트 스토어입니다. 이 폴더를 컨테이너 안의 같은 경로에 마운트해야 호스트의 SDK가 그 파일들을 읽을 수 있습니다.</li>
<li><strong>포트가 세 번 나옵니다.</strong> 바꾼다면 전부 바꾸세요. 에뮬레이터는 그 파일들에 자기 포트를 적어 넣기 때문에, 폴더를 공유하는 컨테이너 두 개는 서로의 파일을 덮어씁니다.</li>
</ul>

<h2 class="relative group">Linux에 AWS Emulator 설치하기
    <div id="linux에-aws-emulator-설치하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#linux%ec%97%90-aws-emulator-%ec%84%a4%ec%b9%98%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>Linux에서는 Docker가 필요 없습니다. Debian 패키지와 RPM이 있습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="c1"># Debian / Ubuntu (use aws-emulator_arm64.deb on ARM)</span>
</span></span><span class="line"><span class="cl">curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
</span></span><span class="line"><span class="cl">sudo apt-get install -y ./aws-emulator.deb
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Amazon Linux, Fedora, RHEL (aarch64.rpm on ARM)</span>
</span></span><span class="line"><span class="cl">sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">aws-emulator --telemetry off</span></span></code></pre></div></div>
<p>패키지는 150 MB입니다. <code>127.0.0.1:9297</code>에서 포그라운드로 돌고, 같은 파일 네 개를 <code>~/.aws/emulator/9297/</code>에 씁니다. Ctrl+C를 누르면 깔끔하게 멈추면서 그 파일들도 지웁니다. 테스트용으로 돌릴 때는 <code>--idle-timeout 900</code>을 붙이세요. 요청 없이 15분이 지나면 알아서 꺼지니까, 깜빡 잊은 에뮬레이터가 일주일 내내 떠 있을 일이 없습니다.</p>

<h2 class="relative group">AWS CLI와 boto3를 에뮬레이터에 연결하기
    <div id="aws-cli와-boto3를-에뮬레이터에-연결하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#aws-cli%ec%99%80-boto3%eb%a5%bc-%ec%97%90%eb%ae%ac%eb%a0%88%ec%9d%b4%ed%84%b0%ec%97%90-%ec%97%b0%ea%b2%b0%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>변수는 이렇습니다. 표준 AWS 환경 변수를 읽는 SDK라면 무엇이든 이걸 가져가니까, 테스트 대상 코드에는 엔드포인트도 키도 필요 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nv">E</span><span class="o">=</span>~/.aws/emulator/9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_ENDPOINT_URL</span><span class="o">=</span>https://127.0.0.1:9297
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_SHARED_CREDENTIALS_FILE</span><span class="o">=</span><span class="nv">$E</span>/emulator_credentials
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CONFIG_FILE</span><span class="o">=</span><span class="nv">$E</span>/config
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_CA_BUNDLE</span><span class="o">=</span><span class="nv">$E</span>/ca.pem
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_REGION</span><span class="o">=</span>us-east-1
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_EC2_METADATA_DISABLED</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">AWS_DISABLE_HOST_PREFIX_INJECTION</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nb">unset</span> AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">curl -s --cacert <span class="nv">$AWS_CA_BUNDLE</span> <span class="nv">$AWS_ENDPOINT_URL</span>/__admin/health   <span class="c1"># ok</span>
</span></span><span class="line"><span class="cl">aws sts get-caller-identity                                          <span class="c1"># 000000000000</span></span></span></code></pre></div></div>
<p>그러면 평범한 boto3가 그냥 동작합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="n">s3</span> <span class="o">=</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span><span class="s2">&#34;s3&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="n">s3</span><span class="o">.</span><span class="n">create_bucket</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="s2">&#34;uploads&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="nb">print</span><span class="p">(</span><span class="n">s3</span><span class="o">.</span><span class="n">list_buckets</span><span class="p">()[</span><span class="s2">&#34;Buckets&#34;</span><span class="p">])</span></span></span></code></pre></div></div>
<p>꼭 남겨 둘 줄은 <code>unset</code>입니다. 환경 변수가 자격 증명 파일보다 우선하기 때문에, 진짜 AWS 키가 아직 export돼 있으면 SDK는 그 키로 서명하고, 에뮬레이터는 요청을 거부하고, 여러분은 이유를 찾느라 10분을 날립니다. <code>aws sts get-caller-identity</code>는 빠르게 확인하기 좋습니다. 에뮬레이터는 항상 계정 <code>000000000000</code>이거든요. 자기 계정 번호가 보인다면 AWS와 이야기하고 있는 겁니다.</p>
<p>그 밖에 제가 부딪혔거나 부딪힐 뻔한 것들입니다.</p>
<ul>
<li><strong>엔드포인트에는 <code>localhost</code>가 아니라 <code>127.0.0.1</code>을 쓰세요.</strong> IP 주소면 SDK가 버킷 이름을 경로에 넣습니다. <code>localhost</code>면 JavaScript, Java, Go SDK가 버킷 이름을 호스트 이름으로 옮기는데(<code>uploads.localhost</code>), 에뮬레이터는 이걸 받지 않습니다.</li>
<li><strong>HTTPS 전용이고, 시작할 때마다 인증서가 새로 만들어집니다.</strong> boto3, AWS CLI, Go는 <code>AWS_CA_BUNDLE</code>을 읽습니다. Node는 같은 <code>ca.pem</code>을 가리키는 <code>NODE_EXTRA_CA_CERTS</code>가 필요하고, Java는 <code>JAVA_TOOL_OPTIONS</code>로 <code>truststore.p12</code>를 씁니다. <code>AWS_CA_BUNDLE</code>은 그 프로세스가 신뢰하는 인증서를 통째로 바꿔 버리기 때문에, 실제 HTTPS API도 호출하는 테스트라면 둘을 합친 번들이 필요합니다.</li>
<li><strong>리셋이 없습니다.</strong> 내용을 비워 주는 관리용 경로가 없으니, 테스트마다 버킷 이름을 따로 주거나 테스트 묶음 사이에 에뮬레이터를 재시작하세요.</li>
<li><strong>키는 시작할 때마다 바뀝니다.</strong> <code>.env</code> 파일에 복사해 두지 말고 자격 증명 파일을 가리키게 하세요.</li>
<li><strong>앱이 엔드포인트를 명시해서 자기 클라이언트를 따로 만든다면</strong>(예를 들어 django-storages의 <code>AWS_S3_ENDPOINT_URL</code>), 그 값도 <code>AWS_ENDPOINT_URL</code>에서 가져오게 하세요. 안 그러면 그 클라이언트 하나만 계속 실제 서비스와 이야기합니다.</li>
</ul>

<h2 class="relative group">Docker Compose로 AWS Emulator 실행하기
    <div id="docker-compose로-aws-emulator-실행하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#docker-compose%eb%a1%9c-aws-emulator-%ec%8b%a4%ed%96%89%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이미 <code>compose.yaml</code>이 있는 프로젝트라면 아래 서비스를 쓰면 됩니다. 위의 Dockerfile로 이미지를 빌드하고, 에뮬레이터 파일을 홈 디렉터리 대신 프로젝트 폴더에 두고, 헬스 체크도 있어서 <code>docker compose up --wait</code>가 준비가 끝난 뒤에 돌아옵니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">services</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">aws</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">build</span><span class="p">:</span><span class="w"> </span><span class="l">./aws-emulator           </span><span class="w"> </span><span class="c"># the folder with the Dockerfile</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">command</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;-p&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;9297&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;--telemetry&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;off&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">ports</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;127.0.0.1:9297:9297&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">environment</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">HOME</span><span class="p">:</span><span class="w"> </span><span class="l">${PWD}/.aws-emulator-home</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">volumes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="l">./.aws-emulator-home/.aws/emulator:${PWD}/.aws-emulator-home/.aws/emulator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">mem_limit</span><span class="p">:</span><span class="w"> </span><span class="l">2g</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">healthcheck</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">test</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&#34;CMD&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;curl&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;-sf&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;--cacert&#34;</span><span class="p">,</span><span class="w"> </span><span class="s2">&#34;${PWD}/.aws-emulator-home/.aws/emulator/9297/ca.pem&#34;</span><span class="p">,</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">             </span><span class="s2">&#34;https://127.0.0.1:9297/__admin/health&#34;</span><span class="p">]</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">interval</span><span class="p">:</span><span class="w"> </span><span class="l">1s</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">retries</span><span class="p">:</span><span class="w"> </span><span class="m">30</span></span></span></code></pre></div></div>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p .aws-emulator-home/.aws/emulator
</span></span><span class="line"><span class="cl">docker compose up -d --wait aws       <span class="c1"># healthy in about 5 s with the image already built</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">E</span><span class="o">=</span><span class="nv">$PWD</span>/.aws-emulator-home/.aws/emulator/9297   <span class="c1"># then the variables from above</span></span></span></code></pre></div></div>
<p><code>.aws-emulator-home/</code>은 <code>.gitignore</code>에 넣으세요. 그 실행의 키가 들어 있습니다.</p>

<h2 class="relative group">pytest에서 AWS Emulator 쓰기
    <div id="pytest에서-aws-emulator-쓰기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#pytest%ec%97%90%ec%84%9c-aws-emulator-%ec%93%b0%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>테스트 자체에는 에뮬레이터 전용 코드가 없습니다. 제가 더하는 건 안전장치 하나입니다. 제가 걱정하는 실패는 빨간 테스트가 아니라, 진짜 버킷을 상대로 돌고 초록색으로 끝난 테스트이기 때문입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># conftest.py</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">uuid</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">boto3</span>
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">pytest</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span><span class="p">(</span><span class="n">scope</span><span class="o">=</span><span class="s2">&#34;session&#34;</span><span class="p">,</span> <span class="n">autouse</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">only_against_the_emulator</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">    <span class="n">url</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&#34;AWS_ENDPOINT_URL&#34;</span><span class="p">,</span> <span class="s2">&#34;&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="ow">not</span> <span class="n">url</span><span class="o">.</span><span class="n">startswith</span><span class="p">((</span><span class="s2">&#34;https://127.0.0.1&#34;</span><span class="p">,</span> <span class="s2">&#34;http://127.0.0.1&#34;</span><span class="p">)):</span>
</span></span><span class="line"><span class="cl">        <span class="n">pytest</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="sa">f</span><span class="s2">&#34;AWS_ENDPOINT_URL is </span><span class="si">{</span><span class="n">url</span><span class="si">!r}</span><span class="s2">; refusing to run against real AWS&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">s3</span><span class="p">():</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">boto3</span><span class="o">.</span><span class="n">client</span><span class="p">(</span><span class="s2">&#34;s3&#34;</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nd"><span>@</span>pytest.fixture</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">bucket</span><span class="p">(</span><span class="n">s3</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">name</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&#34;test-</span><span class="si">{</span><span class="n">uuid</span><span class="o">.</span><span class="n">uuid4</span><span class="p">()</span><span class="o">.</span><span class="n">hex</span><span class="p">[:</span><span class="mi">12</span><span class="p">]</span><span class="si">}</span><span class="s2">&#34;</span>   <span class="c1"># no reset route, so never reuse a name</span>
</span></span><span class="line"><span class="cl">    <span class="n">s3</span><span class="o">.</span><span class="n">create_bucket</span><span class="p">(</span><span class="n">Bucket</span><span class="o">=</span><span class="n">name</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">name</span></span></span></code></pre></div></div>
<p>그러면 테스트는 여느 테스트와 다를 게 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">os</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kn">import</span> <span class="nn">requests</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">test_presigned_upload_rejects_the_wrong_content_type</span><span class="p">(</span><span class="n">s3</span><span class="p">,</span> <span class="n">bucket</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="n">url</span> <span class="o">=</span> <span class="n">s3</span><span class="o">.</span><span class="n">generate_presigned_url</span><span class="p">(</span>
</span></span><span class="line"><span class="cl">        <span class="s2">&#34;put_object&#34;</span><span class="p">,</span> <span class="n">ExpiresIn</span><span class="o">=</span><span class="mi">300</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">        <span class="n">Params</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Bucket&#34;</span><span class="p">:</span> <span class="n">bucket</span><span class="p">,</span> <span class="s2">&#34;Key&#34;</span><span class="p">:</span> <span class="s2">&#34;media/a.jpg&#34;</span><span class="p">,</span> <span class="s2">&#34;ContentType&#34;</span><span class="p">:</span> <span class="s2">&#34;image/jpeg&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">)</span>
</span></span><span class="line"><span class="cl">    <span class="n">r</span> <span class="o">=</span> <span class="n">requests</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">data</span><span class="o">=</span><span class="sa">b</span><span class="s2">&#34;&lt;html&gt;&#34;</span><span class="p">,</span> <span class="n">headers</span><span class="o">=</span><span class="p">{</span><span class="s2">&#34;Content-Type&#34;</span><span class="p">:</span> <span class="s2">&#34;text/html&#34;</span><span class="p">},</span>
</span></span><span class="line"><span class="cl">                     <span class="n">verify</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s2">&#34;AWS_CA_BUNDLE&#34;</span><span class="p">])</span>
</span></span><span class="line"><span class="cl">    <span class="k">assert</span> <span class="n">r</span><span class="o">.</span><span class="n">status_code</span> <span class="o">==</span> <span class="mi">403</span></span></span></code></pre></div></div>
<p>이건 제 마켓플레이스 앱의 업로드 흐름에서 가져온 테스트인데, 어떤 에뮬레이터를 고르느냐가 왜 중요한지 잘 보여 줍니다. 제가 시험한 다섯 개 중 세 개가 여기에 200을 돌려주거든요. 자세한 건 아래에서 다룹니다. 변경할 때마다 영향받는 테스트만 돌린다면 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-10-26-pytest-testmon/" >pytest-testmon</a>도 손대지 않고 그대로 함께 쓸 수 있습니다.</p>

<h2 class="relative group">GitHub Actions에서 AWS Emulator 실행하기
    <div id="github-actions에서-aws-emulator-실행하기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#github-actions%ec%97%90%ec%84%9c-aws-emulator-%ec%8b%a4%ed%96%89%ed%95%98%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>GitHub 러너에서는 Docker를 건너뛰고 Debian 패키지를 설치하세요. 한 스텝에서 띄운 백그라운드 프로세스는 잡이 끝날 때까지 계속 돕니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">test</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">astral-sh/setup-uv@v10</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Start AWS Emulator</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
</span></span></span><span class="line"><span class="cl"><span class="sd">          sudo apt-get install -y ./aws-emulator.deb
</span></span></span><span class="line"><span class="cl"><span class="sd">          aws-emulator --telemetry off --idle-timeout 900 &gt; emulator.log 2&gt;&amp;1 &amp;
</span></span></span><span class="line"><span class="cl"><span class="sd">          E=$HOME/.aws/emulator/9297
</span></span></span><span class="line"><span class="cl"><span class="sd">          for i in $(seq 30); do
</span></span></span><span class="line"><span class="cl"><span class="sd">            curl -sf --cacert $E/ca.pem https://127.0.0.1:9297/__admin/health &amp;&amp; break
</span></span></span><span class="line"><span class="cl"><span class="sd">            sleep 1
</span></span></span><span class="line"><span class="cl"><span class="sd">          done
</span></span></span><span class="line"><span class="cl"><span class="sd">          {
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_ENDPOINT_URL=https://127.0.0.1:9297&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_SHARED_CREDENTIALS_FILE=$E/emulator_credentials&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_CONFIG_FILE=$E/config&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_CA_BUNDLE=$E/ca.pem&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_REGION=us-east-1&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_EC2_METADATA_DISABLED=true&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;AWS_DISABLE_HOST_PREFIX_INJECTION=true&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          } &gt;&gt; &#34;$GITHUB_ENV&#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run pytest</span></span></span></code></pre></div></div>
<p>같은 스텝을 새 <code>ubuntu:24.04</code> 컨테이너에서도 돌려 봤습니다(제 Mac이 ARM이라 arm64 패키지로요). 설치는 29초 걸렸는데 거의 전부가 150 MB 다운로드였고, 헬스 체크는 4초 안에 응답했습니다. 이 잡에는 실제 AWS 자격 증명을 아예 넣지 마세요. 잡 안의 무엇도 AWS에 닿지 않는다고 확신할 수 있는 가장 싼 방법입니다.</p>
<p><code>LTS/latest</code>는 마지막으로 릴리스된 버전을 가리키는데, 아래에서 보겠지만 이게 하루에도 몇 번씩 바뀝니다. CI를 재현 가능하게 하고 싶다면 AWS 문서에 <a href="https://docs.aws.amazon.com/emulator/latest/userguide/versioning.html"  target="_blank" rel="noreferrer">특정 버전을 설치하는 방법</a>이 나와 있습니다. 파이프라인의 나머지를 제가 어떻게 짜는지는 <a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-10-22-docker-compose-ci-github-actions/" >요즘 제가 돌리는 GitHub Actions 파이프라인</a>을 참고하세요.</p>

<h2 class="relative group">LocalStack에서 옮겨 오기
    <div id="localstack에서-옮겨-오기" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#localstack%ec%97%90%ec%84%9c-%ec%98%ae%ea%b2%a8-%ec%98%a4%ea%b8%b0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이미 LocalStack으로 테스트를 돌리고 있다면, 옮기는 일은 대부분 설정입니다.</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>LocalStack</th>
					<th>AWS Emulator</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>엔드포인트</td>
					<td><code>http://localhost:4566</code></td>
					<td><code>https://127.0.0.1:9297</code>과 <code>AWS_CA_BUNDLE</code></td>
			</tr>
			<tr>
					<td>자격 증명</td>
					<td>아무거나 (<code>test</code> / <code>test</code>)</td>
					<td>실행할 때마다 쓰는 파일, 또는 <code>--auth off</code></td>
			</tr>
			<tr>
					<td>계정 ID</td>
					<td><code>000000000000</code></td>
					<td><code>000000000000</code></td>
			</tr>
			<tr>
					<td>설정 스크립트</td>
					<td><code>/etc/localstack/init/ready.d</code>의 init hook</td>
					<td>없음: 헬스 체크 뒤에 fixture에서 리소스 생성</td>
			</tr>
			<tr>
					<td>이미지</td>
					<td><code>localstack/localstack</code> (4.12 이후는 토큰 필요)</td>
					<td>AWS 패키지로 직접 빌드</td>
			</tr>
	</tbody>
</table>
<p>init hook을 많이 쓴다면 그 부분이 진짜로 손이 가는 곳입니다. 저는 테스트마다 버킷을 따로 만들어서 쓸 일이 없었습니다. 그리고 재시작하면 아무것도 남지 않습니다. 에뮬레이터는 전부 메모리에 들고 있으니까요.</p>

<h2 class="relative group">S3 로컬 테스트에서 AWS Emulator가 잡아낸 것과 놓친 것
    <div id="s3-로컬-테스트에서-aws-emulator가-잡아낸-것과-놓친-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#s3-%eb%a1%9c%ec%bb%ac-%ed%85%8c%ec%8a%a4%ed%8a%b8%ec%97%90%ec%84%9c-aws-emulator%ea%b0%80-%ec%9e%a1%ec%95%84%eb%82%b8-%ea%b2%83%ea%b3%bc-%eb%86%93%ec%b9%9c-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>설정은 쉬운 부분입니다. 제가 알고 싶었던 건, 제 코드가 S3의 동작에 기대는 지점에서 이 에뮬레이터도 S3처럼 동작하느냐였습니다. 검사를 12개 썼고, 각각 AWS 문서에 적힌 실제 S3의 동작을 확인합니다.</p>
<ul>
<li><strong>마켓플레이스 앱의 업로드 흐름에서 6개.</strong> 앱이 브라우저에 presigned URL을 건네면, 브라우저가 사진을 버킷에 바로 PUT하고(그래서 버킷에 CORS가 필요합니다), <code>ObjectCreated</code> 이벤트가 파일이 도착했다고 백엔드에 알립니다. <a href="https://jared.lynskey.co.nz/ko/posts/2026/tigris-object-notifications/" >객체 알림에 관한 글</a>에서 다룬 흐름인데, 웹훅 자리에 SQS를 넣었습니다.</li>
<li><strong>Codemagic Patch 버킷에서 6개.</strong> Patch는 React Native 앱용 OTA 업데이트 서버입니다(<a href="https://jared.lynskey.co.nz/ko/posts/2026/2026-09-13-moving-to-codemagic-patch/" >Patch로 옮겨 간 이야기</a>). 휴대폰이 번들을 내려받을 수 있도록 버킷은 공개인데, 업로드가 게시를 기다리는 <code>_internal/</code> 프리픽스만은 예외라서 버킷 정책으로 이 프리픽스를 비공개로 묶어 둡니다.</li>
</ul>
<p>이 검사들을 AWS Emulator 1.0.342(기본 상태로 한 번, <code>--auth off</code>로 한 번), LocalStack 4.12(기본 상태로, 그리고 <code>S3_SKIP_SIGNATURE_VALIDATION=0</code>으로), 서버 모드의 Moto 5.2.6, Floci 1.5.5, 그리고 Patch의 셀프 호스팅 번들이 쓰는 MinIO 포크인 Silo에 돌렸습니다.</p>
<figure><video
    class="my-0 rounded-md"
    autoplay loop muted playsinline preload="metadata"
    poster="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/s3-emulator-test-run.jpg" style="background:url('data:image/webp;base64,UklGRk4AAABXRUJQVlA4IEIAAAAQBACdASogABIAPw10rkymIyIhKAqoxiGJ6QDM0PgAtf/5Tl8J29EIQAD+6MzcUMCFo8DULSYQXf8FTN9rmZMAAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="터미널: 스크립트가 같은 S3 검사 12개를 에뮬레이터 설정 일곱 가지에 돌리고 통과/실패 표를 출력함. 모든 설정이 12개 중 6~8개 통과로 끝남">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/s3-emulator-test-run.mp4" type="video/mp4">
  </video><figcaption>실제로 돌린 결과입니다. 12개를 전부 통과한 건 없었습니다.</figcaption>
</figure>

<p>12개를 모두 통과한 구성은 없었고, 다들 6개에서 8개 사이였습니다. 합계보다 각자 어떤 검사를 놓쳤는지가 더 중요하니, 저한테 가장 아팠을 것부터 순서대로 적어 보겠습니다.</p>
<p><strong>AWS Emulator가 권한에는 가장 엄격합니다.</strong> 제 앱이 JPEG 한 장을 위해 서명해 주는 presigned URL을 예로 들어 보죠. 기본 설정의 LocalStack 4.12, Moto, Floci에서는 같은 URL로 HTML 파일을 올릴 수 있었고, 200이 돌아왔습니다. 공개 파일을 서빙하는 버킷이라면 저장형 XSS가 터지기를 기다리는 셈입니다. AWS Emulator는 S3처럼 403으로 거부했고, 만료된 URL도 다시 거부했습니다. (LocalStack 4.12는 <code>S3_SKIP_SIGNATURE_VALIDATION=0</code>을 설정하면 둘 다 잡고, Floci는 만료는 잡지만 바꿔치기한 파일 형식은 통과시킵니다.) 새 S3 버킷은 Block Public Access가 켜진 채로 만들어져서 그걸 끄기 전까지 공개 버킷 정책이 거부된다는 걸 아는 것도 이것뿐이었고, 명시적 <code>Deny</code>를 낯선 사람뿐 아니라 서버 자신의 서명된 요청에도 적용한 것도 이것뿐이었습니다. 모든 테스트를 통과하고 나서 첫 실제 배포에서 터지는 실수가 딱 이런 것들입니다.</p>
<p><strong>브라우저가 하는 일은 아직 테스트할 수 없습니다.</strong> CORS preflight(브라우저가 교차 출처 PUT 전에 보내는 <code>OPTIONS</code> 요청)는 <code>501 Not Implemented</code>를 받습니다. 기본값대로 인증이 켜져 있으면 서명 없는 요청도 전부 거부하기 때문에, 정책이 허용하더라도 공개 버킷에서의 익명 다운로드가 403을 받습니다. 두 빈틈 모두 이미 저장소에 등록돼 있습니다. 이 프로젝트는 알려진 빈틈을 <code>issues/things-that-do-not-work/</code> 아래에 파일로 관리하는데, 11월 13일 기준으로 6,840개가 있었고 13,409개는 이미 <code>things-that-now-work/</code>로 옮겨져 있었습니다.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="GitHub의 things-that-do-not-work 폴더에 있는 AWS Emulator의 S3 이슈 파일, 제목은 &ldquo;7 net-new causes — CORS preflight answers 501…&rdquo;"
    width="1400"
    height="804"
    src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_33033b091b284c0d.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_33033b091b284c0d.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_f0294a8a0a022038.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-cors-preflight-issue_hu_925176ba1af6cb05.webp"></span><figcaption>프로젝트의 자체 이슈 탐색 에이전트가 11월 9일에 등록한 CORS 빈틈.</figcaption></figure>
</p>
<p><strong><code>--auth off</code>는 한쪽을 얻는 대신 다른 쪽을 내줍니다.</strong> 인증을 끄면 익명 읽기가 되고 버킷 정책도 제대로 평가돼서, Patch 검사 6개가 모두 통과합니다. 그걸 해낸 설정은 이것 하나뿐입니다. 하지만 presigned URL도 더는 검사하지 않아서 업로드 쪽 검사는 2개로 떨어집니다. 에뮬레이터 두 개를 다른 포트에 띄워 하나는 인증을 켜고 하나는 끄면 양쪽을 다 덮을 수 있지만, 다음에 CI 파일을 읽을 사람에게 설명할 거리가 하나 늘어나죠.</p>
<p><strong>변화가 빠릅니다.</strong> v1.0.290부터 v1.0.342까지의 릴리스가 사흘 만에 나왔고, 하나하나가 긴 수정 목록입니다(AWS 말로는 코딩 에이전트가 만들었다는데, 속도만 봐도 알 만합니다). 11월 11일 수정 가운데 하나는 S3의 &ldquo;presigned GET refused with 403&quot;이었습니다. 제 표의 어느 칸이든 다음 주면 어느 쪽으로든 달라져 있을 수 있습니다. CI에서는 버전을 고정하고, 올릴 때는 의식적으로 올리세요.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="GitHub의 aws/aws-emulator 릴리스 페이지: 3시간 전에 나온 v1.0.342에 Latest 표시가 붙어 있고, 사이드바에 릴리스 9개가 더 보임"
    width="1600"
    height="1125"
    src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_e39a0eec6b783a7a.webp"
    srcset="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_e39a0eec6b783a7a.webp 800w, https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_df197ee02b7c435c.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/aws-emulator-releases_hu_59bd3abd9b9aaf92.webp"></span><figcaption>사흘에 릴리스 10개. 하나를 골라 고정하세요.</figcaption></figure>
</p>

<h2 class="relative group">Patch 버킷: 실제 S3에서만 문제가 되는 정책 조건 하나
    <div id="patch-버킷-실제-s3에서만-문제가-되는-정책-조건-하나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#patch-%eb%b2%84%ed%82%b7-%ec%8b%a4%ec%a0%9c-s3%ec%97%90%ec%84%9c%eb%a7%8c-%eb%ac%b8%ec%a0%9c%ea%b0%80-%eb%90%98%eb%8a%94-%ec%a0%95%ec%b1%85-%ec%a1%b0%ea%b1%b4-%ed%95%98%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>예상하지 못한 건 이 부분이었습니다. Patch의 셀프 호스팅 번들은 모든 걸 버킷 하나에 두고, 번들에 포함된 스토리지에 적용하는 정책도 뻔한 것입니다. 누구나 읽을 수 있되 <code>_internal/</code> 아래만 예외죠.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;Version&#34;</span><span class="p">:</span> <span class="s2">&#34;2012-10-17&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;Statement&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="nt">&#34;Effect&#34;</span><span class="p">:</span> <span class="s2">&#34;Allow&#34;</span><span class="p">,</span> <span class="nt">&#34;Principal&#34;</span><span class="p">:</span> <span class="s2">&#34;*&#34;</span><span class="p">,</span> <span class="nt">&#34;Action&#34;</span><span class="p">:</span> <span class="s2">&#34;s3:GetObject&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;Resource&#34;</span><span class="p">:</span> <span class="s2">&#34;arn:aws:s3:::example-ota/*&#34;</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">{</span> <span class="nt">&#34;Effect&#34;</span><span class="p">:</span> <span class="s2">&#34;Deny&#34;</span><span class="p">,</span> <span class="nt">&#34;Principal&#34;</span><span class="p">:</span> <span class="s2">&#34;*&#34;</span><span class="p">,</span> <span class="nt">&#34;Action&#34;</span><span class="p">:</span> <span class="s2">&#34;s3:GetObject&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nt">&#34;Resource&#34;</span><span class="p">:</span> <span class="s2">&#34;arn:aws:s3:::example-ota/_internal/*&#34;</span> <span class="p">}</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>Silo에서 관리자 자격 증명으로 서명하면 이 정책은 적힌 그대로 동작합니다. 낯선 사람은 <code>_internal/</code>을 읽지 못하고, 서버가 직접 <code>_internal/</code>에서 공개 프리픽스로 하는 복사(&lsquo;게시&rsquo; 단계)는 통과합니다. 그런데 실제 S3에서는 <code>&quot;Principal&quot;: &quot;*&quot;</code>를 건 명시적 <code>Deny</code>가 여러분 자신의 자격 증명을 포함해 모두에게 적용되기 때문에, 같은 정책이 서버 자신의 게시 단계를 막아 버립니다. AWS Emulator는 그 복사를 403으로 거부했는데, AWS의 정책 평가 규칙에 따르면 S3가 하는 동작이 바로 그겁니다.</p>
<p>Patch 메인테이너들도 분명 이걸 알고 있습니다. <a href="https://github.com/codemagic-ci-cd/codemagic-patch/blob/main/deploy/selfhost/aws-s3-bucket-policy.example.json"  target="_blank" rel="noreferrer">AWS S3용 예시 정책</a>에서는 <code>Deny</code>에 조건을 하나 더 붙이거든요.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="s2">&#34;Condition&#34;</span><span class="err">:</span> <span class="p">{</span> <span class="nt">&#34;StringNotEquals&#34;</span><span class="p">:</span> <span class="p">{</span> <span class="nt">&#34;aws:PrincipalAccount&#34;</span><span class="p">:</span> <span class="s2">&#34;YOUR_AWS_ACCOUNT_ID&#34;</span> <span class="p">}</span> <span class="p">}</span></span></span></code></pre></div></div>
<p>이 줄이 있으면 AWS Emulator(익명 쪽도 테스트할 수 있게 <code>--auth off</code>로)와 Moto 둘 다 워커의 게시는 허용하면서 <code>_internal/</code> 익명 읽기는 여전히 거부합니다. 하지만 이 줄이 없는 버전을 잡아낸 건 AWS Emulator뿐이었습니다. Moto, LocalStack 4.12, Floci는 어느 쪽이든 복사를 통과시켰으니, 이 중 무엇을 썼어도 저는 망가진 정책을 그대로 배포했을 겁니다. 쓸 수 있는 가장 엄격한 에뮬레이터로 정책을 테스트해야 하는 이유로는 이게 제가 찾은 가장 분명한 사례입니다. MinIO 환경에서 쓰던 정책을 그 조건 없이 S3로 옮기면, 첫 실제 게시 전까지는 아무것도 문제를 알려 주지 않습니다.</p>
<p>(제 Patch 서버는 번들을 Tigris에 저장하는데, Tigris에는 버킷 정책이 아예 없어서 <code>_internal/</code>은 별도의 비공개 버킷에 둡니다. Patch 설정의 <code>S3_INTERNAL_BUCKET</code>이 그 용도입니다. 그리고 저는 Codemagic에 Patch에 관한 유료 기고 글도 씁니다. 이 글은 그런 글이 아니고, 누구에게서도 돈을 받지 않았습니다.)</p>

<h2 class="relative group">지금이라면 무엇을 쓸지
    <div id="지금이라면-무엇을-쓸지" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%a7%80%ea%b8%88%ec%9d%b4%eb%9d%bc%eb%a9%b4-%eb%ac%b4%ec%97%87%ec%9d%84-%ec%93%b8%ec%a7%80" aria-label="앵커">#</a>
    </span>
    
</h2>
<table>
	<thead>
			<tr>
					<th></th>
					<th>준비 시간</th>
					<th>유휴 메모리</th>
					<th>이미지</th>
					<th>계정</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>AWS Emulator 1.0.342</td>
					<td>0.4–0.5초</td>
					<td>176 MiB</td>
					<td>1.67 GB (직접 빌드)</td>
					<td>불필요</td>
			</tr>
			<tr>
					<td>LocalStack 4.12</td>
					<td>0.9–2.2초</td>
					<td>90 MiB</td>
					<td>1.89 GB</td>
					<td>4.12는 불필요, 이후 버전은 토큰 필요</td>
			</tr>
			<tr>
					<td>Moto 5.2.6 (서버)</td>
					<td>0.7–0.8초</td>
					<td>45 MiB</td>
					<td>560 MB</td>
					<td>불필요</td>
			</tr>
			<tr>
					<td>Floci 1.5.5</td>
					<td>0.3–0.4초</td>
					<td>11 MiB</td>
					<td>292 MB</td>
					<td>불필요</td>
			</tr>
	</tbody>
</table>
<p>제 Mac의 Docker에서 각각 콜드 스타트 세 번씩 잰 값입니다. 신경 쓸 만큼 느린 건 하나도 없습니다.</p>
<p>백엔드 테스트라면 저는 AWS Emulator로 시작하겠습니다. 이게 잡아내는 실수(권한, 서명, Block Public Access)는 이게 아니면 프로덕션에서야 드러나는 것들이고, 이 목록에서 무료이면서 최신이고 S3를 만드는 사람들이 직접 만든 건 이것뿐이니까요. CORS preflight가 구현되기 전까지는 브라우저 쪽 검사(preflight, 그리고 공개 프리픽스에서의 익명 다운로드)를 위한 작은 잡 하나를 Floci로 남겨 두겠습니다. 엄격한 서명 검사를 켠 LocalStack 4.12도 이 검사들을 통과하지만, 멈춰 있는 버전이라 수정이 나오지 않습니다. 테스트가 Python이고 컨테이너를 띄우고 싶지 않다면 여전히 Moto의 인프로세스 mock이 가장 가볍습니다. 다만 presigned URL 검사만큼은 Moto에 맡기지 마세요.</p>
<p>검사 12개는 오후 한나절이면 자기 버킷에 맞게 쓸 수 있을 만큼 짧습니다. 어떤 에뮬레이터든, 이것까지 포함해서, 믿기 전에 꼭 한번 해 보길 권합니다. 표에 나온 도구는 저마다 다른 검사에서 실패했고, 그게 바로 여러분의 테스트가 조용히 넘어가 버릴 빈틈입니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/aws-emulator-setup/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>pytest-testmon: 변경된 코드에 영향받는 테스트만 실행하기</title>
      <link>https://jared.lynskey.co.nz/ko/posts/2026/2026-10-26-pytest-testmon/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/ko/posts/2026/2026-10-26-pytest-testmon/</guid>
      <pubDate>Mon, 26 Oct 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Python</category>
      <category>Django</category>
      <category>pytest</category>
      <category>Testing</category>
      <category>Test Impact Analysis</category>
      <category>CI/CD</category>
      <category>GitHub Actions</category>
      <category>Claude Code</category>
      <category>AI Agents</category>
      <category>Efficiency</category>
      <description>pytest-testmon은 변경이 닿는 테스트만, 짐작이 아니라 커버리지 기록으로 골라 돌립니다. 테스트 2,248개짜리 Django 스위트에 넣은 방법, 필요한 래퍼, Python 3.14의 함정.</description>
      <content:encoded><![CDATA[<p><a href="https://www.testmon.org/"  target="_blank" rel="noreferrer">pytest-testmon</a>은 변경 사항이 영향을 줄 수 있는 테스트만 실행하는 pytest 플러그인입니다. coverage.py로 각 테스트가 어떤 코드 줄을 실행하는지 지켜보고, 테스트가 거쳐 간 코드 블록마다 체크섬을 저장해 둡니다. 다음 실행에서는 그 체크섬을 디스크의 코드와 비교해서, 블록이 바뀐 테스트와 지난번에 실패한 테스트만 돌립니다. <code>pytest --lf</code>가 하던 일까지 겸하는 셈이죠.</p>
<p>이런 기법을 통틀어 테스트 영향 분석(test impact analysis)이라고 하는데, testmon은 Python에서 이걸 무료 오픈소스로 쓰는 방법입니다. git과는 아무 상관이 없습니다. 커밋을 했든 안 했든, 지난 실행에서 본 것과 비교할 뿐입니다.</p>
<p>이번 주에 제 마켓플레이스 앱의 Python 테스트에 이걸 넣었습니다. 속도 자체가 목적은 아니었습니다.</p>
<figure>
  <div class="mc-film">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRmYAAABXRUJQVlA4IFoAAADwBACdASogABIAPw1wqUqmIyGYDAQAYxDE9IAAS3igrsLc+giUXH/mz758faBcoAAA/vVl8+gZ7GYAPuvC1znoo64X/UaaVXzZOS4gxmDEyDUzHvkl6JAAAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="이 글을 내레이션으로 소개하는 짧은 영상">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_ko.vtt" srclang="ko" label="한국어" default>
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_zh-cn.vtt" srclang="zh-cn" label="简体中文">
  </video>
  </div>
  <script>window.mcFilm && window.mcFilm()</script><figcaption>이 글을 약 8분짜리 영상으로 만들었습니다. 내레이션은 영어이고 한국어 자막이 나옵니다.</figcaption>
</figure>


<h2 class="relative group">넣은 이유
    <div id="넣은-이유" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%84%a3%ec%9d%80-%ec%9d%b4%ec%9c%a0" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>기능 요청은 대개 작습니다. 화면 하나, 엔드포인트 하나, 다르게 동작해야 하는 규칙 하나. 그런데 테스트 스위트를 통째로 돌리다 보니 요청마다 실제보다 커졌습니다. 스위트는 Django 테스트 2,248개로, 프로세스 넷이면 3분 반쯤, 하나면 11분이 걸립니다. 그런데 수정할 때마다 이걸 전부 돌렸습니다. 그 거의 전부가 요청과는 아무 상관 없는 것을 확인하는데도요. 상관없는 테스트가 실패하거나 그냥 실행이 오래 걸리면 기능은 기다려야 했습니다. 기능 요청과 무관한 사정에 발이 묶인 건데, 발목을 잡은 게 다름 아닌 제 테스트 스위트였죠.</p>
<p>그렇다고 다른 길이 더 나은 것도 아니었습니다. 전체 실행을 건너뛰고, 변경을 다루는 테스트 파일이 어느 건지 짐작하고, 가끔은 틀리는 겁니다. 빠르긴 해도 정확하지는 않습니다. 그리고 테스트 없이 내보낸 변경은 같은 기능 요청을 두 번 처리하게 만듭니다.</p>
<p>제가 기다리는 테스트는 변경이 닿을 수 있는 테스트와 정확히 같아야 합니다. 더도 덜도 말고요. testmon은 그 집합을 짐작이 아니라 기록으로 줍니다. 전체 스위트는 여전히 CI에서 돕니다. 거기서는 제가 다음에 할 작업을 붙잡지 않습니다.</p>

<h2 class="relative group">돌릴 테스트를 고르는 방식
    <div id="돌릴-테스트를-고르는-방식" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%8f%8c%eb%a6%b4-%ed%85%8c%ec%8a%a4%ed%8a%b8%eb%a5%bc-%ea%b3%a0%eb%a5%b4%eb%8a%94-%eb%b0%a9%ec%8b%9d" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>testmon은 Python 파일 하나를 여러 블록으로 나눕니다. 모듈 최상위, 각 클래스, 각 함수가 블록이 되고, 중첩 함수의 본문은 바깥 블록에서 잘라 냅니다. 저장하는 건 블록마다의 체크섬이고, 코드 자체는 저장하지 않습니다. 테스트가 도는 동안 coverage.py가 실행된 줄을 기록하면, testmon은 그 줄이 어느 블록에 속하는지 적어 둡니다. 정적 분석도 없고, import를 보고 짐작하지도 않습니다. 테스트는 정확히 자기가 실행한 블록에만 의존합니다.</p>
<p>이런 모듈이 있다고 해 보죠.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># pricing.py</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">subtotal</span><span class="p">(</span><span class="n">items</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">price</span> <span class="o">*</span> <span class="n">item</span><span class="o">.</span><span class="n">quantity</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">discount</span><span class="p">(</span><span class="n">total</span><span class="p">,</span> <span class="n">code</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">code</span> <span class="o">==</span> <span class="s2">&#34;WELCOME10&#34;</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">total</span> <span class="o">*</span> <span class="mf">0.9</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">total</span></span></span></code></pre></div></div>
<p><code>subtotal()</code>만 호출하는 테스트는 모듈 최상위와 <code>subtotal</code>의 본문에 의존합니다. <code>discount()</code>를 어떻게 고쳐 쓰든 testmon은 그 테스트를 다시 돌리지 않습니다. <code>discount</code>의 줄을 하나도 실행한 적이 없으니까요. 반대로 <code>subtotal</code> 안에서 글자 하나만 바꿔도, 결과가 달라질 수 없는 변경이라 해도 테스트는 다시 돕니다. testmon은 부작용을 두고 머리를 굴리지 않습니다. 실행한 블록이 바뀌었으면 다시 돌 뿐입니다.</p>
<p>코드를 둘러싼 환경도 추적합니다. 기록에는 Python 버전, 그리고 설치된 패키지와 그 버전이 들어갑니다. 환경 변수는 보지 않습니다. 같은 코드를 설정 모듈 두 개로 돌린다면 <code>--testmon-env</code>(8단계)로 이름을 붙여 주지 않으면 기록 하나를 같이 쓰게 됩니다. Django를 업그레이드하면 Django를 건드린 테스트가 전부 다시 영향을 받는데, Django 앱에서는 그게 곧 전부입니다.</p>

<h2 class="relative group">보지 못하는 것
    <div id="보지-못하는-것" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%eb%b3%b4%ec%a7%80-%eb%aa%bb%ed%95%98%eb%8a%94-%ea%b2%83" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>testmon이 추적하는 건 테스트가 실행하는 Python입니다. 테스트가 읽는 다른 파일, 그러니까 템플릿, JSON, 텍스트, 그 밖에 디스크에 있는 무엇이든 추적하지 않습니다. 네트워크 너머의 서비스도 추적하지 않습니다. 그리고 테스트가 시작되기 전에 한 번 실행되는 것은 어느 특정 테스트에도 묶을 수 없습니다.</p>
<p>Django 프로젝트라면 우선 마이그레이션입니다. 테스트 데이터베이스를 만들 때 한 번 실행되기 때문에 어느 테스트의 기록에도 들어가지 않습니다(아래 래퍼는 새 마이그레이션이 생기면 테스트 데이터베이스를 다시 만듭니다). 다음은 설정과 시작 코드로, pytest가 시작하는 동안 어느 한 테스트의 바깥에서 실행됩니다. 그리고 템플릿과 데이터 파일입니다. 템플릿은 Python이 아니라서, 고쳐도 그걸 렌더링하는 테스트가 하나도 다시 돌지 않습니다.</p>
<p>제 스위트에는 이런 게 몇 가지 더 있습니다. 어떤 테스트는 모바일 앱의 테스트와 함께 쓰는 픽스처 JSON 파일을 읽습니다. 어떤 테스트는 빌드된 웹 번들을 확인하고, 또 어떤 테스트는 같은 저장소에서 생성하는 정적 사이트의 결과물을 확인합니다. 이 중 무엇을 바꾸든 testmon은 태연하게 돌릴 게 없다고 할 겁니다. 아래 방법에서 testmon을 스크립트로 감싸고, 이런 파일이 바뀌면 알아채서 전부 돌리게 하는 이유가 이겁니다.</p>

<h2 class="relative group">Django 프로젝트에 넣는 방법
    <div id="django-프로젝트에-넣는-방법" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#django-%ed%94%84%eb%a1%9c%ec%a0%9d%ed%8a%b8%ec%97%90-%eb%84%a3%eb%8a%94-%eb%b0%a9%eb%b2%95" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>아래 단계는 pytest와 <a href="https://pytest-django.readthedocs.io/"  target="_blank" rel="noreferrer">pytest-django</a>를 쓰고, 의존성은 uv로 관리한다고 가정합니다. pip를 쓴다면 <code>uv add --dev</code>를 <code>pip install</code>로 바꾸고 <code>uv run</code>은 빼세요.</p>
<p><strong>1. 설치합니다.</strong></p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv add --dev pytest-testmon</span></span></code></pre></div></div>
<p><strong>2. pytest로 스위트를 돌릴 수 있는지 확인합니다.</strong> testmon은 pytest 플러그인이라 <code>python manage.py test</code>에서는 아무 일도 하지 않습니다. pytest-django에는 설정 모듈과 테스트가 쓰는 파일 패턴을 알려 줘야 합니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># pytest.ini</span>
</span></span><span class="line"><span class="cl"><span class="k">[pytest]</span>
</span></span><span class="line"><span class="cl"><span class="na">DJANGO_SETTINGS_MODULE</span> <span class="o">=</span> <span class="s">myproject.settings</span>
</span></span><span class="line"><span class="cl"><span class="na">python_files</span> <span class="o">=</span> <span class="s">tests.py test_*.py *_tests.py</span>
</span></span><span class="line"><span class="cl"><span class="na">python_classes</span> <span class="o">=</span> <span class="s">Test* *Tests *TestCase</span></span></span></code></pre></div></div>
<p>지금까지 Django의 러너로만 스위트를 돌렸다면, testmon을 넣기 전에 pytest로 한 번 돌려 보고 결과가 달라지는 부분부터 고치세요. 그러지 않으면 두 가지를 한꺼번에 디버깅하게 됩니다.</p>
<p><strong>3. 기록은 git에 넣지 않습니다.</strong> testmon은 pytest 루트 디렉터리에 <code>.testmondata</code>를 씁니다. SQLite 데이터베이스라서 옆에 <code>-shm</code>과 <code>-wal</code> 파일도 생기고, 아래 스크립트가 스탬프 파일을 하나 더 만듭니다. 패턴 하나로 전부 처리됩니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># .gitignore
</span></span><span class="line"><span class="cl">.testmondata*</span></span></code></pre></div></div>
<p><strong>4. 스위트 전체를 한 번 기록합니다.</strong> testmon은 모든 테스트가 도는 걸 한 번 보기 전까지는 아무것도 고를 수 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv run pytest --testmon</span></span></code></pre></div></div>
<p>새로 받은 체크아웃에서는 이 첫 실행이 프로세스 하나로 스위트 전체를 돕니다. 제 경우엔 테스트 2,248개에 12분쯤 걸립니다. 그다음부터는 같은 명령이 영향받는 테스트만 돌립니다. 바뀐 게 없으면 아무것도 돌리지 않습니다.</p>
<p>주의할 점이 두 가지 있습니다. testmon 2.2.0 이하에서는 pytest의 캐시 플러그인이 필요합니다. 처음에는 <code>-p no:cacheprovider</code>를 붙여 돌렸다가 <code>KeyError: 'lf'</code>로 죽었습니다(2.3.0은 <code>--lf</code>가 없으면 미지정으로 처리합니다). 그리고 Python 3.14 이상이라면 기록하기 전에 <code>COVERAGE_CORE=ctrace</code>를 설정하세요. 이유는 뒤에 나오는 &ldquo;초록불처럼 보였던 버그&quot;에서 설명합니다. 아래 스크립트에서 가장 중요한 한 줄입니다.</p>
<p>업데이트(11월 7일): 11월 2일에 나온 testmon 2.3.0은 coverage의 C 트레이서를 스스로 강제하므로, 그 버전에서는 이 export가 혹시 몰라 두는 줄이 됩니다. 2.2.0 이하라면 그대로 두세요. 그리고 일부러 망가뜨려 확인하는 검사는 버전과 상관없이 계속하세요.</p>
<p><strong>5. testmon이 보지 못하는 파일까지 챙기도록 감쌉니다.</strong> 매일 안심하고 쓸 수 있게 해 주는 게 이 부분입니다. 스크립트는 지난 실행이 시작된 시점의 스탬프 파일을 남겨 둡니다. testmon이 추적할 수 없는 파일 중 스탬프보다 새로운 게 하나라도 있으면 전부 돌리고 처음부터 다시 기록합니다. 새 마이그레이션이라면 테스트 데이터베이스만 다시 만듭니다. 그 밖에는 testmon에게 고르게 맡깁니다. 줄인 예제입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/usr/bin/env bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># scripts/test-changed.sh: the tests a change can affect, or all when in doubt.</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh            # affected tests</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh --all      # everything, re-recorded</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh -k orders  # anything else goes to pytest</span>
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -euo pipefail
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> <span class="s2">&#34;</span><span class="k">$(</span>dirname <span class="s2">&#34;</span><span class="nv">$0</span><span class="s2">&#34;</span><span class="k">)</span><span class="s2">/..&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># coverage&#39;s C tracer: from Python 3.14 coverage defaults to sys.monitoring,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># which reports a line only the first time a process runs it, so testmon</span>
</span></span><span class="line"><span class="cl"><span class="c1"># would credit each line to one test. Changing this means --all.</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">COVERAGE_CORE</span><span class="o">=</span>ctrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">STAMP</span><span class="o">=</span>.testmondata.started
</span></span><span class="line"><span class="cl"><span class="nv">full</span><span class="o">=</span><span class="nb">false</span>
</span></span><span class="line"><span class="cl"><span class="nv">rebuild</span><span class="o">=</span><span class="nb">false</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> <span class="s2">&#34;</span><span class="si">${</span><span class="nv">1</span><span class="k">:-</span><span class="si">}</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="s2">&#34;--all&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nv">full</span><span class="o">=</span>true<span class="p">;</span> <span class="nb">shift</span>
</span></span><span class="line"><span class="cl"><span class="k">elif</span> <span class="o">[</span> ! -f .testmondata <span class="o">]</span> <span class="o">||</span> <span class="o">[</span> ! -f <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;No record yet: running everything once.&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nv">full</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="k">else</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Changed since the last run started, and not traceable per test:</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># anything that isn&#39;t Python, plus settings and conftest.</span>
</span></span><span class="line"><span class="cl">    <span class="nv">newer</span><span class="o">=</span><span class="s2">&#34;</span><span class="k">$(</span>find myapp myproject fixtures pytest.ini <span class="se">\
</span></span></span><span class="line"><span class="cl">        -type f -newer <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> ! -path <span class="s1">&#39;*/migrations/*&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        <span class="se">\(</span> ! -name <span class="s1">&#39;*.py&#39;</span> -o -path <span class="s1">&#39;myproject/settings*&#39;</span> -o -name <span class="s1">&#39;conftest.py&#39;</span> <span class="se">\)</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        ! -path <span class="s1">&#39;*/__pycache__/*&#39;</span> <span class="p">|</span> head -5<span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -n <span class="s2">&#34;</span><span class="nv">$newer</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Changed, and not traceable per test:&#34;</span><span class="p">;</span> <span class="nb">printf</span> <span class="s1">&#39;  %s\n&#39;</span> <span class="nv">$newer</span>
</span></span><span class="line"><span class="cl">        <span class="nv">full</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># A new migration needs a fresh test database, not a full run.</span>
</span></span><span class="line"><span class="cl">    <span class="o">[</span> -n <span class="s2">&#34;</span><span class="k">$(</span>find myapp -path <span class="s1">&#39;*/migrations/*.py&#39;</span> -newer <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="p">|</span> head -1<span class="k">)</span><span class="s2">&#34;</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">rebuild</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Stamp the start, so an edit made while the tests run counts next time.</span>
</span></span><span class="line"><span class="cl"><span class="nv">started</span><span class="o">=</span><span class="s2">&#34;</span><span class="k">$(</span>mktemp .testmondata.run.XXXXXX<span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">args</span><span class="o">=(</span>--testmon --reuse-db<span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># --create-db alone deletes the database when the run ends; with</span>
</span></span><span class="line"><span class="cl"><span class="c1"># --reuse-db as well, the rebuilt one is kept for next time.</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$rebuild</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="nb">true</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">args</span><span class="o">=(</span>--testmon --reuse-db --create-db<span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$full</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="nb">true</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">args</span><span class="o">=(</span>--testmon-noselect --reuse-db --create-db<span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">status</span><span class="o">=</span><span class="m">0</span>
</span></span><span class="line"><span class="cl">uv run pytest <span class="s2">&#34;</span><span class="si">${</span><span class="nv">args</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span> -q <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span> <span class="o">||</span> <span class="nv">status</span><span class="o">=</span><span class="nv">$?</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 0: passed, or nothing selected. 1: some failed (still recorded).</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 5: nothing collected at all.</span>
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span> in 0<span class="p">|</span>1<span class="p">|</span>5<span class="o">)</span> mv <span class="s2">&#34;</span><span class="nv">$started</span><span class="s2">&#34;</span> <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="p">;;</span> *<span class="o">)</span> rm -f <span class="s2">&#34;</span><span class="nv">$started</span><span class="s2">&#34;</span> <span class="p">;;</span> <span class="k">esac</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="m">5</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nb">exit</span> <span class="m">0</span>
</span></span><span class="line"><span class="cl"><span class="nb">exit</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span></span></span></code></pre></div></div>
<p>여기서 두 가지는 짚고 넘어갈 만합니다. <code>--reuse-db</code>는 실행 사이에 테스트 데이터베이스를 유지하는 pytest-django의 플래그입니다. 실행이 몇 초로 줄어들면 이게 중요해집니다. 매번 데이터베이스를 새로 만드는 데 테스트 자체보다 오래 걸릴 수도 있거든요. 전체 실행이나 새 마이그레이션 뒤의 실행에서는 데이터베이스가 현재 스키마를 갖도록 <code>--create-db</code>를 더합니다. 이때 <code>--reuse-db</code>도 옆에 남겨 두세요. <code>--create-db</code>만 쓰면 pytest-django가 실행이 끝날 때 데이터베이스를 지워 버려서, 다음 실행이 처음부터 다시 만들어야 합니다.</p>
<p>그리고 testmon이 모든 테스트를 선택에서 빼면 실행은 0으로 끝나니, &ldquo;바뀐 것 없음&quot;은 통과로 칩니다. 종료 코드 5는 pytest의 &ldquo;수집된 테스트 없음&quot;인데, 스크립트는 이것도 문제없는 것으로 봅니다.</p>
<p>목록에 없는 것도 눈여겨보세요. <code>pyproject.toml</code>과 락 파일입니다. 첫 버전은 락 파일이 바뀔 때마다 전부 돌렸는데, 그러다 보니 느린 대체 경로가 거의 매일 작동해서 오히려 전보다 나빠졌습니다. testmon은 설치된 패키지 버전을 이미 직접 추적하니, 도와줄 필요가 없습니다.</p>
<p><strong>6. 전용 데이터베이스와 캐시를 줍니다.</strong> 같은 머신에서 다른 것도 테스트를 돌린다면, 이를테면 두 번째 터미널이나 코딩 에이전트, <code>manage.py test</code> 같은 것이 있다면, 스크립트가 자기만의 테스트 데이터베이스와 캐시 번호를 쓰게 하세요. 그래야 유지해 둔 데이터베이스가 남의 실행과 마주칠 일이 없습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">DATABASE_URL</span><span class="o">=</span><span class="s2">&#34;postgresql://myapp:myapp@localhost:5432/myapp_changed&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">REDIS_URL</span><span class="o">=</span><span class="s2">&#34;redis://localhost:6379/8&#34;</span></span></span></code></pre></div></div>
<p><strong>7. 실행할 때마다 먼저 그 캐시를 비웁니다.</strong> 이건 호되게 겪고 배웠습니다. 전체 실행에서는 나지 않던 <code>KeyError</code>로 부분 실행이 실패하기 시작했습니다. 카테고리 라벨 몇 개가 만료 없이 캐시되어 있었는데, 한 실행에서 유지한 테스트 데이터베이스가 그보다 앞선 실행이 데워 둔 캐시와 만난 겁니다. 스크립트 맨 위에서 캐시를 비우니 해결됐습니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv run python -c <span class="s2">&#34;import os, redis; redis.Redis.from_url(os.environ[&#39;REDIS_URL&#39;]).flushdb()&#34;</span></span></span></code></pre></div></div>
<p>testmon은 문서에 적힌 대로 일했을 뿐입니다. 매번 다른 부분 집합을 돌리면, 앞서 돈 테스트 덕분에 통과하던 테스트가 드러납니다. 고칠 곳은 testmon이 아니라 테스트 설정입니다.</p>
<p><strong>8. 선택이 틀렸을 때 쓸 플래그를 알아 둡니다.</strong></p>
<ul>
<li><code>--testmon-noselect</code>는 모든 테스트를 돌리되 실패할 가능성이 높은 것부터 돌립니다. <code>-k</code>, <code>-m</code>, <code>--lf</code>나 테스트의 노드 ID를 함께 넘기면 testmon이 알아서 이 모드로 바꿉니다.</li>
<li><code>--testmon-forceselect</code>는 영향받는 테스트 중 <code>-k</code>나 <code>-m</code>에도 맞는 것만 돌립니다.</li>
<li><code>--testmon-nocollect</code>는 기존 기록을 쓰되 거기에 보태지는 않습니다. 디버거 아래에서나 coverage가 이미 돌고 있을 때는 강제로 이 모드가 됩니다.</li>
<li><code>--no-testmon</code>은 한 번의 실행에서만 testmon을 끕니다. <code>addopts</code>에 넣어 두었을 때 씁니다.</li>
<li><code>--testmon-env=&lt;name&gt;</code>은 한 파일 안에 기록을 따로따로 둡니다. 설정 모듈 두 개로 돌리는 스위트에 씁니다.</li>
</ul>
<p>프로젝트에 JavaScript 쪽도 있다면, Jest에는 같은 기능이 내장돼 있습니다. <code>jest --changedSince=main</code>은 <code>main</code> 이후 바뀐 것을 import하는 테스트를 돌리는데, coverage가 아니라 import를 따라갑니다. 저는 이걸 앱의 <code>package.json</code>에 <code>npm run test:changed</code>로 넣어서 양쪽이 같은 습관을 갖게 했습니다. 유틸리티 모듈 하나를 고쳤더니 앱의 테스트 파일 121개 중 7개가 선택됐습니다.</p>

<h2 class="relative group">얼마나 아껴 주나
    <div id="얼마나-아껴-주나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%96%bc%eb%a7%88%eb%82%98-%ec%95%84%ea%bb%b4-%ec%a3%bc%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>래퍼를 넣고 다음 절의 버그까지 고친 뒤, 시작 시간을 포함해서 재 봤습니다.</p>
<table>
	<thead>
			<tr>
					<th>바뀐 것</th>
					<th style="text-align: right">실행한 테스트</th>
					<th style="text-align: right">시간</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>없음</td>
					<td style="text-align: right">0</td>
					<td style="text-align: right">1.0초</td>
			</tr>
			<tr>
					<td>홈 화면 배너 뒤의 코드 한 군데 수정</td>
					<td style="text-align: right">17</td>
					<td style="text-align: right">8.5초</td>
			</tr>
			<tr>
					<td>그 수정 되돌리기</td>
					<td style="text-align: right">17</td>
					<td style="text-align: right">8.7초</td>
			</tr>
			<tr>
					<td>비교용 스위트 전체(프로세스 4개)</td>
					<td style="text-align: right">2,248</td>
					<td style="text-align: right">약 3½분</td>
			</tr>
	</tbody>
</table>
<p>평소의 수정이라면 병렬 스위트보다 25배쯤 빠르고, 바뀐 게 없을 때는 200배쯤 빠릅니다.</p>
<p>기록도 더 넓은 범위에서 같은 말을 합니다. 스위트가 실행하는, 테스트가 아닌 Python 파일 307개 가운데 중앙값에 해당하는 파일을 바꾸면 테스트 22개, 테스트 시간으로 8초쯤에 닿습니다. 반대쪽 끝에는 핵심 모듈 몇 개가 있습니다. 거의 모든 테스트가 이 모듈들을 실행하니, 여기를 바꾸면 1,500개 안팎의 테스트에 닿고 testmon은 스위트 대부분을 다시 돌립니다. 그게 맞는 답이지, 실패가 아닙니다. 이 수치들은 파일별 상한입니다. testmon은 블록 단위로 일하니까, 함수 하나를 바꾸면 그 함수를 실행한 테스트만 고릅니다.</p>
<p>비용은 래퍼가 대체 경로로 넘어갈 때 드러납니다. 전체 실행은 첫 실행과 똑같이 프로세스 하나로 기록하는 실행이라 12분쯤 걸리고, 그건 이 래퍼가 대신하는 병렬 스위트보다 느립니다. 프로세스 하나로 도는 건 testmon을 pytest-xdist와 함께 아직 안 써 봤기 때문입니다. xdist는 1.4부터 지원하니, 다음에 재 볼 건 그쪽이죠. 그래서 전체 실행을 촉발하는 파일 목록은 정직하게 줄일 수 있는 데까지 짧아야 합니다.</p>

<h2 class="relative group">초록불처럼 보였던 버그
    <div id="초록불처럼-보였던-버그" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%b4%88%eb%a1%9d%eb%b6%88%ec%b2%98%eb%9f%bc-%eb%b3%b4%ec%98%80%eb%8d%98-%eb%b2%84%ea%b7%b8" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>처음 잰 수치는 이것보다 좋았습니다. 수정 한 번에 테스트 6개, 3.3초. 그런데 틀린 수치였고, 화면 어디에도 그런 말은 없었습니다.</p>
<p>Python 3.14부터 coverage.py는 인터프리터의 <code>sys.monitoring</code> 위에 만든 새 코어를 기본으로 씁니다. 이 코어는 한 프로세스가 어떤 줄을 처음 실행할 때만 그 줄을 보고합니다. testmon은 어느 테스트가 어느 줄을 실행했는지를 coverage에서 받아 기록을 만드니, 각 줄은 우연히 그 줄을 처음 실행한 테스트 하나에만 돌아가고 다른 테스트에는 하나도 돌아가지 않았습니다. 테스트 여덟 개가 함께 거치는 줄을 고치면 testmon은 그중 하나만 고르는 거죠.</p>
<p>이걸 잡아낸 건 이 설정을 그대로 가져다 쓴 제 다른 작은 프로젝트였습니다. 거기에 도입하면서 일부러 한 줄을 망가뜨리고 결과를 비교해 봤는데, 숫자가 맞지 않았습니다. 이 스위트로 돌아와 같은 확인을 해 봤습니다. 홈 화면 배너 코드에서 슬라이드 제목 한 줄을 망가뜨렸더니, 그냥 pytest는 실패한 테스트 8개를 보고했고 testmon은 4개를 골랐습니다. 망가진 나머지 4개는 한 번도 돌지 않았고, 출력 어디에도 그것들이 빠졌다는 말은 없었습니다.</p>
<p>고치는 건 한 줄, <code>export COVERAGE_CORE=ctrace</code>입니다. coverage를 예전의 C 트레이서로 되돌리는 설정이죠. 트레이서가 다르면 기록도 달라지니 다시 기록했습니다. 테스트 2,248개에 12분 3초. 그 뒤로는 같은 식으로 망가뜨리는 수정을 하면, 그 수정으로 깨진 테스트 11개가 전부 돌았습니다.</p>
<p>업데이트(11월 7일): 11월 2일에 나온 testmon 2.3.0은 프로세스 안에서도, 서브프로세스에서도 C 트레이서를 스스로 설정하므로 새로 설치하면 이 export는 더 이상 필요 없습니다. 다음 문단의 검사는 여전히 필요합니다.</p>
<p>이 글에서 무엇보다 먼저 전하고 싶은 교훈이 이겁니다. 너무 적게 고르는 테스트 선택기는 성공과 똑같이 생겼습니다. 테스트는 적고, 실행은 빠르고, 전부 초록불이죠. 그러니 선택기를 설정할 때는 여러 테스트가 함께 쓰는 무언가를 일부러 망가뜨리고, 그냥 스위트와 선택기를 둘 다 돌려서 같은 테스트가 실패하는지 확인하세요. 그리고 Python이나 coverage.py의 버전이 바뀔 때마다 다시 확인하세요.</p>

<h2 class="relative group">코딩 에이전트가 들어오는 자리
    <div id="코딩-에이전트가-들어오는-자리" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%bd%94%eb%94%a9-%ec%97%90%ec%9d%b4%ec%a0%84%ed%8a%b8%ea%b0%80-%eb%93%a4%ec%96%b4%ec%98%a4%eb%8a%94-%ec%9e%90%eb%a6%ac" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>이제 그 저장소의 변경을 전부 제 손으로 하지는 않습니다. 작은 변경은 코딩 에이전트가, 제 경우엔 Claude Code가 많이 맡는데, 좋은 에이전트는 수정할 때마다 테스트를 돌립니다. 11분짜리 스위트 앞에서는 에이전트도 제가 겪던 나쁜 선택지 두 개를 똑같이 마주합니다. 기다리거나, 어느 테스트 파일이 중요한지 짐작하거나.</p>
<p>그래서 저장소의 에이전트 지침에 이제 이렇게 적혀 있습니다. 작업 중에 테스트를 돌리는 기본 방법은 래퍼 스크립트이고, 전체 실행은 <code>--all</code>. 에이전트는 수정할 때마다 저와 똑같이 정확한 테스트 집합을 몇 초 만에 받습니다. 6단계에서 스크립트에 전용 데이터베이스와 캐시를 준 것도 이 때문입니다. 바쁜 날에는 같은 머신에서 테스트를 돌리는 세션이 하나가 아니고, 유지해 둔 데이터베이스가 남의 실행과 마주쳐서는 절대 안 되니까요.</p>
<p>testmon에 AI 전용 기능이 따로 필요한 건 하나도 없습니다. 같은 기록, 같은 선택입니다. 다만 변경을 만드는 쪽이 변경을 아주 많이 만들 때 더 중요해질 뿐이죠.</p>

<h2 class="relative group">CI에는 왜 더 거친 버전을 넣었나
    <div id="ci에는-왜-더-거친-버전을-넣었나" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#ci%ec%97%90%eb%8a%94-%ec%99%9c-%eb%8d%94-%ea%b1%b0%ec%b9%9c-%eb%b2%84%ec%a0%84%ec%9d%84-%eb%84%a3%ec%97%88%eb%82%98" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>testmon에는 CI 모드가 없습니다. 러너에서도 노트북에서와 똑같이 동작하고, 작성자는 CI 러너끼리 <code>.testmondata</code>를 공유하거나 캐시하는 방식이 자기네 호스팅 서비스인 testmon.net보다 훨씬 덜 효과적이라고 적어 두었습니다. 캐시된 기록은 앞에서 말한 모든 면에서 눈이 먼 채일 테고, 제 CI는 Django의 러너로 프로세스 넷에서 스위트를 돌리니, testmon은 빼 두었습니다.</p>
<p>대신 CI에는 같은 아이디어를 파일 단위로 넣었습니다. 체크 워크플로는 이제 작은 잡 하나로 시작하는데, 이 잡이 push의 diff를 보고 저장소의 어느 쪽을 건드렸는지 정합니다. Python API인지, 모바일 앱인지, 둘 다인지, 둘 다 아닌지. 전에는 문서만 바꾼 push까지 포함해 모든 push에서 Python 잡과 앱 잡을 둘 다 돌렸습니다. 이제 문서만 바꾼 push는 아무것도 돌리지 않고, 앱만 바꾼 push는 Django 스위트를 건너뜁니다. 실제 커밋 다섯 개에 대고 이 잡을 시험 삼아 돌려 봤더니, 문서만 바꾼 커밋은 아무것도 돌리지 않았고, 앱만 바꾼 커밋은 Python 잡을, 백엔드만 바꾼 커밋은 앱 잡을 건너뛰었습니다. 줄인 예제입니다.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">outputs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">python</span><span class="p">:</span><span class="w"> </span><span class="l">${{ steps.diff.outputs.python }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">fetch-depth</span><span class="p">:</span><span class="w"> </span><span class="m">0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">id</span><span class="p">:</span><span class="w"> </span><span class="l">diff</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">BEFORE</span><span class="p">:</span><span class="w"> </span><span class="l">${{ github.event.before }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">HEAD</span><span class="p">:</span><span class="w"> </span><span class="l">${{ github.sha }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          FILES=&#34;$(git diff --name-only &#34;$BEFORE&#34; &#34;$HEAD&#34;)&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          # Python&#39;s inputs include the non-Python files its tests read.
</span></span></span><span class="line"><span class="cl"><span class="sd">          PY=&#39;^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">          if printf &#39;%s\n&#39; &#34;$FILES&#34; | grep -qE &#34;$PY&#34;; then
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;python=true&#34; &gt;&gt; &#34;$GITHUB_OUTPUT&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          else
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;python=false&#34; &gt;&gt; &#34;$GITHUB_OUTPUT&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          fi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">python</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">needs</span><span class="p">:</span><span class="w"> </span><span class="l">changes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l">needs.changes.outputs.python == &#39;true&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run python manage.py test --parallel 4 --noinput</span></span></span></code></pre></div></div>
<p>실제 워크플로는 비교할 범위가 없을 때도 전부 돌립니다. 새 브랜치, 강제 push, 수동 실행이 그런 경우입니다.</p>
<p>사각지대는 모양만 다를 뿐 그대로입니다. testmon이 JSON 파일을 못 보듯, 경로 필터도 목록에 적어 주지 않으면 못 봅니다. 그래서 패턴에 공유 픽스처, 빌드된 번들, 생성된 사이트를 명시적으로 적고, 이걸 고치는 사람은 목록을 정직하게 유지해 달라는 주석을 달아 두었습니다. 파일 단위 버전은 더 투박하지만, 실패하더라도 안전한 쪽으로 실패합니다. Python 쪽에서 뭐든 바뀌었으면 스위트 전체가 돕니다.</p>

<h2 class="relative group">써 볼 만한가요?
    <div id="써-볼-만한가요" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%ec%8d%a8-%eb%b3%bc-%eb%a7%8c%ed%95%9c%ea%b0%80%ec%9a%94" aria-label="앵커">#</a>
    </span>
    
</h2>
<p>몇 분씩 걸리는 스위트라면, 네. 진짜 비용은 testmon이 보지 못하는 것들이고, 래퍼 스크립트가 그걸 위해 있습니다. 그렇다 해도 testmon이 있어야 할 자리는 노트북에서 도는 작업 루프입니다. CI는 Python 쪽이 바뀔 때마다 여전히 스위트 전체를 돌리고, 배포 전에 제가 믿는 건 그 실행입니다.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
