Moto

Warnings

• breaking Moto v5.x introduced a significant breaking change: all individual service decorators (e.g., `@mock_s3`, `@mock_dynamodb`, `@mock_sqs`) have been removed and replaced by a single, unified `@mock_aws` decorator.
  Fix: Replace specific decorators like `@mock_s3` with `@mock_aws`. If you need to specify specific services for the mock, pass them as arguments to `@mock_aws` (though often not necessary for basic usage, it mocks all by default). For example: `@mock_aws(config={'s3': {'use_docker': False}})`.
• gotcha Boto3 clients/resources must be created *after* the `moto` mock has been established. If a Boto3 client is initialized globally (e.g., at the module level) before the `@mock_aws` decorator or context manager is activated, `moto` will not intercept those calls, and they may hit real AWS.
  Fix: Create `boto3` clients/resources inside the `@mock_aws` decorated function, within the `with mock_aws():` block, or within a `setUp` method of a `unittest.TestCase` where the class is decorated. For Pytest, ensure fixtures that create clients are decorated or called within the mock's scope. Using local imports for modules that create `boto3` clients can also help.
• gotcha Always specify `region_name` explicitly when creating `boto3` clients and resources (e.g., `boto3.client('s3', region_name='us-east-1')`). Moto can sometimes exhibit inconsistent behavior or default to unexpected regions if `region_name` is omitted, potentially leading to hard-to-debug test failures.
  Fix: Include `region_name='your-desired-region'` in all `boto3.client()` and `boto3.resource()` calls within your mocked tests.
• breaking In Moto v3.x, the behavior of class decorators changed: the mock state is now reset before *every* test method within a decorated class. Previously, the state was global and shared across methods in the same class.
  Fix: If your tests relied on shared state between methods in a class, refactor them to ensure each test method sets up its required state independently, or use alternative mechanisms (e.g., pytest fixtures with appropriate scope) to manage state if shared setup is truly necessary.
• gotcha For Pytest users, ensure that any `boto3` client-creating fixtures are correctly integrated with Moto's mocking. If a fixture creates a client before `mock_aws` is active, it won't be mocked.
  Fix: Decorate your pytest fixtures with `@mock_aws` if they provision AWS clients, or use the `mock_aws` context manager within the fixture's setup phase. Example: `@pytest.fixture @mock_aws def s3_client(): return boto3.client('s3', region_name='us-east-1')`.
• gotcha Moto intercepts HTTP requests and requires dummy AWS credentials to be set (either via environment variables or `~/.aws/credentials`). Without them, `botocore` might attempt to resolve actual credentials or hit real AWS endpoints, leading to errors or unintended side effects.
  Fix: Before running tests, set environment variables like `AWS_ACCESS_KEY_ID=testing`, `AWS_SECRET_ACCESS_KEY=testing`, `AWS_SECURITY_TOKEN=testing`, `AWS_SESSION_TOKEN=testing`, and `AWS_DEFAULT_REGION=us-east-1`. These can be exported in your test runner or set programmatically.

Install

• pip install moto[all] Install with all service mocks
• pip install 'moto[s3,dynamodb]' Install specific service mocks (e.g., S3, DynamoDB)

Imports

• mock_aws

  from moto import mock_aws

  As of Moto v5.x, service-specific decorators like `mock_s3` or `mock_dynamodb` have been replaced by the single, unified `mock_aws` decorator.

Quickstart

This quickstart demonstrates how to mock an S3 service using the `@mock_aws` decorator. It creates a Boto3 S3 client within the mocked context, creates a bucket, and then verifies its existence, all without interacting with actual AWS infrastructure. Dummy AWS credentials are set to prevent botocore from attempting real AWS calls.

import boto3
from moto import mock_aws
import os

@mock_aws
def test_s3_bucket_creation():
    # Ensure dummy AWS credentials are set for botocore to not attempt real calls
    os.environ['AWS_ACCESS_KEY_ID'] = 'testing'
    os.environ['AWS_SECRET_ACCESS_KEY'] = 'testing'
    os.environ['AWS_SECURITY_TOKEN'] = 'testing'
    os.environ['AWS_SESSION_TOKEN'] = 'testing'
    os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'

    s3_client = boto3.client('s3', region_name='us-east-1')
    bucket_name = 'my-test-bucket-123'
    
    # Create a bucket in the mocked AWS environment
    s3_client.create_bucket(Bucket=bucket_name)
    
    # List buckets and verify the new bucket exists
    response = s3_client.list_buckets()
    buckets = [b['Name'] for b in response['Buckets']]
    
    assert bucket_name in buckets
    print(f"Successfully created and verified bucket: {bucket_name}")

if __name__ == '__main__':
    test_s3_bucket_creation()