vitest-dynamodb-lite

https://github.com/yamatatsu/vitest-dynamodb-lite
Admin
A utility that integrates DynamoDB Lite, an in-memory or file-based DynamoDB emulator, with the...
Tokens:4,383
Snippets:22
Trust Score:8.5
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install vitest-dynamodb-lite

Source: https://github.com/yamatatsu/vitest-dynamodb-lite/blob/main/packages/vitest-dynamodb-lite/README.md

Demonstrates how to install the vitest-dynamodb-lite package using different package managers. This is a development dependency.

```bash
npm i vitest-dynamodb-lite -D
# or
yarn add vitest-dynamodb-lite -D
# or
pnpm add vitest-dynamodb-lite -D
```

--------------------------------

### Perform Basic CRUD Operations with Mock DynamoDB

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Demonstrates basic DynamoDB CRUD operations (put, get, query) using the AWS SDK v3 Document Client connected to the mock server. Includes examples for single items and querying with composite keys.

```javascript
import { test, expect } from "vitest";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const dynamodb = DynamoDBDocument.from(
  new DynamoDBClient({
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    region: "local",
  }),
);

test("should put and get an item", async () => {
  // Put an item
  await dynamodb.put({
    TableName: "users",
    Item: {
      id: "user-123",
      name: "John Doe",
      email: "john@example.com",
      age: 30,
    },
  });

  // Get the item
  const { Item } = await dynamodb.get({
    TableName: "users",
    Key: { id: "user-123" },
  });

  expect(Item).toEqual({
    id: "user-123",
    name: "John Doe",
    email: "john@example.com",
    age: 30,
  });
});

test("should query items with composite keys", async () => {
  // Put multiple items
  await dynamodb.put({
    TableName: "orders",
    Item: { userId: "user-123", orderId: 1, total: 99.99 },
  });
  await dynamodb.put({
    TableName: "orders",
    Item: { userId: "user-123", orderId: 2, total: 49.99 },
  });

  // Query items
  const { Items } = await dynamodb.query({
    TableName: "orders",
    KeyConditionExpression: "userId = :userId",
    ExpressionAttributeValues: {
      ":userId": "user-123",
    },
  });

  expect(Items).toHaveLength(2);
  expect(Items[0].orderId).toBe(1);
  expect(Items[1].orderId).toBe(2);
});
```

--------------------------------

### CommonJS Configuration for DynamoDB Tables

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

An example of configuring DynamoDB tables using the CommonJS module format. This is suitable for Node.js environments that use `require`. It defines table schemas and throughput settings.

```javascript
// vitest-dynamodb-lite-config.cjs (CommonJS)
module.exports = {
  tables: [
    {
      TableName: "products",
      KeySchema: [{ AttributeName: "sku", KeyType: "HASH" }],
      AttributeDefinitions: [{ AttributeName: "sku", AttributeType: "S" }],
      ProvisionedThroughput: { ReadCapacityUnits: 1, WriteCapacityUnits: 1 },
    },
  ],
  basePort: 8000,
};

```

--------------------------------

### Configure vitest setupFiles

Source: https://github.com/yamatatsu/vitest-dynamodb-lite/blob/main/packages/vitest-dynamodb-lite/README.md

Shows how to configure vitest to use vitest-dynamodb-lite by adding it to the `setupFiles` array in `vitest.config.ts`. This ensures the mock is initialized before tests run.

```javascript
// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["vitest-dynamodb-lite"],
  },
});
```

--------------------------------

### DynamoDB Client Initialization

Source: https://github.com/yamatatsu/vitest-dynamodb-lite/blob/main/packages/vitest-dynamodb-lite/README.md

Illustrates how to initialize the DynamoDBClient to connect to the mock endpoint provided by vitest-dynamodb-lite. It utilizes `process.env.MOCK_DYNAMODB_ENDPOINT` which is unique per test runner.

```javascript
const client = new DynamoDBClient({
  ...yourConfig,
  ...(process.env.MOCK_DYNAMODB_ENDPOINT && {
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    region: "local",
  }),
});
```

--------------------------------

### Destroying DynamoDB Client

Source: https://github.com/yamatatsu/vitest-dynamodb-lite/blob/main/packages/vitest-dynamodb-lite/README.md

