@horietakehiro/aws-cdk-utul 0.2.2 → 0.9.0

package/README.md

@@ -1,14 +1,88 @@
-# Welcome to your CDK TypeScript project
+# AWS CDK Unit Test Utility Library
 
-This is a blank project for CDK development with TypeScript.
+<p align="left">
+    <a href="https://www.npmjs.com/package/@horietakehiro/aws-cdk-utul?activeTab=readme" > 
+        <img alt="NPM Version" src="https://img.shields.io/npm/v/%40horietakehiro%2Faws-cdk-utul">
+   </a>
+</p>
 
-The `cdk.json` file tells the CDK Toolkit how to execute your app.
+**aws-cdk-utul(unit test utility library) makes it faster, more efficient, and less mistaken for you to code AWS CDK unit tests.**
 
-## Useful commands
+---
 
-* `npm run build`   compile typescript to js
-* `npm run watch`   watch for changes and compile
-* `npm run test`    perform the jest unit tests
-* `npx cdk deploy`  deploy this stack to your default AWS account/region
-* `npx cdk diff`    compare deployed stack with current state
-* `npx cdk synth`   emits the synthesized CloudFormation template
+## Features
+
+---
+
+### TypedTemplate
+
+When you code AWS CDK unit tests in some IDE(e.g. VSCode), `TypedTemplate` class provides you a type hinting and type validation for (alomost) all AWS CloudFormation resource types.
+
+![type-hinting-1](./docs/type-hinting-1.png)
+
+The key concepts are:
+- You can define unit tests for your AWS CloudFormation templates by using well-type-defined methods via `TypedTemplate` class - a proxy for original `Template` class.
+- Returned values from methods of `TypedTemplate` are also well-type-defined.
+- You can still use `Matcher` and other arbitrary objects too.
+
+So you can quickly code AWS CDK unit tests without any trivial mistakes and googling.
+```js
+import { Stack } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+
+import { TypedTemplate } from "@horietakehiro/aws-cdk-utul/lib/assertions";
+import { AWS_EC2_SUBNET, AWS_EC2_VPC } from "@horietakehiro/aws-cdk-utul/lib/types/cfn-resource-types";
+const stack = new Stack()
+
+// just wrap an original `Template` instance of aws-cdk-lib/assertions
+const template = new TypedTemplate(Template.fromStack(stack))
+// you can execute all method implemented in original `Template` instance
+template.hasResource(AWS_EC2_VPC({Properties: {
+  CidrBlock: "10.0.0.0/16"
+}}))
+// you can still use original `Matcher` class too.
+const subnets = template.findResources(AWS_EC2_SUBNET({Properties: {
+  Tags: Match.arrayWith([
+    {Key: "Name", Value: Match.stringLikeRegexp("Public")}
+  ])
+}}))
+// you can access resources with more efficient way
+subnets.forEach((sn) => { 
+  expect(sn.def.Properties?.CidrBlock?.endsWith("/24")).toBe(true)
+})
+```
+
+---
+
+### ExtraMatch
+
+`ExtraMatch` class provides you some kind of a syntax sugar for original `Match` class.
+
+```js
+import { ExtraMatch } from "@horietakehiro/aws-cdk-utul/lib/assertions"
+// get just vpc's logical id
+const [{id}] = template.findResources(AWS_EC2_VPC({}))
+template.allResources(AWS_EC2_SUBNET({
+  // Equals to {VpcId: {Ref: id}}
+  Properties: {VpcId: ExtraMatch.ref(id)}
+}))
+template.hasOutput("VPCARN", {
+  // Equals to {Value: {"Fn::GetAtt": [id, "Arn"]}}
+  Value: ExtraMatch.getAttArn(id)
+})
+```
+
+---
+
+## Install
+
+```bash
+npm install @horietakehiro/aws-cdk-utul
+```
+
+---
+
+## Some notes
+
+- Schemas of AWS CloudFormation resource types used in this library are based on [those at `us-east-1`](https://docs.aws.amazon.com/ja_jp/AWSCloudFormation/latest/UserGuide/resource-type-schemas.html)
+- Compatible with AWS CDK v2.0.0 or greater.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@horietakehiro/aws-cdk-utul",
   "license": "MIT",
-  "version": "0.2.2",
+  "version": "0.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/horietakehiro/aws-cdk-utul"