@kensio/yulin v0.18.0 adds simulated CloudFormation

Version 0.18.0 of the @kensio/yulin package adds simulated CloudFormation.

This feature allows you to deploy JSON templates from CloudFormation, SAM or CDK into the simulated AWS. Using your existing CloudFormation templates for local development and testing is convenient and efficient.

The simulated CloudFormation deployment only takes a few milliseconds and sets up the simulated AWS resources in the same single process alongside your Node.js application code and tests. You can step through the whole system in a debugger, as well as collect test coverage metrics from the simulated system tests.

Given a basic CloudFormation JSON output template like this:

{
  "Resources": {
    "SiteBucket": {
      "Type": "AWS::S3::Bucket",
      "Properties": {
        "BucketName": "example-site-bucket",
        "WebsiteConfiguration": {
          "IndexDocument": "index.html"
        }
      }
    }
  }
}

You can directly deploy it into the simulated AWS via the sim CloudFormation service:

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();
const simCfn = simAws.cloudFormation();

const stack = await simCfn.deployTemplate({
  stackName: "site-stack",
  template: {
    Resources: {
      SiteBucket: {
        Type: "AWS::S3::Bucket",
        Properties: {
          BucketName: "example-site-bucket",
          WebsiteConfiguration: {
            IndexDocument: "index.html",
          },
        },
      },
    },
  },
});

await stack.waitForDeployComplete();

That creates the simulated S3 Bucket and configures static website hosting for it according to the configuration in the JSON template.

There is also a deployTemplateFile() convenience method that takes a file path and deploys the JSON template at that path into the simulated AWS:

import { SimAws } from "@kensio/yulin";

const simAws = new SimAws();

const stack = await simAws
  .cloudFormation()
  .deployTemplateFile("foo/bar/path/template.json");

await stack.waitForDeployComplete();

Because the simulated CloudFormation uses normal JSON output templates, it can deploy templates created by standard CloudFormation, SAM or CDK. You can use the existing CloudFormation setup for your project directly with the simulated AWS, making it easy to run realistic system tests and develop locally on your laptop.

By default the simulated CloudFormation deploys CloudFront Functions from the handler source code embedded in the JSON template. This works and supports low-effort configuration. There is also an optional bindings parameter that you can use to swap in the real handler function implementations for your CloudFront Functions when deploying into simulated AWS:

import { SimAws } from "@kensio/yulin";

import { viewerRequestHandler } from "./path/to/viewer-request-handler.js";

const simAws = new SimAws();

const stack = await simAws
  .cloudFormation()
  .deployTemplateFile({
    templatePath: "cdk.out/TestStack.template.json",
    bindings: [
      {
        logicalId: "FooCloudFrontFunction",
        handler: viewerRequestHandler,
      },
    ],
  });

The simulated CloudFormation deployment uses the logicalId of the CloudFront Function to swap in the real handler function in the same process. This allows you to run the whole system simulation and step through it in a debugger, including inside CloudFront Function handler code. It also allows you to collect test coverage metrics for your CloudFront Functions.

GitHub: https://github.com/KensioSoftware/yulin

npm: https://www.npmjs.com/package/@kensio/yulin