Shows the recommended practice of destroying the DynamoDB client after all tests have completed to clean up resources. This can be done in a `setupFilesAfterEnv` configuration.

```javascript
afterAll(() => {
  client.destroy();
});
```

--------------------------------

### Configure Vitest to use vitest-dynamodb-lite

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Configure Vitest to use vitest-dynamodb-lite by adding it to the setupFiles in your vitest.config.ts. This ensures the mock server is initialized for your tests.

```typescript
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["vitest-dynamodb-lite"],
  },
});
```

--------------------------------

### JSON Configuration for DynamoDB Tables

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Demonstrates how to configure DynamoDB tables using a JSON file. This format is straightforward and widely compatible. It specifies table names, key schemas, attribute definitions, and provisioned throughput.

```json
// vitest-dynamodb-lite-config.json
{
  "tables": [
    {
      "TableName": "products",
      "KeySchema": [{ "AttributeName": "sku", "KeyType": "HASH" }],
      "AttributeDefinitions": [{ "AttributeName": "sku", "AttributeType": "S" }],
      "ProvisionedThroughput": { "ReadCapacityUnits": 1, "WriteCapacityUnits": 1 }
    }
  ],
  "basePort": 8000
}

```

--------------------------------

### DynamoDB Table Configuration

Source: https://github.com/yamatatsu/vitest-dynamodb-lite/blob/main/packages/vitest-dynamodb-lite/README.md

Defines the schema and configuration for DynamoDB tables used by vitest-dynamodb-lite. This includes table name, key schema, attribute definitions, and throughput. It can be in JS or JSON format.

```javascript
export default {
  tables: [
    {
      TableName: "table",
      KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
      AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
      ProvisionedThroughput: {
        ReadCapacityUnits: 1,
        WriteCapacityUnits: 1,
      },
    },
  ],
  basePort: 8000,
};
```

```json
module.exports = {
  tables: [
    {
      // ...
      data: [{ id: "a", someattribute: "hello world" }],
    },
  ],
};
```

--------------------------------

### Define DynamoDB Table Schemas with vitest-dynamodb-lite

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Define your DynamoDB table schemas in a configuration file (e.g., vitest-dynamodb-lite-config.js). This configuration specifies table names, key schemas, attribute definitions, and provisioned throughput.

```javascript
export default {
  tables: [
    {
      TableName: "users",
      KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
      AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
      ProvisionedThroughput: {
        ReadCapacityUnits: 1,
        WriteCapacityUnits: 1,
      },
    },
    {
      TableName: "orders",
      KeySchema: [
        { AttributeName: "userId", KeyType: "HASH" },
        { AttributeName: "orderId", KeyType: "RANGE" },
      ],
      AttributeDefinitions: [
        { AttributeName: "userId", AttributeType: "S" },
        { AttributeName: "orderId", AttributeType: "N" },
      ],
      ProvisionedThroughput: {
        ReadCapacityUnits: 1,
        WriteCapacityUnits: 1,
      },
    },
  ],
  basePort: 8000,
};
```

--------------------------------

### Integrate AWS SDK v3 DynamoDB Client with Mock Server

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Connect your AWS SDK v3 DynamoDB client to the mock server by using the automatically provided environment variables (MOCK_DYNAMODB_ENDPOINT). This allows your application code to interact with the mock database during tests. Includes cleanup logic using afterAll.

```javascript
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";
import { afterAll } from "vitest";

const client = new DynamoDBClient({
  ...(process.env.MOCK_DYNAMODB_ENDPOINT && {
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    region: "local",
  }),
});

const dynamodb = DynamoDBDocument.from(client);

// Clean up after all tests
afterAll(() => {
  client.destroy();
});

// Use dynamodb for all operations
export { dynamodb };
```

--------------------------------

### Dynamic Table Configuration with Functions (TypeScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Allows for dynamic generation of DynamoDB table configurations at runtime using functions. This is useful for creating table names based on environment variables or other runtime conditions. It requires the `Config` type from `vitest-dynamodb-lite`.

