moto for Python: Mocking boto3 in Tests

moto is a Python library that mocks AWS services in-process, so boto3 calls in your tests never leave your machine.

It works by intercepting the HTTP calls botocore makes and returning simulated AWS responses, backed by an in-memory model of each service's state. Your application code doesn't know the difference - it still calls boto3.client("s3") and gets back real-shaped responses.

Recipe

The current moto API is one decorator, @mock_aws, that mocks every AWS service at once. Older per-service decorators like @mock_s3 still exist in some codebases but are deprecated in moto v5 in favor of the unified form.

# --- Python (boto3) ---
import boto3
from moto import mock_aws
 
@mock_aws
def test_create_and_list_bucket():
    s3 = boto3.client("s3", region_name="us-east-1")
    s3.create_bucket(Bucket="my-test-bucket")
 
    names = [b["Name"] for b in s3.list_buckets()["Buckets"]]
    assert "my-test-bucket" in names

// --- TypeScript (AWS SDK v3) ---
// The equivalent test pattern in the TypeScript ecosystem uses
// aws-sdk-client-mock, not moto (moto is Python-only).
import { S3Client, CreateBucketCommand, ListBucketsCommand } from "@aws-sdk/client-s3";
import { mockClient } from "aws-sdk-client-mock";
 
const s3Mock = mockClient(S3Client);
 
test("create and list bucket", async () => {
  s3Mock.on(CreateBucketCommand).resolves({});
  s3Mock.on(ListBucketsCommand).resolves({ Buckets: [{ Name: "my-test-bucket" }] });
 
  const s3 = new S3Client({});
  await s3.send(new CreateBucketCommand({ Bucket: "my-test-bucket" }));
  const res = await s3.send(new ListBucketsCommand({}));
  expect(res.Buckets?.map((b) => b.Name)).toContain("my-test-bucket");
});

When to reach for this:

• You're writing Python unit tests for code that calls boto3.
• You want realistic simulated behavior (state persists across calls in the same test) rather than one canned response.
• You need to test error paths - moto raises the same ClientError shapes real AWS would.
• You want zero network dependency and zero risk of touching a real account.

Working Example

A more complete test that seeds state, exercises a function, and checks both the return value and side effects.

# --- Python (boto3) ---
import boto3
import pytest
from moto import mock_aws
from botocore.exceptions import ClientError
 
 
def upsert_user_count(table_name: str, user_id: str) -> int:
    ddb = boto3.resource("dynamodb")
    table = ddb.Table(table_name)
    resp = table.update_item(
        Key={"id": user_id},
        UpdateExpression="ADD visits :one",
        ExpressionAttributeValues={":one": 1},
        ReturnValues="UPDATED_NEW",
    )
    return int(resp["Attributes"]["visits"])
 
 
@pytest.fixture
def ddb_table():
    with mock_aws():
        ddb = boto3.resource("dynamodb", region_name="us-east-1")
        ddb.create_table(
            TableName="Visits",
            KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
            AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
            BillingMode="PAY_PER_REQUEST",
        )
        yield "Visits"
 
 
def test_upsert_user_count_increments(ddb_table):
    assert upsert_user_count(ddb_table, "user-7") == 1
    assert upsert_user_count(ddb_table, "user-7") == 2
 
 
def test_upsert_user_count_missing_table_raises():
    # No fixture here - no table exists in this mocked account.
    with mock_aws():
        with pytest.raises(ClientError) as exc:
            upsert_user_count("NoSuchTable", "user-7")
        assert exc.value.response["Error"]["Code"] == "ResourceNotFoundException"

// --- TypeScript (AWS SDK v3) ---
// aws-sdk-client-mock equivalent: stub the two DynamoDB commands
// the function under test actually calls.
import {
  DynamoDBClient,
  UpdateItemCommand,
  ResourceNotFoundException,
} from "@aws-sdk/client-dynamodb";
import { mockClient } from "aws-sdk-client-mock";
 
async function upsertUserCount(ddb: DynamoDBClient, tableName: string, userId: string): Promise<number> {
  const res = await ddb.send(new UpdateItemCommand({
    TableName: tableName,
    Key: { id: { S: userId } },
    UpdateExpression: "ADD visits :one",
    ExpressionAttributeValues: { ":one": { N: "1" } },
    ReturnValues: "UPDATED_NEW",
  }));
  return Number(res.Attributes?.visits.N);
}
 
