Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/modules/dynamodb.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# DynamoDB

## Install

```bash
npm install @testcontainers/dynamodb --save-dev
```

## Examples

These examples use the following libraries:

- [@aws-sdk/client-dynamodb](https://www.npmjs.com/package/@aws-sdk/client-dynamodb)

npm install @aws-sdk/client-dynamodb

Choose an image from the [container registry](https://hub.docker.com/r/amazon/dynamodb-local) and substitute `IMAGE`.

### Connect to local endpoint

<!--codeinclude-->
[](../../packages/modules/dynamodb/src/dynamodb-container.test.ts) inside_block:connectEndpoint
<!--/codeinclude-->

### Use a shared database

<!--codeinclude-->
[](../../packages/modules/dynamodb/src/dynamodb-container.test.ts) inside_block:sharedDB
<!--/codeinclude-->
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ nav:
- CosmosDB: modules/cosmosdb.md
- Couchbase: modules/couchbase.md
- CouchDB: modules/couchdb.md
- DynamoDB: modules/dynamodb.md
- Elasticsearch: modules/elasticsearch.md
- Etcd: modules/etcd.md
- GCloud: modules/gcloud.md
Expand Down
365 changes: 233 additions & 132 deletions package-lock.json

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions packages/modules/dynamodb/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
FROM amazon/dynamodb-local:3.3.2
37 changes: 37 additions & 0 deletions packages/modules/dynamodb/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
{
"name": "@testcontainers/dynamodb",
"version": "12.2.1",
"license": "MIT",
"keywords": [
"dynamodb",
"testing",
"docker",
"testcontainers"
],
"description": "DynamoDB module for Testcontainers",
"homepage": "https://github.com/testcontainers/testcontainers-node#readme",
"repository": {
"type": "git",
"url": "git+https://github.com/testcontainers/testcontainers-node.git"
},
"bugs": {
"url": "https://github.com/testcontainers/testcontainers-node/issues"
},
"main": "build/index.js",
"files": [
"build"
],
"publishConfig": {
"access": "public"
},
"scripts": {
"prepack": "shx cp ../../../README.md . && shx cp ../../../LICENSE .",
"build": "tsc --project tsconfig.build.json"
},
"dependencies": {
"testcontainers": "^12.2.1"
},
"devDependencies": {
"@aws-sdk/client-dynamodb": "^3.1166.0"
}
}
163 changes: 163 additions & 0 deletions packages/modules/dynamodb/src/dynamodb-container.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
import {
CreateTableCommand,
DynamoDBClient,
GetItemCommand,
ListTablesCommand,
PutItemCommand,
waitUntilTableExists,
} from "@aws-sdk/client-dynamodb";
import { getImage } from "../../../testcontainers/src/utils/test-helper";
import { DynamoDBContainer } from "./dynamodb-container";

const IMAGE = getImage(__dirname);

async function createTestTable(client: DynamoDBClient): Promise<{
addUser: (userId: number, name: string) => Promise<void>;
getUser: (userId: number) => Promise<string | null>;
}> {
const command = new CreateTableCommand({
TableName: "users",
BillingMode: "PAY_PER_REQUEST",
AttributeDefinitions: [
{
AttributeName: "userId",
AttributeType: "N",
},
],
KeySchema: [
{
AttributeName: "userId",
KeyType: "HASH",
},
],
});

await client.send(command);
await waitUntilTableExists({ client, maxWaitTime: 30 }, { TableName: "users" });

return {
addUser: async (userId, name) => {
const putCommand = new PutItemCommand({
TableName: "users",
Item: {
userId: { N: userId.toString() },
name: { S: name },
},
});
await client.send(putCommand);
},
getUser: async (userId) => {
const getCommand = new GetItemCommand({
TableName: "users",
Key: {
userId: { N: userId.toString() },
},
ConsistentRead: true,
});
const result = await client.send(getCommand);
return result.Item?.name?.S ?? null;
},
};
}

function createClient(endpoint: string, accessKeyId: string = "AKIAIOSFODNN7EXAMPLE"): DynamoDBClient {
const client = new DynamoDBClient({
region: "us-east-1",
credentials: {
// use any credentials
accessKeyId,
secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
endpoint,
});
return client;
}

describe("DynamoDBContainer", { timeout: 180_000 }, () => {
it("connects with endpoint", async () => {
// connectEndpoint {
await using container = await new DynamoDBContainer(IMAGE).start();
const client = new DynamoDBClient({
region: "us-east-1",
credentials: {
// use any credentials
accessKeyId: "AKIAIOSFODNN7EXAMPLE",
secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
endpoint: container.getEndpoint(),
});

const command = new ListTablesCommand({});
const result = await client.send(command);

expect(result.TableNames).toStrictEqual([]);
// }
});

it("stores data", async () => {
await using container = await new DynamoDBContainer(IMAGE).start();
const client = createClient(container.getEndpoint());

const { addUser, getUser } = await createTestTable(client);
await addUser(1, "Bob");
await addUser(2, "Alice");

const userA = await getUser(1);
const userB = await getUser(2);
expect(userA).toBe("Bob");
expect(userB).toBe("Alice");
});

it("separates data by client by default", async () => {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This tests DynamoDB Local's own behaviour. The sharedDB test already fails if -sharedDb doesn't reach the container, so this one can go.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure what you mean. I think I can either validate the withXYZ methods by checking they resulted in the expected command (similar to https://github.com/testcontainers/testcontainers-node/blob/main/packages/modules/redis/src/redis-container.test.ts#L185-L186) or by oberserving the behaviour of the container this flag is supposed to influence. I assumed the latter is preferred and then I would argue we only know withSharedDB caused the desired effect if we know it behaves differently when we do not call withSharedDB. Or am I misunderstanding?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point, it shows the sharedDB test can fail. Happy to keep it.

await using container = await new DynamoDBContainer(IMAGE).start();

// Uses dummy credentials from the documentation
const clientA = createClient(container.getEndpoint(), "AKIAIOSFODNN7EXAMPL1");
const clientB = createClient(container.getEndpoint(), "AKIAIOSFODNN7EXAMPL2");

await createTestTable(clientA);

const resultA = await clientA.send(new ListTablesCommand());
const resultB = await clientB.send(new ListTablesCommand());

// Since clientA created the table, only clientA should see it
expect(resultA.TableNames).toStrictEqual(["users"]);
expect(resultB.TableNames).toStrictEqual([]);
});

it("uses a shared table when requested", async () => {
// sharedDB {
await using container = await new DynamoDBContainer(IMAGE).withSharedDB().start();

// Both clients will see the same data eventhough the
// ACCESS_KEY_ID differ
const clientA = new DynamoDBClient({
region: "us-east-1",
endpoint: container.getEndpoint(),
credentials: {
accessKeyId: "AKIAIOSFODNN7EXAMPLE",
secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
});

const clientB = new DynamoDBClient({
region: "us-east-1",
endpoint: container.getEndpoint(),
credentials: {
accessKeyId: "AKIAIOSFODNN7EXAMPL2",
secretAccessKey: "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",
},
});
// }

await createTestTable(clientA);

const resultA = await clientA.send(new ListTablesCommand());
const resultB = await clientB.send(new ListTablesCommand());

// Eventhough clientA created the table, both should see it due to
// the shared table design
expect(resultA.TableNames).toStrictEqual(["users"]);
expect(resultB.TableNames).toStrictEqual(["users"]);
});
});
41 changes: 41 additions & 0 deletions packages/modules/dynamodb/src/dynamodb-container.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
import { AbstractStartedContainer, GenericContainer, Wait } from "testcontainers";

// https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.UsageNotes.html#DynamoDBLocal.Endpoint
const DYNAMODB_PORT = 8000;

export class DynamoDBContainer extends GenericContainer {
private sharedDB: boolean = false;

constructor(image: string) {
super(image);
this.withExposedPorts(DYNAMODB_PORT)
.withStartupTimeout(120_000)
.withWaitStrategy(Wait.forHttp("/", DYNAMODB_PORT).forStatusCode(400));
}

public withSharedDB(): this {
Comment thread
stschulte marked this conversation as resolved.
Resolved
this.sharedDB = true;
return this;
}

public override async start(): Promise<StartedDynamoDBContainer> {
this.withCommand(["-jar", "DynamoDBLocal.jar", "-inMemory", ...(this.sharedDB ? ["-sharedDb"] : [])]);
this.withEnvironment({
DDB_LOCAL_TELEMETRY: "0",
});

const started = await super.start();
return new StartedDynamoDBContainer(started);
}
}

export class StartedDynamoDBContainer extends AbstractStartedContainer {
public getPort(): number {
return this.startedTestContainer.getMappedPort(DYNAMODB_PORT);
}

public getEndpoint(): string {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

getConnectionUri() returning `http://${this.getHost()}:${this.getPort()}` would match the LocalStack module, and avoids the trailing slash new URL adds.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have strong opinions here. Changed in c320419

const url = `http://${this.getHost()}:${this.getPort()}`;
return url;
}
}
1 change: 1 addition & 0 deletions packages/modules/dynamodb/src/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
export { DynamoDBContainer, StartedDynamoDBContainer } from "./dynamodb-container";
9 changes: 9 additions & 0 deletions packages/modules/dynamodb/tsconfig.build.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"extends": "./tsconfig.json",
"exclude": ["build", "src/**/*.test.ts"],
"references": [
{
"path": "../../testcontainers"
}
]
}
16 changes: 16 additions & 0 deletions packages/modules/dynamodb/tsconfig.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
{
"extends": "../../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "build",
"paths": {
"testcontainers": ["../../testcontainers/src"]
}
},
"exclude": ["build"],
"references": [
{
"path": "../../testcontainers"
}
]
}