pytest-dynamodb

DynamoDB fixtures for pytest.

What is this?

pytest-dynamodb is a pytest plugin for tests that need a running DynamoDB instance. It provides fixtures for both a managed local process and a connection to an already running instance.

Quickstart: first test

1. Install the plugin and your test dependencies.

2. Download and unpack DynamoDB Local (see AWS docs): https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html Place extracted files in dynamodb_dir (default: /tmp/dynamodb), or choose another location and pass it via --dynamodb-dir when running tests.

3. Make sure Java is available in your environment (DynamoDB Local runs as a JAR).

4. Write a test that uses the built-in dynamodb fixture:

import uuid

def test_can_put_and_get_item(dynamodb):
    table = dynamodb.create_table(
        TableName="Test",
        KeySchema=[{"AttributeName": "id", "KeyType": "HASH"}],
        AttributeDefinitions=[{"AttributeName": "id", "AttributeType": "S"}],
        ProvisionedThroughput={"ReadCapacityUnits": 10, "WriteCapacityUnits": 10},
    )

    _id = str(uuid.uuid4())
    table.put_item(Item={"id": _id, "test_key": "test_value"})
    item = table.get_item(Key={"id": _id})

    assert item["Item"]["test_key"] == "test_value"

5. Run tests:

pytest

For a full example, see tests/test_dynamodb.py.

How to use

The plugin contains three fixtures:

• dynamodb - function-scoped DynamoDBServiceResource fixture.

• dynamodb_proc - session-scoped fixture that starts DynamoDB Local on first use and stops it at the end of the test session.

• dynamodb_noproc - session-scoped fixture that connects to an externally managed DynamoDB instance (for example, Docker).

When to use which fixture:

• Use dynamodb (default) when tests should manage a local process automatically.

• Use dynamodb_noproc when DynamoDB is already running elsewhere and lifecycle is managed outside pytest.

Simply include one of these fixtures in your test fixture list.

You can also create additional client and process fixtures:

from pytest_dynamodb import factories

dynamodb_my_proc = factories.dynamodb_proc(port=None, delay=True)
dynamodb_my = factories.dynamodb("dynamodb_my_proc")

from pytest_dynamodb import factories

dynamodb_my_noproc = factories.dynamodb_noproc(host="dynamodb", port=8088)
dynamodb_my = factories.dynamodb("dynamodb_my_noproc")

Configuration

You can define settings in three ways:

• Fixture factory argument

• Command line option

• Configuration option in pytest.ini

Precedence order:

• Fixture factory argument

• Command line option

• pytest.ini option

Example usage:

• Pass as fixture factory argument:

  from pytest_dynamodb import factories
  
  dynamodb_proc = factories.dynamodb_proc(port=8888)

• Use command line option:

  pytest tests --dynamodb-port=8888

• Set in pytest.ini:

  [pytest]
  dynamodb_port = 8888

Known issues

• Parallel runs with a fixed --dynamodb-port may fail because workers contend for the same port.

Package resources

• Source: https://github.com/dbfixtures/pytest-dynamodb

• Bug tracker: https://github.com/dbfixtures/pytest-dynamodb/issues