```typescript
// vitest-dynamodb-lite-config.ts
import { Config } from "vitest-dynamodb-lite";

export default {
  tables: async () => {
    // Load configuration from external source
    const environment = process.env.NODE_ENV || "test";

    return [
      {
        TableName: `users-${environment}`,
        KeySchema: [{ AttributeName: "id", KeyType: "HASH" }],
        AttributeDefinitions: [{ AttributeName: "id", AttributeType: "S" }],
        ProvisionedThroughput: {
          ReadCapacityUnits: 1,
          WriteCapacityUnits: 1,
        },
      },
    ];
  },
  basePort: 8000,
} satisfies Config;

```

--------------------------------

### Access and Verify Fixture Data in Vitest (JavaScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Demonstrates how to connect to the mock DynamoDB endpoint and query pre-populated fixture data within Vitest tests. It uses `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` to interact with the database. Asserts that the retrieved items match the expected fixture data.

```javascript
import { test, expect } from "vitest";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const dynamodb = DynamoDBDocument.from(
  new DynamoDBClient({
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    region: "local",
  }),
);

test("should access pre-populated fixture data", async () => {
  const { Item } = await dynamodb.get({
    TableName: "pk-string-table",
    Key: { pk_string: "pk-0" },
  });

  expect(Item).toEqual({ pk_string: "pk-0" });
});

test("fixture data resets between tests", async () => {
  // This test runs independently with fresh fixture data
  const { Item } = await dynamodb.get({
    TableName: "pk-string-table",
    Key: { pk_string: "pk-1" },
  });

  expect(Item).toEqual({ pk_string: "pk-1" });
});

```

--------------------------------

### Configure Fixture Data for DynamoDB Tables (JavaScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

Defines initial data for DynamoDB tables that will be pre-populated and reset between tests. This ensures consistent test environments. It requires the table schema and the data to be inserted.

```javascript
// vitest-dynamodb-lite-config.js
export default {
  tables: [
    {
      TableName: "pk-string-table",
      KeySchema: [{ AttributeName: "pk_string", KeyType: "HASH" }],
      AttributeDefinitions: [
        { AttributeName: "pk_string", AttributeType: "S" },
      ],
      ProvisionedThroughput: { ReadCapacityUnits: 1, WriteCapacityUnits: 1 },
      data: [
        { pk_string: "pk-0" },
        { pk_string: "pk-1" },
        { pk_string: "pk-2" },
      ],
    },
    {
      TableName: "pk-string-sk-number-table",
      KeySchema: [
        { AttributeName: "pk_string", KeyType: "HASH" },
        { AttributeName: "sk_number", KeyType: "RANGE" },
      ],
      AttributeDefinitions: [
        { AttributeName: "pk_string", AttributeType: "S" },
        { AttributeName: "sk_number", AttributeType: "N" },
      ],
      ProvisionedThroughput: { ReadCapacityUnits: 1, WriteCapacityUnits: 1 },
      data: [
        { pk_string: "pk-0", sk_number: 1, group: "a-1" },
        { pk_string: "pk-0", sk_number: 2, group: "a-1" },
        { pk_string: "pk-1", sk_number: 1, group: "a-1" },
        { pk_string: "pk-1", sk_number: 2, group: "a-2" },
      ],
    },
  ],
  basePort: 8200,
};

```

--------------------------------

### Define Complex DynamoDB Table Schema with GSI (JavaScript Configuration)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

This configuration file defines a DynamoDB table named 'analytics' with a composite primary key (userId, timestamp) and a Global Secondary Index (EventTypeIndex) also with a composite key (eventType, timestamp). It includes attribute definitions, projection types, provisioned throughput, and initial data.

```javascript
// vitest-dynamodb-lite-config.js
export default {
  tables: [
    {
      TableName: "analytics",
      KeySchema: [
        { AttributeName: "userId", KeyType: "HASH" },
        { AttributeName: "timestamp", KeyType: "RANGE" },
      ],
      AttributeDefinitions: [
        { AttributeName: "userId", AttributeType: "S" },
        { AttributeName: "timestamp", AttributeType: "N" },
        { AttributeName: "eventType", AttributeType: "S" },
      ],
      GlobalSecondaryIndexes: [
        {
          IndexName: "EventTypeIndex",
          KeySchema: [
            { AttributeName: "eventType", KeyType: "HASH" },
            { AttributeName: "timestamp", KeyType: "RANGE" },
          ],
          Projection: { ProjectionType: "ALL" },
          ProvisionedThroughput: {
            ReadCapacityUnits: 1,
            WriteCapacityUnits: 1,
          },
        },
      ],
      ProvisionedThroughput: {
        ReadCapacityUnits: 1,
        WriteCapacityUnits: 1,
      },
      data: [
        { userId: "user-1", timestamp: 1000, eventType: "login" },
        { userId: "user-1", timestamp: 2000, eventType: "purchase" },
        { userId: "user-2", timestamp: 1500, eventType: "login" },
      ],
    },
  ],
  basePort: 8000,
};

```

