Testing

This guide covers how to test effect-dynamodb entities using Effect’s service-based architecture. You will learn how to mock the DynamoDB client, verify CRUD operations, assert on error paths, and test queries.

Domain Models and Entities

Define your models and entities as usual. These are the same models you use in production code:

1
class Employee extends Schema.Class<Employee>("Employee")({
2
  employeeId: Schema.String,
3
  email: Schema.String,
4
  displayName: Schema.NonEmptyString,
5
  department: Schema.String,
6
  createdBy: Schema.String,
7
}) {}
8

9
const EmployeeModel = DynamoModel.configure(Employee, {
10
  createdBy: { immutable: true },
11
})
12

13
class Task extends Schema.Class<Task>("Task")({
14
  taskId: Schema.String,
15
  projectId: Schema.String,
16
  title: Schema.NonEmptyString,
17
  status: Schema.Literals(["active", "completed", "archived"]),
18
  assignee: Schema.String,
19
}) {}

1
const AppSchema = DynamoSchema.make({ name: "myapp", version: 1 })
2

3
const EmployeeEntity = Entity.make({
4
  model: EmployeeModel,
5
  entityType: "Employee",
6
  primaryKey: {
7
    pk: { field: "pk", composite: ["employeeId"] },
8
    sk: { field: "sk", composite: [] },
9
  },
10
  indexes: {
11
    byEmail: {
12
      name: "gsi1",
13
      pk: { field: "gsi1pk", composite: ["email"] },
14
      sk: { field: "gsi1sk", composite: [] },
15
    },
16
  },
17
  unique: { email: ["email"] },
18
  timestamps: true,
19
  versioned: true,
20
})
21

22
const TaskEntity = Entity.make({
23
  model: Task,
24
  entityType: "Task",
25
  primaryKey: {
26
    pk: { field: "pk", composite: ["taskId"] },
27
    sk: { field: "sk", composite: [] },
28
  },
29
  indexes: {
30
    byProject: {
31
      name: "gsi1",
32
      pk: { field: "gsi1pk", composite: ["projectId"] },
33
      sk: { field: "gsi1sk", composite: ["status"] },
34
      type: "clustered",
35
    },
36
  },
37
  timestamps: true,
38
})
39

40
const MainTable = Table.make({
41
  schema: AppSchema,
42
  entities: { EmployeeEntity, TaskEntity },
43
})

Set Up a Mock DynamoDB Client

effect-dynamodb uses DynamoClient as an Effect Service (Context.Service). In tests, provide a mock implementation via Layer.succeed. Each method receives the raw AWS SDK input and returns an Effect:

1
// Track calls for assertions
2
let putItemCalls: Array<unknown> = []
3
let getItemCalls: Array<unknown> = []
4
let queryCalls: Array<unknown> = []
5
let transactWriteItemsCalls: Array<unknown> = []
6

7
// Configurable mock responses
8
let putItemResponse: Effect.Effect<unknown, DynamoError> = Effect.succeed({})
9
let getItemResponse: Effect.Effect<unknown, DynamoError> = Effect.succeed({})
10
let queryResponse: Effect.Effect<unknown, DynamoError> = Effect.succeed({})
11
let transactWriteItemsResponse: Effect.Effect<unknown, DynamoError> = Effect.succeed({})
12

13
const resetMocks = () => {
14
  putItemCalls = []
15
  getItemCalls = []
16
  queryCalls = []
17
  transactWriteItemsCalls = []
18
  putItemResponse = Effect.succeed({})
19
  getItemResponse = Effect.succeed({})
20
  queryResponse = Effect.succeed({})
21
  transactWriteItemsResponse = Effect.succeed({})
22
}
23

