AWS SDK Testing Best Practices

Q: Why does moto use @mock_aws instead of per-service decorators now?

moto v5 unified every service-specific decorator into one @mock_aws decorator that covers all services at once; the old per-service decorators still work but are deprecated.

Q: What's the most common aws-sdk-client-mock mistake?

Forgetting to call .reset() between tests. Because the mock is module-scoped, a stub or call history from one test can silently leak into and affect a later one.

Q: What should I assert on besides the mocked return value?

The request your code actually sent. Matchers like toHaveReceivedCommandWith (aws-sdk-client-mock) or reading seeded state back (moto) catch bugs where parameters are wrong even though the mocked call "succeeds."

A testing pyramid for AWS SDK-calling code, in both Python and TypeScript.

Walk the list once now, then use it as a review checklist whenever you add tests around new SDK-calling code.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly bottom-to-top of the pyramid: unit mocks first, then integration, then real-account contract tests, then cross-cutting hygiene.
Check the boxes against your own test suite as a quick audit.
Revisit whenever you add a new service integration or a new kind of SDK-calling code.

A - Unit Tests: In-Process Mocks First

Default to in-process mocks for unit tests. Use @mock_aws (moto) in Python and mockClient(...) (aws-sdk-client-mock) in TypeScript; both run in milliseconds with no network access.
Never make a real network call in a unit test. A test that hits real AWS is an integration or contract test, not a unit test - name and place it accordingly.
Use the current moto API. @mock_aws is the unified decorator in moto v5; the older per-service decorators (@mock_s3, @mock_dynamodb) are deprecated.
Test your function, not the mock. Wrap the SDK call in your own function and assert on that function's behavior, so the test still means something if the mocking library changes.
Cover the error path, not just the happy path. Simulate a ClientError/typed SDK exception and assert your code handles it - this is usually where real bugs hide.

Isolate at the client boundary and keep unit tests fast.

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

// --- TypeScript (AWS SDK v3) ---
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";
import { mockClient } from "aws-sdk-client-mock";
 
const s3Mock = mockClient(S3Client);
 
test("creates a bucket", async () => {
  s3Mock.on(CreateBucketCommand).resolves({});
  await new S3Client({}).send(new CreateBucketCommand({ Bucket: "my-bucket" }));
  expect(s3Mock).toHaveReceivedCommandWith(CreateBucketCommand, { Bucket: "my-bucket" });
});

B - Test Hygiene

Reset mocks between tests. aws-sdk-client-mock instances persist stubs at module scope - call .reset() in beforeEach; moto isolates state per @mock_aws-decorated function automatically.
Assert on the request, not only the response. Use toHaveReceivedCommandWith (aws-sdk-client-mock) or read seeded/mutated state back (moto) to catch bugs where the wrong parameters are sent.
Branch assertions on error codes, never messages. Check err.response["Error"]["Code"] (boto3) or instanceof SpecificException (SDK v3); message text can change without notice.
Inject the client rather than constructing it inline. Passing the client into the function under test makes substituting a mock or fake trivial and keeps the function testable in isolation.
Set dummy credentials in test environments. boto3 wants something present in the credential chain even under moto; use fake values, never real keys, in CI.

C - Integration Tests: LocalStack

Reach for LocalStack only when a mock structurally can't help. Cross-service triggers (S3 event to Lambda, DynamoDB stream to consumer) are the clearest case.
Keep LocalStack tests to a smaller, separate suite. They're slower to start and run than in-process mocks - don't let them become the default for everyday unit tests.
Use path-style S3 addressing against LocalStack. Set forcePathStyle: true (SDK v3) or the boto3 equivalent; virtual-hosted-style URLs need real DNS LocalStack doesn't provide.
Never hardcode the LocalStack endpoint into app code. Set it only via test/CI environment configuration so production traffic can never accidentally target a local container.
Check service coverage before relying on an obscure feature. The free tier covers core services well; some newer or specialized behaviors need LocalStack Pro or aren't modeled at all.

D - Contract Tests: Real AWS in CI

Keep the contract suite small and deliberate. It exists to catch real IAM/quota edges and service drift mocks can't - not to duplicate your whole test suite.
Run on a schedule or as a release gate, not per-commit. Real AWS latency and occasional transient errors make per-push runs slow and flaky for reasons unrelated to your code.
Use a dedicated sandbox account with its own scoped credentials. Never reuse production credentials or a shared deploy pipeline's secrets for contract tests.
Tag every resource you create and always clean it up. Tear down in a finally/fixture-teardown/afterAll, even on failure, so nothing leaks into a growing, invisible cost.
Isolate contract tests into their own CI job. A sandbox account outage should never block the fast unit-test feedback loop developers rely on for every push.

