Skip to content
A library that allows you to easily mock out tests based on AWS infrastructure.
Branch: master
Clone or download
spulec Merge pull request #2329 from swen128/bugfix/dynamodb/update-item
Fix DynamoDB update_item to deal with list-type attributes
Latest commit d824237 Jul 21, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Update lists of implemented services and endpoints (#2258) Jun 24, 2019
moto Fixed `update_item` of DynamoDB to deal with the list type. Jul 21, 2019
other_langs Added an example of using a moto server with Scala Jul 7, 2019
scripts Fixes for get_policy and get_policy_version with AWS managed policies ( Jun 6, 2019
tests Fixed `update_item` of DynamoDB to deal with the list type. Jul 21, 2019
.bumpversion.cfg Version 1.3.4 (#1757) Aug 7, 2018
.coveragerc fix keys to use types Mar 15, 2013
.gitignore 1987 support transfer acceleration (#2018) May 25, 2019
.travis.yml Disable non-prereleases; prep for 1.3.13. Jul 15, 2019
AUTHORS.md Updates to create_subnet and describe_subnets responses (#2053) May 28, 2019
CHANGELOG.md 1.3.7 Nov 4, 2018
CODE_OF_CONDUCT.md Add docs on contributing and code of conduct. Feb 27, 2017
CONTRIBUTING.md Add getting setup to contributing. Jul 9, 2019
Dockerfile dockerfile with cryptography package Sep 27, 2017
IMPLEMENTATION_COVERAGE.md Merge pull request #2311 from caguado/fix/2310 Jul 20, 2019
ISSUE_TEMPLATE.md Add docs on contributing and code of conduct. Feb 27, 2017
LICENSE Add license. Apr 26, 2013
MANIFEST.in Implement some of cognito-idp May 7, 2018
Makefile Add getting setup to contributing. Jul 9, 2019
README.md Update supported python versions, add badages. Jul 13, 2019
requirements-dev.txt MockAWS implementation using botocore event hooks Oct 29, 2018
requirements.txt Reorganize requirements. Sep 10, 2014
setup.cfg Finalize implementation of DynamoDB Streams Nov 8, 2018
setup.py Merge pull request #2297 from yan12125/patch-2 Jul 16, 2019
tox.ini Update supported python versions, add badages. Jul 13, 2019
travis_moto_server.sh lambda + SNS enhancements (#1048) Sep 27, 2017
update_version_from_git.py Remove double-dev from release name. Jul 15, 2019
wait_for.py Bug fix for default network ACL entries (#2056) May 26, 2019

README.md

Moto - Mock AWS Services

Join the chat at https://gitter.im/awsmoto/Lobby

Build Status Coverage Status Docs PyPI PyPI - Python Version PyPI - Downloads

In a nutshell

Moto is a library that allows your tests to easily mock out AWS Services.

Imagine you have the following python code that you want to test:

import boto3

class MyModel(object):
    def __init__(self, name, value):
        self.name = name
        self.value = value

    def save(self):
        s3 = boto3.client('s3', region_name='us-east-1')
        s3.put_object(Bucket='mybucket', Key=self.name, Body=self.value)

Take a minute to think how you would have tested that in the past.

Now see how you could test it with Moto:

import boto3
from moto import mock_s3
from mymodule import MyModel


@mock_s3
def test_my_model_save():
    conn = boto3.resource('s3', region_name='us-east-1')
    # We need to create the bucket since this is all in Moto's 'virtual' AWS account
    conn.create_bucket(Bucket='mybucket')

    model_instance = MyModel('steve', 'is awesome')
    model_instance.save()

    body = conn.Object('mybucket', 'steve').get()['Body'].read().decode("utf-8")

    assert body == 'is awesome'

With the decorator wrapping the test, all the calls to s3 are automatically mocked out. The mock keeps the state of the buckets and keys.

It gets even better! Moto isn't just for Python code and it isn't just for S3. Look at the standalone server mode for more information about running Moto with other languages. Here's the status of the other AWS services implemented:

|-------------------------------------------------------------------------------------|
| Service Name              | Decorator             | Development Status              |
|-------------------------------------------------------------------------------------|
| ACM                       | @mock_acm             | all endpoints done              |
|-------------------------------------------------------------------------------------|
| API Gateway               | @mock_apigateway      | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Autoscaling               | @mock_autoscaling     | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Cloudformation            | @mock_cloudformation  | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Cloudwatch                | @mock_cloudwatch      | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| CloudwatchEvents          | @mock_events          | all endpoints done              |
|-------------------------------------------------------------------------------------|
| Cognito Identity          | @mock_cognitoidentity | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| Cognito Identity Provider | @mock_cognitoidp      | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| Config                    | @mock_config          | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| Data Pipeline             | @mock_datapipeline    | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| DynamoDB                  | @mock_dynamodb        | core endpoints done             |
| DynamoDB2                 | @mock_dynamodb2       | all endpoints + partial indexes |
|-------------------------------------------------------------------------------------|
| EC2                       | @mock_ec2             | core endpoints done             |
|     - AMI                 |                       | core endpoints done             |
|     - EBS                 |                       | core endpoints done             |
|     - Instances           |                       | all  endpoints done             |
|     - Security Groups     |                       | core endpoints done             |
|     - Tags                |                       | all  endpoints done             |
|-------------------------------------------------------------------------------------|
| ECR                       | @mock_ecr             | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| ECS                       | @mock_ecs             | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| ELB                       | @mock_elb             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| ELBv2                     | @mock_elbv2           | all endpoints done              |
|-------------------------------------------------------------------------------------|
| EMR                       | @mock_emr             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Glacier                   | @mock_glacier         | core endpoints done             |
|-------------------------------------------------------------------------------------|
| IAM                       | @mock_iam             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| IoT                       | @mock_iot             | core endpoints done             |
|                           | @mock_iotdata         | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Kinesis                   | @mock_kinesis         | core endpoints done             |
|-------------------------------------------------------------------------------------|
| KMS                       | @mock_kms             | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| Lambda                    | @mock_lambda          | basic endpoints done, requires  |
|                           |                       | docker                          |
|-------------------------------------------------------------------------------------|
| Logs                      | @mock_logs            | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| Organizations             | @mock_organizations   | some core endpoints done        |
|-------------------------------------------------------------------------------------|
| Polly                     | @mock_polly           | all endpoints done              |
|-------------------------------------------------------------------------------------|
| RDS                       | @mock_rds             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| RDS2                      | @mock_rds2            | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Redshift                  | @mock_redshift        | core endpoints done             |
|-------------------------------------------------------------------------------------|
| Route53                   | @mock_route53         | core endpoints done             |
|-------------------------------------------------------------------------------------|
| S3                        | @mock_s3              | core endpoints done             |
|-------------------------------------------------------------------------------------|
| SecretsManager            | @mock_secretsmanager  | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| SES                       | @mock_ses             | all endpoints done              |
|-------------------------------------------------------------------------------------|
| SNS                       | @mock_sns             | all endpoints done              |
|-------------------------------------------------------------------------------------|
| SQS                       | @mock_sqs             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| SSM                       | @mock_ssm             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| STS                       | @mock_sts             | core endpoints done             |
|-------------------------------------------------------------------------------------|
| SWF                       | @mock_swf             | basic endpoints done            |
|-------------------------------------------------------------------------------------|
| X-Ray                     | @mock_xray            | all endpoints done              |
|-------------------------------------------------------------------------------------|

For a full list of endpoint implementation coverage

Another Example

Imagine you have a function that you use to launch new ec2 instances:

import boto3


def add_servers(ami_id, count):
    client = boto3.client('ec2', region_name='us-west-1')
    client.run_instances(ImageId=ami_id, MinCount=count, MaxCount=count)

To test it:

from . import add_servers
from moto import mock_ec2

@mock_ec2
def test_add_servers():
    add_servers('ami-1234abcd', 2)

    client = boto3.client('ec2', region_name='us-west-1')
    instances = client.describe_instances()['Reservations'][0]['Instances']
    assert len(instances) == 2
    instance1 = instances[0]
    assert instance1['ImageId'] == 'ami-1234abcd'

Using moto 1.0.X with boto2

moto 1.0.X mock decorators are defined for boto3 and do not work with boto2. Use the @mock_AWSSVC_deprecated to work with boto2.

Using moto with boto2

from moto import mock_ec2_deprecated
import boto

@mock_ec2_deprecated
def test_something_with_ec2():
    ec2_conn = boto.ec2.connect_to_region('us-east-1')
    ec2_conn.get_only_instances(instance_ids='i-123456')

When using both boto2 and boto3, one can do this to avoid confusion:

from moto import mock_ec2_deprecated as mock_ec2_b2
from moto import mock_ec2

Usage

All of the services can be used as a decorator, context manager, or in a raw form.

Decorator

@mock_s3
def test_my_model_save():
    # Create Bucket so that test can run
    conn = boto3.resource('s3', region_name='us-east-1')
    conn.create_bucket(Bucket='mybucket')
    model_instance = MyModel('steve', 'is awesome')
    model_instance.save()
    body = conn.Object('mybucket', 'steve').get()['Body'].read().decode()

    assert body == 'is awesome'

Context Manager

def test_my_model_save():
    with mock_s3():
        conn = boto3.resource('s3', region_name='us-east-1')
        conn.create_bucket(Bucket='mybucket')
        model_instance = MyModel('steve', 'is awesome')
        model_instance.save()
        body = conn.Object('mybucket', 'steve').get()['Body'].read().decode()

        assert body == 'is awesome'

Raw use

def test_my_model_save():
    mock = mock_s3()
    mock.start()

    conn = boto3.resource('s3', region_name='us-east-1')
    conn.create_bucket(Bucket='mybucket')

    model_instance = MyModel('steve', 'is awesome')
    model_instance.save()

    assert conn.Object('mybucket', 'steve').get()['Body'].read().decode() == 'is awesome'

    mock.stop()

Stand-alone Server Mode

Moto also has a stand-alone server mode. This allows you to utilize the backend structure of Moto even if you don't use Python.

It uses flask, which isn't a default dependency. You can install the server 'extra' package with:

pip install "moto[server]"

You can then start it running a service:

$ moto_server ec2
 * Running on http://127.0.0.1:5000/

You can also pass the port:

$ moto_server ec2 -p3000
 * Running on http://127.0.0.1:3000/

If you want to be able to use the server externally you can pass an IP address to bind to as a hostname or allow any of your external interfaces with 0.0.0.0:

$ moto_server ec2 -H 0.0.0.0
 * Running on http://0.0.0.0:5000/

Please be aware this might allow other network users to access your server.

Then go to localhost to see a list of running instances (it will be empty since you haven't added any yet).

If you want to use boto with this (using the simpler decorators above instead is strongly encouraged), the easiest way is to create a boto config file (~/.boto) with the following values:

[Boto]
is_secure = False
https_validate_certificates = False
proxy_port = 5000
proxy = 127.0.0.1

If you want to use boto3 with this, you can pass an endpoint_url to the resource

boto3.resource(
    service_name='s3',
    region_name='us-west-1',
    endpoint_url='http://localhost:5000',
)

Install

$ pip install moto

Releases

Releases are done from travisci. Fairly closely following this: https://docs.travis-ci.com/user/deployment/pypi/

  • Commits to master branch do a dev deploy to pypi.
  • Commits to a tag do a real deploy to pypi.
You can’t perform that action at this time.