PyPI Travis-CI Codecov

pytest-localstack is a plugin for pytest to create AWS integration tests via a Localstack Docker container.

Read The Docs


  • pytest >= 3.3.0
  • Docker


  • Create pytest fixtures that start and stop a Localstack container.
  • Temporarily patch botocore to redirect botocore/boto3 API calls to Localstack container.
  • Plugin system to easily extend supports to other AWS client libraries such as aiobotocore.


import boto3
import pytest_localstack

localstack = pytest_localstack.patch_fixture(
    services=["s3"],  # Limit to the AWS services you need.
    scope='module',  # Use the same Localstack container for all tests in this module.
    autouse=True,  # Automatically use this fixture in tests.

def test_s3_bucket_creation():
    s3 = boto3.resource('s3')  # Botocore/boto3 will be patched to use Localstack
    assert len(list(s3.buckets.all())) == 0
    bucket = s3.Bucket('foobar')
    assert len(list(s3.buckets.all())) == 1


Install with pipenv:

$ pipenv install pytest-localstack

(You have pipenv, right?)


  • More detailed docs.
  • Break Docker container running out of LocalstackSession.
  • Make botocore patching more comprehensible.
  • Add common test resource fixture factories i.e. S3 buckets, SQS queues, SNS topics, etc.
  • Test this works for non-localhost Docker containers.
  • Add other client libraries such as aiobotocore.

Change Log

0.1.3 (2018-07-17)

  • Fix for botocore >= 1.10.58.

0.1.2 (2018-06-22)

  • Broke out LocalstackSession into RunningSession which doesn’t start localstack itself.

0.1.1 (2018-04-23)

  • Fixed bug where patched botocore clients wouldn’t populated the _exceptions attribute.

0.1.0 (2018-03-13)

  • Initial release

Indices and tables