E - Overall Shape

Weight your suite like a pyramid. Hundreds of fast in-process-mocked unit tests, dozens of LocalStack integration tests, a handful of scheduled contract tests.
Pick the cheapest tool that still catches the bug you're worried about. Escalate up the pyramid only when a lower layer genuinely can't verify the behavior.
Treat test speed as a feature. A slow suite gets run less often; keeping unit tests fast and mock-based is what makes running tests on every save realistic.
Revisit the pyramid shape as the codebase grows. A creeping number of LocalStack or contract tests where a mock would do is a sign to push tests back down a layer.
Document why a test lives at its layer. A one-line comment ("needs real IAM enforcement") on a contract or LocalStack test saves the next person from "simplifying" it into a mock that misses the point.

FAQs

What's the single most important rule here?

Default to fast, in-process mocks for the vast majority of tests, and only escalate to LocalStack or real AWS when the specific behavior genuinely requires it.

Why does moto use @mock_aws instead of per-service decorators now?

moto v5 unified every service-specific decorator into one @mock_aws decorator that covers all services at once; the old per-service decorators still work but are deprecated.

How many contract tests against real AWS should I have?

A handful, focused specifically on things mocks and LocalStack can't verify - real IAM permission edges and genuine service quirks - not a re-run of your whole suite.

What's the most common aws-sdk-client-mock mistake?

Forgetting to call .reset() between tests. Because the mock is module-scoped, a stub or call history from one test can silently leak into and affect a later one.

When is LocalStack worth the extra setup?

When you need to verify cross-service behavior, like an S3 event actually triggering a downstream consumer, that an in-process mock has no way to simulate.

Should contract tests run on every pull request?

Generally no. Run them on a schedule or as a pre-release gate so real AWS latency and rare transient errors don't slow down or destabilize the everyday CI feedback loop.

What should I assert on besides the mocked return value?

The request your code actually sent. Matchers like toHaveReceivedCommandWith (aws-sdk-client-mock) or reading seeded state back (moto) catch bugs where parameters are wrong even though the mocked call "succeeds."

Is it ever fine to skip contract tests entirely?

For small projects with simple, well-documented AWS usage, maybe. But any code relying on specific IAM boundaries or quota behavior benefits from at least a small, scheduled contract suite.

Why AWS SDK Code Needs Its Own Testing Strategy - the mental model behind this pyramid.
AWS SDK Testing Basics - the beginner walkthrough behind group A.
moto for Python: Mocking boto3 in Tests - group A in depth for Python.
aws-sdk-client-mock for TypeScript - group A/B in depth for TypeScript.
LocalStack for Local AWS Emulation - group C in depth.
Contract Tests Against Real AWS in CI - group D in depth.

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

AWS SDK Testing Best Practices

A testing pyramid for AWS SDK-calling code, in both Python and TypeScript.

Walk the list once now, then use it as a review checklist whenever you add tests around new SDK-calling code.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly bottom-to-top of the pyramid: unit mocks first, then integration, then real-account contract tests, then cross-cutting hygiene.
Check the boxes against your own test suite as a quick audit.
Revisit whenever you add a new service integration or a new kind of SDK-calling code.

A - Unit Tests: In-Process Mocks First

Default to in-process mocks for unit tests. Use @mock_aws (moto) in Python and mockClient(...) (aws-sdk-client-mock) in TypeScript; both run in milliseconds with no network access.
Never make a real network call in a unit test. A test that hits real AWS is an integration or contract test, not a unit test - name and place it accordingly.
Use the current moto API. @mock_aws is the unified decorator in moto v5; the older per-service decorators (@mock_s3, @mock_dynamodb) are deprecated.
Test your function, not the mock. Wrap the SDK call in your own function and assert on that function's behavior, so the test still means something if the mocking library changes.
Cover the error path, not just the happy path. Simulate a ClientError/typed SDK exception and assert your code handles it - this is usually where real bugs hide.

Isolate at the client boundary and keep unit tests fast.

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

// --- TypeScript (AWS SDK v3) ---
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";
import { mockClient } from "aws-sdk-client-mock";
 
const s3Mock = mockClient(S3Client);
 
test("creates a bucket", async () => {
  s3Mock.on(CreateBucketCommand).resolves({});
  await new S3Client({}).send(new CreateBucketCommand({ Bucket: "my-bucket" }));
  expect(s3Mock).toHaveReceivedCommandWith(CreateBucketCommand, { Bucket: "my-bucket" });
});

B - Test Hygiene

