Runtime Guides

Package-source copy · Generated into the site so runtime docs are searchable and linkable.

Testing Guide (Python)

This guide documents how to test Python services that use tabletheory_py.

Use strict fakes from tabletheory_py.mocks to avoid real AWS calls and to keep tests deterministic.

from tabletheory_py.mocks import ANY, FakeDynamoDBClient, FakeKmsClient

fake_ddb = FakeDynamoDBClient()
fake_kms = FakeKmsClient(plaintext_key=b"\x00" * 32, ciphertext_blob=b"edk")

fake_ddb.expect("put_item", {"TableName": "notes", "Item": {"PK": ANY, "SK": ANY, "secret": ANY}})

✅ CORRECT: deterministic encryption inputs

For tests involving encryption, inject deterministic rand_bytes:

table = Table(model, client=fake_ddb, kms_key_arn="arn:aws:kms:...", kms_client=fake_kms, rand_bytes=lambda n: b"\x01" * n)

Stateful fake for behavioral unit tests

Use StatefulDynamoDBClient from tabletheory_py or tabletheory_py.testkit when a test should exercise real TableTheory Python writes, queries, updates, batches, or transactions without scripting each low-level request:

from tabletheory_py import StatefulDynamoDBClient, Table

fake_ddb = StatefulDynamoDBClient()
table = Table(model, client=fake_ddb, now=lambda: "2026-07-04T00:00:00.000000000Z")

table.put(note)
page = table.query("USER#1")

assert len(page.items) == 1
assert fake_ddb.items("notes")[0]["ttl"] == {"N": "1700000000"}

Choose the test double by intent:

  • FakeDynamoDBClient: ordered expectation mock for exact request-shape assertions and error injection.
  • StatefulDynamoDBClient: deterministic in-memory TableTheory behavior for write-then-query consumer tests. It honors keys, basic expressions, optimistic-lock conditions, TTL attribute persistence, batches, and transactions, but it is not a general DynamoDB emulator.
  • moto: useful only when a project already standardizes on moto-specific AWS emulation; it is outside TableTheory’s contract gate.
  • DynamoDB Local: authoritative choice for AWS-exact expression, index, pagination, throughput, and integration behavior.

Integration testing (DynamoDB Local)

Use DynamoDB Local to validate real DynamoDB constraints (pagination, conditional writes, batch limits).

From repo root:

make docker-up
uv --directory py run pytest -q tests/integration

Environment variables (typical for local):

  • DYNAMODB_ENDPOINT (default http://localhost:8000)
  • AWS_REGION (default us-east-1)
  • AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (use dummy)