Cloud Spec - AWS CDK

Cloud Spec is a testing framework for AWS CDK applications that simplifies the process of writing and running integration tests for your cloud infrastructure. Unlike the official @aws-cdk/integ-tests-alpha module, Cloud Spec drives the tests locally via vitest

Features

• Easily deploy CDK stacks for testing purposes
• Automatically manage stack outputs
• Simplified test setup and execution
• Automatic stack naming based on test names
• Tagging of resources for easy identification

Installation

npm install @cloudspec/aws-cdk

Requirements

• Vitest (tested with version 1.6)
• A Vitest configuration file (e.g., vitest.config.mjs) with the following settings:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    // Needed for bundling NodeJSFunction during tests
    // see https://github.com/aws/aws-cdk/issues/20873
    pool: 'forks',
  },
})

Usage

Here's a basic example of how to use Cloud Spec:

import { cloudSpec } from '@cloudspec/aws-cdk';
import { Stack, CfnOutput } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { describe, it } from 'vitest';

const cloud = cloudSpec();

describe('S3 Bucket Tests', () => {
  cloud.setup((stack: Stack, setOutputs) => {
    const bucket = new Bucket(stack, 'TestBucket');
    setOutputs({
      bucketName: bucket.bucketName,
    });
  });

  cloud.test('bucket should exist', async (outputs) => {
    const { bucketName } = outputs;
     // Add assertions here to check if the bucket exists
  });

and run vitest

API

cloudSpec()

Returns an object with two functions:

• setup(createResources, timeout?): Sets up the CDK stack for testing.

  • createResources: A function that creates the CDK resources and sets outputs.
  • timeout: Optional timeout for stack deployment (default: 120000ms).

• test(name, testFn, timeout?): Runs a test against the deployed resources.

  • name: The name of the test.
  • testFn: An async function containing test assertions.
  • timeout: Optional timeout for the test (default: 600000ms).

Contributing

We welcome contributions!

License

This project is licensed under the MIT License - see the LICENSE file for details.