--------------------------------

### Run Concurrent Vitest Tests with Isolated DynamoDB Instances (JavaScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

This snippet demonstrates how to run multiple test files concurrently using Vitest. Each test file imports AWS SDK clients and configures them with an endpoint specific to its runner, ensuring isolated DynamoDB instances per test.

```javascript
// tests/user-service.test.js
import { test, expect } from "vitest";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const dynamodb = DynamoDBDocument.from(
  new DynamoDBClient({
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT, // Unique per test file
    region: "local",
  }),
);

test("user service - create user", async () => {
  await dynamodb.put({
    TableName: "users",
    Item: { id: "user-1", name: "Alice" },
  });

  const { Item } = await dynamodb.get({
    TableName: "users",
    Key: { id: "user-1" },
  });

  expect(Item.name).toBe("Alice");
});

// tests/order-service.test.js - runs concurrently in separate process
import { test, expect } from "vitest";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const dynamodb = DynamoDBDocument.from(
  new DynamoDBClient({
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT, // Different port from user-service
    region: "local",
  }),
);

test("order service - create order", async () => {
  await dynamodb.put({
    TableName: "users",
    Item: { id: "user-1", name: "Bob" }, // No conflict with user-service test
  });

  const { Item } = await dynamodb.get({
    TableName: "users",
    Key: { id: "user-1" },
  });

  expect(Item.name).toBe("Bob"); // Different data, different instance
});

```

--------------------------------

### Query DynamoDB Using Global Secondary Index (JavaScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

This test snippet demonstrates how to query a DynamoDB table using a Global Secondary Index (GSI). It queries the 'analytics' table using the 'EventTypeIndex' to retrieve records where eventType is 'login', showcasing the usage of IndexName and ExpressionAttributeValues.

```javascript
import { test, expect } from "vitest";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb";

const dynamodb = DynamoDBDocument.from(
  new DynamoDBClient({
    endpoint: process.env.MOCK_DYNAMODB_ENDPOINT,
    region: "local",
  }),
);

test("should query using global secondary index", async () => {
  const { Items } = await dynamodb.query({
    TableName: "analytics",
    IndexName: "EventTypeIndex",
    KeyConditionExpression: "eventType = :eventType",
    ExpressionAttributeValues: {
      ":eventType": "login",
    },
  });

  expect(Items).toHaveLength(2);
  expect(Items[0].userId).toBe("user-1");
  expect(Items[1].userId).toBe("user-2");
});

```

--------------------------------

### Access Environment Variables for DynamoDB and AWS Credentials (JavaScript)

Source: https://context7.com/yamatatsu/vitest-dynamodb-lite/llms.txt

This snippet shows how to access automatically configured environment variables within Vitest tests. These include the unique port for the DynamoDB connection, the full endpoint URL, and mock AWS credentials.

```javascript
import { test, expect } from "vitest";

test("environment variables are set", () => {
  // Port unique to this test runner (basePort + VITEST_WORKER_ID)
  expect(process.env.MOCK_DYNAMODB_PORT).toBeDefined();
  expect(parseInt(process.env.MOCK_DYNAMODB_PORT)).toBeGreaterThan(8000);

  // Endpoint for DynamoDB client configuration
  expect(process.env.MOCK_DYNAMODB_ENDPOINT).toBe(
    `http://localhost:${process.env.MOCK_DYNAMODB_PORT}`
  );

  // Mock AWS credentials (set if not already present)
  expect(process.env.AWS_ACCESS_KEY_ID).toBe("access-key");
  expect(process.env.AWS_SECRET_ACCESS_KEY).toBe("secret-key");
});

```
Tokens:
Raw