AWS Emulator で AWS SDK を使うコードをローカルでテストする

FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-aarch64.rpm /tmp/aws-emulator.rpm
RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
    && mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]

docker build -t aws-emulator .
docker run --rm aws-emulator -v

Version: 1.0.353
Release date: 2026.11.14
Commit: ca8a89dedfa8e4b5e67a3c90dc736f921ba409a1

mkdir -p ~/.aws/emulator
PORT=9297
# --memory, --memory-swap: メモリを 2 GiB に制限し、スワップを使わない
# -p 127.0.0.1:...: 自分のマシンにだけ公開する（-p 9297:9297 ではネットワーク全体に公開される）
# -e HOME: コンテナ内でもホストと同じパスを使い、config に書かれるパスをホストでも有効にする
# -v: エミュレーターが生成した認証情報と証明書をホストから読めるようにする
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  aws-emulator -p $PORT

{
  "message": "emulator server information",
  "endpoint_url": "https://127.0.0.1:9297",
  "health_check_url": "https://127.0.0.1:9297/__admin/health",
  "config_file": "/Users/you/.aws/emulator/9297/config",
  "ca_file": "/Users/you/.aws/emulator/9297/ca.pem",
  "java_truststore_file": "/Users/you/.aws/emulator/9297/truststore.p12"
}

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

PORT=9297
export AWS_ENDPOINT_URL=https://127.0.0.1:$PORT
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/$PORT/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/$PORT/config
export AWS_CA_BUNDLE=~/.aws/emulator/$PORT/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
# AWS SDK for JavaScript v3 は AWS_CA_BUNDLE を読まないため、Node.js に証明書を追加する
export NODE_EXTRA_CA_CERTS=~/.aws/emulator/$PORT/ca.pem
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

npm init -y
npm pkg set type=module scripts.test="vitest run"
npm install @aws-sdk/[email protected] @aws-sdk/[email protected] @aws-sdk/[email protected]
npm install -D [email protected] typescript

source ./emulator.env.sh
node -e '
const { STSClient, GetCallerIdentityCommand } = require("@aws-sdk/client-sts");
new STSClient({}).send(new GetCallerIdentityCommand({})).then((r) => console.log(r.Account, r.Arn));
'

000000000000 arn:aws:iam::000000000000:user/emulator

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient,
  GetCommand,
  PutCommand,
} from "@aws-sdk/lib-dynamodb";
 
export type Todo = {
  id: string;
  title: string;
  done: boolean;
};
 
// 接続先は環境変数と設定ファイルから決まるため、endpoint も credentials も渡さない
const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));
 
export async function saveTodo(tableName: string, todo: Todo): Promise<void> {
  await client.send(new PutCommand({ TableName: tableName, Item: todo }));
}
 
export async function findTodo(
  tableName: string,
  id: string,
): Promise<Todo | undefined> {
  const { Item } = await client.send(
    new GetCommand({ TableName: tableName, Key: { id } }),
  );
  return Item as Todo | undefined;
}

import { randomUUID } from "node:crypto";
import {
  CreateTableCommand,
  DeleteTableCommand,
  DynamoDBClient,
  waitUntilTableExists,
} from "@aws-sdk/client-dynamodb";
import { GetCallerIdentityCommand, STSClient } from "@aws-sdk/client-sts";
import { afterAll, beforeAll, describe, expect, test } from "vitest";
import { findTodo, saveTodo } from "./todo-repository";
 
const dynamodb = new DynamoDBClient({});
// エミュレーターは起動中のリソースを保持するため、実行ごとに一意なテーブル名を使う
const tableName = `todos-${randomUUID()}`;
 
beforeAll(async () => {
  // 誤って本物の AWS アカウントでテストしないよう、エミュレーターの固定アカウントか確認する
  const identity = await new STSClient({}).send(new GetCallerIdentityCommand({}));
  expect(identity.Account).toBe("000000000000");
 
  await dynamodb.send(
    new CreateTableCommand({
      TableName: tableName,
      AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
      KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
      BillingMode: "PAY_PER_REQUEST",
    }),
  );
  await waitUntilTableExists(
    { client: dynamodb, maxWaitTime: 30 },
    { TableName: tableName },
  );
});
 
afterAll(async () => {
  await dynamodb.send(new DeleteTableCommand({ TableName: tableName }));
});
 
describe("todo-repository", () => {
  test("保存した Todo を取得できる", async () => {
    await saveTodo(tableName, { id: "1", title: "牛乳を買う", done: false });
 
    await expect(findTodo(tableName, "1")).resolves.toEqual({
      id: "1",
      title: "牛乳を買う",
      done: false,
    });
  });
 
  test("存在しない ID では undefined を返す", async () => {
    await expect(findTodo(tableName, "not-found")).resolves.toBeUndefined();
  });
});

source ./emulator.env.sh
npm test -- --reporter=verbose

 ✓ src/todo-repository.test.ts > todo-repository > 保存した Todo を取得できる 60ms
 ✓ src/todo-repository.test.ts > todo-repository > 存在しない ID では undefined を返す 3ms
 
 Test Files  1 passed (1)
      Tests  2 passed (2)

{
  "message": "table created",
  "operation": "CreateTable",
  "table_name": "todos-fb46292b-391c-46e9-bf58-cebeb7f42a1c",
  "billing_mode": "PAY_PER_REQUEST",
  "outcome": "created"
}