dynamotest

README

dynamotest

Leverage the power of DynamoDB Local with ory/dockertest to create your DynamoDB test cases effortlessly.

🌄 What is dynamotest?

dynamotest is a package designed to help set up a DynamoDB Local Docker instance on your machine as part of Go test code. It uses ory/dockertest to start the DynamoDB Local instance in your Go test code, and is configured so that each call to dynamotest.NewDynamoDB(t) will create a dedicated instance, allowing parallel testing on multiple Docker instances. The function returns a new DynamoDB client which is already connected to the instance, enabling you to start using the client immediately. Additionally, it provides a clean-up function to ensure that the Docker instance gets deleted if clean-up is preferred. If you do not call the clean-up function, the instance will keep running, which may be useful for debugging and investigation.

It is also worth noting that this package uses only the v2 version of the AWS SDK.

NOTE: It is a prerequisite that you are able to start up a Docker container for DynamoDB Local.

🚀 Example

Here's a simple example to get you started with dynamotest.

Step 1: Define Table Schema

package usage_example

import (
	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb"
	"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)

func getSchema() dynamodb.CreateTableInput {
	return dynamodb.CreateTableInput{
		AttributeDefinitions: []types.AttributeDefinition{
			{
				AttributeName: aws.String("pk"),
				AttributeType: types.ScalarAttributeTypeS,
			},
			{
				AttributeName: aws.String("sk"),
				AttributeType: types.ScalarAttributeTypeS,
			},
		},
		KeySchema: []types.KeySchemaElement{
			{
				AttributeName: aws.String("pk"),
				KeyType:       types.KeyTypeHash,
			},
			{
				AttributeName: aws.String("sk"),
				KeyType:       types.KeyTypeRange,
			},
		},
	}
}

Step 2: Write Test Code

package usage_example

import (
	"context"
	"os"
	"testing"

	"github.com/stretchr/testify/assert"
	"github.com/rozen03/dynamotest"
)

func TestMain(m *testing.M) {
	code := dynamotest.RunTestAndCleanup(m)
	os.Exit(code)
}

func TestRepositoryExample_Create(t *testing.T) {
	client := dynamotest.DynamoDBClient()
	table := client.CreateTestingTable(t, "test", getSchema())

	repo := RepositoryExample{client: client, table: &table}
	model := ExampleModel{
		ID:    "1",
		SK:    "1",
		Value: "example",
	}

	err := repo.Create(context.Background(), model)
	assert.NoError(t, err)
}

Refer to usage_example/example_test.go for the complete code and more detailed examples.

Documentation

Index

• func RunTestAndCleanup(m *testing.M) int
• type Client
  • func DynamoDBClient() Client
  • func NewDynamoDB() (Client, func())
  • func (c Client) CreateTestingTable(t *testing.T, tablePrefix string, schema dynamodb.CreateTableInput, ...) string

Functions

func RunTestAndCleanup

func RunTestAndCleanup(m *testing.M) int

Types

type Client

type Client struct {
	*dynamodb.Client
	ContainerID string
}

var GlobalClient *Client

func DynamoDBClient

func DynamoDBClient() Client

func NewDynamoDB

func NewDynamoDB() (Client, func())

NewDynamoDB creates a Docker container with DynamoDB Local, and returns the connected DynamoDB client. Clean up function is returned as well to ensure container gets removed after test is complete.

func (Client) CreateTestingTable

func (c Client) CreateTestingTable(t *testing.T, tablePrefix string, schema dynamodb.CreateTableInput, initialData ...any) string

CreateTestingTable creates a table with the given schema and initial data and returns the table name

** ** tablePrefix is the prefix of the table name, we need this just in case we want to create multiple tables ** with the same schema and different data, so we can differentiate between them, ** and also, to check what happened to the table if not purged ** ** schema is the schema of the table except the table name which is generated by the function using the tablePrefix and the billing mode is set to PayPerRequest ** ** initialData is a type alias for any type of data that can be used to populate the table *