pytest-localstack¶
pytest-localstack is a plugin for pytest to create AWS integration tests via a Localstack Docker container. Requires Docker.
Features¶
- 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.
Example¶
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')
bucket.create()
assert len(list(s3.buckets.all())) == 1
TODO¶
- 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.
Top-Level Imports¶
The most important parts can be imported directly from pytest_localstack
.
from pytest_localstack import *
-
pytest_localstack.
session_fixture
(scope='function', services=None, autouse=False, docker_client=None, region_name='us-east-1', kinesis_error_probability=0.0, dynamodb_error_probability=0.0, container_log_level=10, localstack_verison='latest', auto_remove=True, pull_image=True, container_name=None, **kwargs)[source]¶ Create a pytest fixture that provides a LocalstackSession.
This is not a fixture! It is a factory to create them.
The fixtures that are created by this function will provide a
pytest_localstack.session.LocalstackSession
instance. This is useful for simulating multiple AWS accounts. It does not automatically redirect botocore/boto3 traffic to Localstack (although LocalstackSession has a method to do that.) The LocalstackSession instance has factories to create botocore/boto3 clients that will connect to Localstack.Parameters: - scope (str, optional) – The pytest scope which this fixture will use. Defaults to ‘function’.
- services (list|dict, optional) –
One of:
- A
list
of AWS service names to start in the Localstack container. - A
dict
of service names to the port they should run on.
Defaults to all services. Setting this can reduce container startup time and therefore test time.
- A
- autouse (bool, optional) –
- docker_client – A docker-py Client object that will be used to talk to Docker. Defaults to docker.from_env(). Pytest-localstack currently only supports connecting to localhost anyway.
- region_name (str, optional) – Region name to assume. Each Localstack container acts like a single AWS region. Defaults to ‘us-east-1’.
- kinesis_error_probability (float, optional) – Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses.
- dynamodb_error_probability (float, optional) – Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses.
- container_log_level (int, optional) – The logging level to use
for Localstack container logs. Defaults to
logging.DEBUG
. - localstack_verison (str, optional) – The version of the Localstack image to use. Defaults to latest.
- auto_remove (bool, optional) – If True, delete the Localstack container when it stops.
- pull_image (bool, optional) – If True, pull the Localstack image before running it. Default: True.
- container_name (str, optional) – The name for the Localstack container. Defaults to a randomly generated id.
- **kwargs – Additional kwargs will be passed to the LocalstackSession.
Yields: A
pytest_localstack.session.LocalstackSession
-
pytest_localstack.
patch_fixture
(scope='function', services=None, autouse=False, docker_client=None, region_name='us-east-1', kinesis_error_probability=0.0, dynamodb_error_probability=0.0, container_log_level=10, localstack_verison='latest', auto_remove=True, pull_image=True, container_name=None, **kwargs)[source]¶ Create a pytest fixture that temporarially redirects all botocore sessions and clients to a Localstack container.
This is not a fixture! It is a factory to create them.
The fixtures that are created by this function will run a Localstack container and patch botocore to direct traffic there for the duration of the tests.
Since boto3 uses botocore to send requests, boto3 will also be redirected.
Parameters: - scope (str, optional) – The pytest scope which this fixture will use. Defaults to ‘function’.
- services (list|dict, optional) –
One of
- A
list
of AWS service names to start in the Localstack container. - A
dict
of service names to the port they should run on.
Defaults to all services. Setting this can reduce container startup time and therefore test time.
- A
- autouse (bool, optional) –
- docker_client – A docker-py Client object that will be used to talk to Docker. Defaults to docker.from_env(). Pytest-localstack currently only supports connecting to localhost anyway.
- region_name (str, optional) – Region name to assume. Each Localstack container acts like a single AWS region. Defaults to ‘us-east-1’.
- kinesis_error_probability (float, optional) – Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into Kinesis API responses.
- dynamodb_error_probability (float, optional) – Decimal value between 0.0 (default) and 1.0 to randomly inject ProvisionedThroughputExceededException errors into DynamoDB API responses.
- container_log_level (int, optional) – The logging level to use
for Localstack container logs. Defaults to
logging.DEBUG
. - localstack_verison (str, optional) – The version of the Localstack image to use. Defaults to latest.
- auto_remove (bool, optional) – If True, delete the Localstack container when it stops.
- pull_image (bool, optional) – If True, pull the Localstack image before running it. Default: True
- container_name (str, optional) – The name for the Localstack container. Defaults to a randomly generated id.
- **kwargs – Additional kwargs will be passed to the LocalstackSession.
Yields: A
pytest_localstack.session.LocalstackSession