24
const MockDynamoClient = Layer.succeed(DynamoClient, {
25
  putItem: (input) => {
26
    putItemCalls.push(input)
27
    return putItemResponse as any
28
  },
29
  getItem: (input) => {
30
    getItemCalls.push(input)
31
    return getItemResponse as any
32
  },
33
  query: (input) => {
34
    queryCalls.push(input)
35
    return queryResponse as any
36
  },
37
  updateItem: () => Effect.die("not used"),
38
  deleteItem: () => Effect.die("not used"),
39
  transactWriteItems: (input) => {
40
    transactWriteItemsCalls.push(input)
41
    return transactWriteItemsResponse as any
42
  },
43
  batchGetItem: () => Effect.die("not used"),
44
  batchWriteItem: () => Effect.die("not used"),
45
  transactGetItems: () => Effect.die("not used"),
46
  scan: () => Effect.die("not used"),
47
  createTable: () => Effect.die("not used"),
48
  deleteTable: () => Effect.die("not used"),
49
  describeTable: () => Effect.die("not used"),
50
  updateTable: () => Effect.die("not used"),
51
  listTables: () => Effect.die("not used"),
52
  createBackup: () => Effect.die("not used"),
53
  deleteBackup: () => Effect.die("not used"),
54
  listBackups: () => Effect.die("not used"),
55
  restoreTableFromBackup: () => Effect.die("not used"),
56
  describeContinuousBackups: () => Effect.die("not used"),
57
  updateContinuousBackups: () => Effect.die("not used"),
58
  restoreTableToPointInTime: () => Effect.die("not used"),
59
  exportTableToPointInTime: () => Effect.die("not used"),
60
  describeExport: () => Effect.die("not used"),
61
  updateTimeToLive: () => Effect.die("not used"),
62
  describeTimeToLive: () => Effect.die("not used"),
63
  tagResource: () => Effect.die("not used"),
64
  untagResource: () => Effect.die("not used"),
65
  listTagsOfResource: () => Effect.die("not used"),
66
})
67

68
const TestLayer = Layer.merge(MockDynamoClient, MainTable.layer({ name: "test-table" }))

Verify a Put Operation

Create a typed client with DynamoClient.make() and assert that the entity’s put method calls the underlying DynamoDB client correctly. Wire the mock layer with Effect.provide(TestLayer):

1
const testPutOperation = Effect.gen(function* () {
2
  resetMocks()
3

4
  // EmployeeEntity has unique constraints, so it uses transactWriteItems
5
  transactWriteItemsResponse = Effect.succeed({})
6

7
  const db = yield* DynamoClient.make({
8
    entities: { EmployeeEntity, TaskEntity },
9
  })
10

11
  const result = yield* db.entities.EmployeeEntity.put({
12
    employeeId: "emp-1",
13
    email: "alice@acme.com",
14
    displayName: "Alice",
15
    department: "Engineering",
16
    createdBy: "admin",
17
  })
18

19
  // Verify the result
20
  console.assert(result.employeeId === "emp-1", "employeeId should be emp-1")
21
  console.assert(result.displayName === "Alice", "displayName should be Alice")
22
  console.assert(transactWriteItemsCalls.length === 1, "transactWriteItems should be called once")
23

24
  yield* Console.log("  Put operation: PASSED")
25
}).pipe(Effect.provide(TestLayer))

Assert on Error Paths

Mock the client to return a failure and use Effect.flip to inspect the error channel. When a unique constraint entity receives a TransactionCanceledException, effect-dynamodb translates it to a UniqueConstraintViolation:

1
// #region test-error
2
const testErrorPath = Effect.gen(function* () {
3
  resetMocks()
4

5
  // Simulate a TransactionCanceledException (unique constraint violation).
6
  // Index 0 = main item (succeeds), index 1 = sentinel (fails with ConditionalCheckFailed).
7
  transactWriteItemsResponse = Effect.fail(
8
    new DynamoError({
9
      operation: "TransactWriteItems",
10
      cause: {
11
        name: "TransactionCanceledException",
12
        CancellationReasons: [{ Code: "None" }, { Code: "ConditionalCheckFailed" }],
13
      },
14
    }),
15
  )
16

17
  const db = yield* DynamoClient.make({
18
    entities: { EmployeeEntity, TaskEntity },
19
  })
20

21
  const result = yield* db.entities.EmployeeEntity.put({
22
    employeeId: "emp-2",
23
    email: "taken@example.com",
24
    displayName: "Bob",
25
    department: "Sales",
26
    createdBy: "admin",
27
  })
28
    .asEffect()
29
    .pipe(Effect.flip)
30

31
  // The entity layer translates the DynamoDB error to a domain error
32
  console.assert(
33
    result._tag === "UniqueConstraintViolation",
34
    `expected UniqueConstraintViolation, got ${result._tag}`,
35
  )
36

37
  yield* Console.log("  Error path (UniqueConstraintViolation): PASSED")
38
}).pipe(Effect.provide(TestLayer))