const ddbMock = mockClient(DynamoDBClient);
 
test("increments on repeated calls", async () => {
  ddbMock.on(UpdateItemCommand)
    .resolvesOnce({ Attributes: { visits: { N: "1" } } })
    .resolvesOnce({ Attributes: { visits: { N: "2" } } });
 
  const ddb = new DynamoDBClient({});
  expect(await upsertUserCount(ddb, "Visits", "user-7")).toBe(1);
  expect(await upsertUserCount(ddb, "Visits", "user-7")).toBe(2);
});
 
test("missing table rejects", async () => {
  ddbMock.on(UpdateItemCommand).rejects(
    new ResourceNotFoundException({ message: "not found", $metadata: {} }),
  );
  await expect(upsertUserCount(new DynamoDBClient({}), "NoSuchTable", "user-7"))
    .rejects.toBeInstanceOf(ResourceNotFoundException);
});

What this demonstrates:

• moto's mock_aws() context manager works as a fixture, letting you create real tables/buckets once and reuse them across tests.
• Because moto actually stores state, calling the same update twice produces genuinely incrementing values, not a canned response repeated.
• moto raises the real ClientError/ResourceNotFoundException shape for a missing table, so your error-handling code is tested against realistic errors.
• The TypeScript side stubs each call explicitly instead, since aws-sdk-client-mock has no persistent backend to model incrementing state.

Deep Dive

Why @mock_aws and Not the Old Per-Service Decorators

• moto v5 consolidated every service-specific decorator (@mock_s3, @mock_dynamodb, @mock_sqs, and so on) into one @mock_aws decorator.
• The old decorators still work in older moto versions but are deprecated; new code should use @mock_aws exclusively.
• @mock_aws mocks all services at once, which matters when your code touches more than one service in the same test.
• It can be used as a decorator, a context manager (with mock_aws():), or a pytest fixture, whichever fits your test structure.

How the Interception Works

• moto patches botocore's HTTP transport layer, so calls never leave the process.
• Each service has a simulated backend model that tracks created resources, so state (a bucket's objects, a table's items) persists for the life of the mock.
• Responses are shaped to match real AWS responses closely enough that response-parsing code behaves the same as it would against the real API.
• Because it's a simulation, not every service's every edge case and quota behavior is modeled - complex or newer services have thinner coverage than core ones like S3, DynamoDB, and SQS.

Scoping the Mock

• Decorate an individual test function to isolate state per test - the most common pattern for unit tests.
• Use the context manager form inside a fixture when you need to seed shared state once for multiple tests.
• Nesting @mock_aws inside another mocked context is unnecessary - one mock covers every service call inside its scope.

Gotchas

• Using the deprecated per-service decorators - @mock_s3 still works in some moto versions but is being phased out. Fix: use @mock_aws in all new code.
• Client created before the mock is active - a boto3.client(...) built outside the @mock_aws scope may bind to real endpoints. Fix: always construct clients inside the decorated function or context manager.
• Assuming moto covers every service feature - some advanced or newer service behaviors are only partially modeled. Fix: check moto's service coverage docs before relying on an obscure feature; fall back to LocalStack or a contract test if it's not supported.
• Forgetting a region - some services require an explicit region even under moto. Fix: pass region_name explicitly rather than relying on environment defaults in CI.
• Testing against moto's exact error messages - message text can differ slightly from real AWS. Fix: assert on the error code (Code in err.response["Error"]), never the message string.
• Real credentials still required syntactically - boto3 wants some access key/secret present even under moto. Fix: set dummy AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY env vars in your test environment; moto never validates or uses them.

Alternatives

FAQs

Related

• AWS SDK Testing Basics - the first mocked test walkthrough.
• aws-sdk-client-mock for TypeScript - the equivalent tool for SDK v3.
• LocalStack for Local AWS Emulation - when you need more than an in-process mock.
• Why AWS SDK Code Needs Its Own Testing Strategy - where moto fits in the test pyramid.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).