Reset mocks between tests. aws-sdk-client-mock instances persist stubs at module scope - call .reset() in beforeEach; moto isolates state per @mock_aws-decorated function automatically.
Assert on the request, not only the response. Use toHaveReceivedCommandWith (aws-sdk-client-mock) or read seeded/mutated state back (moto) to catch bugs where the wrong parameters are sent.
Branch assertions on error codes, never messages. Check err.response["Error"]["Code"] (boto3) or instanceof SpecificException (SDK v3); message text can change without notice.
Inject the client rather than constructing it inline. Passing the client into the function under test makes substituting a mock or fake trivial and keeps the function testable in isolation.
Set dummy credentials in test environments. boto3 wants something present in the credential chain even under moto; use fake values, never real keys, in CI.

C - Integration Tests: LocalStack

Reach for LocalStack only when a mock structurally can't help. Cross-service triggers (S3 event to Lambda, DynamoDB stream to consumer) are the clearest case.
Keep LocalStack tests to a smaller, separate suite. They're slower to start and run than in-process mocks - don't let them become the default for everyday unit tests.
Use path-style S3 addressing against LocalStack. Set forcePathStyle: true (SDK v3) or the boto3 equivalent; virtual-hosted-style URLs need real DNS LocalStack doesn't provide.
Never hardcode the LocalStack endpoint into app code. Set it only via test/CI environment configuration so production traffic can never accidentally target a local container.
Check service coverage before relying on an obscure feature. The free tier covers core services well; some newer or specialized behaviors need LocalStack Pro or aren't modeled at all.

D - Contract Tests: Real AWS in CI

Keep the contract suite small and deliberate. It exists to catch real IAM/quota edges and service drift mocks can't - not to duplicate your whole test suite.
Run on a schedule or as a release gate, not per-commit. Real AWS latency and occasional transient errors make per-push runs slow and flaky for reasons unrelated to your code.
Use a dedicated sandbox account with its own scoped credentials. Never reuse production credentials or a shared deploy pipeline's secrets for contract tests.
Tag every resource you create and always clean it up. Tear down in a finally/fixture-teardown/afterAll, even on failure, so nothing leaks into a growing, invisible cost.
Isolate contract tests into their own CI job. A sandbox account outage should never block the fast unit-test feedback loop developers rely on for every push.

E - Overall Shape

Weight your suite like a pyramid. Hundreds of fast in-process-mocked unit tests, dozens of LocalStack integration tests, a handful of scheduled contract tests.
Pick the cheapest tool that still catches the bug you're worried about. Escalate up the pyramid only when a lower layer genuinely can't verify the behavior.
Treat test speed as a feature. A slow suite gets run less often; keeping unit tests fast and mock-based is what makes running tests on every save realistic.
Revisit the pyramid shape as the codebase grows. A creeping number of LocalStack or contract tests where a mock would do is a sign to push tests back down a layer.
Document why a test lives at its layer. A one-line comment ("needs real IAM enforcement") on a contract or LocalStack test saves the next person from "simplifying" it into a mock that misses the point.

FAQs

What's the single most important rule here?

Default to fast, in-process mocks for the vast majority of tests, and only escalate to LocalStack or real AWS when the specific behavior genuinely requires it.

Why does moto use @mock_aws instead of per-service decorators now?

moto v5 unified every service-specific decorator into one @mock_aws decorator that covers all services at once; the old per-service decorators still work but are deprecated.

How many contract tests against real AWS should I have?

A handful, focused specifically on things mocks and LocalStack can't verify - real IAM permission edges and genuine service quirks - not a re-run of your whole suite.

What's the most common aws-sdk-client-mock mistake?

Forgetting to call .reset() between tests. Because the mock is module-scoped, a stub or call history from one test can silently leak into and affect a later one.

When is LocalStack worth the extra setup?

When you need to verify cross-service behavior, like an S3 event actually triggering a downstream consumer, that an in-process mock has no way to simulate.

Should contract tests run on every pull request?

Generally no. Run them on a schedule or as a pre-release gate so real AWS latency and rare transient errors don't slow down or destabilize the everyday CI feedback loop.

What should I assert on besides the mocked return value?

Is it ever fine to skip contract tests entirely?

For small projects with simple, well-documented AWS usage, maybe. But any code relying on specific IAM boundaries or quota behavior benefits from at least a small, scheduled contract suite.

Why AWS SDK Code Needs Its Own Testing Strategy - the mental model behind this pyramid.
AWS SDK Testing Basics - the beginner walkthrough behind group A.
moto for Python: Mocking boto3 in Tests - group A in depth for Python.
aws-sdk-client-mock for TypeScript - group A/B in depth for TypeScript.
LocalStack for Local AWS Emulation - group C in depth.
Contract Tests Against Real AWS in CI - group D in depth.

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

AWS SDK Testing Best Practices

Buscar na documentação

AWS SDK Testing Best Practices