Test Query Results

Return mock query results from the client and verify the decoded output. Use toAttributeMap from the Marshaller to build DynamoDB-formatted items:

1
const testQueryResults = Effect.gen(function* () {
2
  resetMocks()
3

4
  // Return mock query results from the client
5
  queryResponse = Effect.succeed({
6
    Items: [
7
      toAttributeMap({
8
        pk: "$myapp#v1#task#t-1",
9
        sk: "$myapp#v1#task",
10
        gsi1pk: "$myapp#v1#task#proj-alpha",
11
        gsi1sk: "$myapp#v1#tasksByProject#task#active",
12
        __edd_e__: "Task",
13
        taskId: "t-1",
14
        projectId: "proj-alpha",
15
        title: "Implement feature",
16
        status: "active",
17
        assignee: "alice",
18
        createdAt: "2024-01-15T10:30:00.000Z",
19
        updatedAt: "2024-01-15T10:30:00.000Z",
20
      }),
21
      toAttributeMap({
22
        pk: "$myapp#v1#task#t-2",
23
        sk: "$myapp#v1#task",
24
        gsi1pk: "$myapp#v1#task#proj-alpha",
25
        gsi1sk: "$myapp#v1#tasksByProject#task#active",
26
        __edd_e__: "Task",
27
        taskId: "t-2",
28
        projectId: "proj-alpha",
29
        title: "Write tests",
30
        status: "active",
31
        assignee: "bob",
32
        createdAt: "2024-01-16T09:00:00.000Z",
33
        updatedAt: "2024-01-16T09:00:00.000Z",
34
      }),
35
    ],
36
    LastEvaluatedKey: undefined,
37
  })
38

39
  const db = yield* DynamoClient.make({
40
    entities: { EmployeeEntity, TaskEntity },
41
  })
42

43
  const results = yield* db.entities.TaskEntity.byProject({ projectId: "proj-alpha" })
44
    .filter({ status: "active" })
45
    .collect()
46

47
  // Verify decoded results
48
  console.assert(results.length === 2, `expected 2 results, got ${results.length}`)
49
  console.assert(results[0]!.taskId === "t-1", "first task should be t-1")
50
  console.assert(results[1]!.taskId === "t-2", "second task should be t-2")
51
  console.assert(results[0]!.title === "Implement feature", "first task title should match")
52
  console.assert(queryCalls.length === 1, "query should be called once")
53

54
  yield* Console.log("  Query results: PASSED")
55
}).pipe(Effect.provide(TestLayer))

Using with Vitest

In a real test suite, use @effect/vitest with it.effect instead of running assertions manually. The Layer.succeed and Effect.provide patterns are identical:

1
import { describe, expect, it } from "@effect/vitest"
2
import { Effect, Layer } from "effect"
3
import { DynamoClient } from "effect-dynamodb"
4
import { beforeEach, vi } from "vitest"
5

6
describe("EmployeeEntity", () => {
7
  beforeEach(() => vi.resetAllMocks())
8

9
  it.effect("creates an employee", () =>
10
    Effect.gen(function* () {
11
      // ... same pattern as above, but with vi.fn() and expect()
12
      const db = yield* DynamoClient.make({
13
        entities: { EmployeeEntity, TaskEntity },
14
        tables: { MainTable },
15
      })
16

17
      const result = yield* db.entities.EmployeeEntity.put({
18
        employeeId: "emp-1",
19
        email: "alice@acme.com",
20
        displayName: "Alice",
21
        department: "Engineering",
22
        createdBy: "admin",
23
      })
24

25
      expect(result.employeeId).toBe("emp-1")
26
      expect(result.displayName).toBe("Alice")
27
    }).pipe(Effect.provide(TestLayer))
28
  )
29
})

What’s Next?

Getting Started — Quick start guide
DynamoDB Streams — Process change events from DynamoDB Streams