@liflig/cdk-snapshot 1.0.0 → 1.0.2

package/README.md

@@ -2,27 +2,42 @@
 
 [![npm](https://img.shields.io/npm/v/@liflig/cdk-snapshot.svg)](https://www.npmjs.com/package/@liflig/cdk-snapshot)
 [![ci](https://github.com/capralifecycle/cdk-snapshot/actions/workflows/ci.yml/badge.svg)](https://github.com/capralifecycle/cdk-snapshot/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/@liflig/cdk-snapshot.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@liflig/cdk-snapshot.svg)](LICENSE)
 
-Normalizes synthesized AWS CDK stacks for snapshot testing by stripping values such as asset hashes, bootstrap parameters, Lambda version suffixes and more, in order to produce more stable and usable snapshot files.
+Snapshot testing for AWS CDK stacks. A stack is synthesized to CloudFormation and
+normalized before it is snapshotted. The CDK bootstrap version is always dropped.
+Asset hashes, Lambda version suffixes and CDK Pipelines asset IDs change whenever
+an asset's content does; the [options](#options) mask them, so a snapshot fails only
+when the infrastructure itself changed.
 
-The library provides a generic implementation with a thin adapter per test runner: `node:test`, Bun, Vitest and Jest. Everything is built around one pure function, `cdkTemplate`, which turns a stack into a normalized template object; each adapter wraps that function in whatever the runner's own snapshot assertion looks like. All four write the same snapshot bodies — only the file header differs — so the same `.snap` files stay valid if a project switches runner.
+- One normalization for `node:test`, Bun, Vitest and Jest.
+- All four record the same template. Switching runner means regenerating the snapshots
+  once, see [Switching runner](#switching-runner).
+- Replaces `jest-cdk-snapshot` with the same options, defaults and serialization,
+  see [Migrating](#migrating-from-jest-cdk-snapshot).
 
 ## Install
 
 ```sh
 bun add -d @liflig/cdk-snapshot
+npm install --save-dev @liflig/cdk-snapshot
+pnpm add -D @liflig/cdk-snapshot
 ```
 
-`aws-cdk-lib` and `constructs` are peer dependencies. The package is ESM; CommonJS test files can `require()` it on Node 22.12 or later.
+The package is ESM. Under Jest that needs configuration, see [Jest](#jest).
 
 ## Usage
 
-Import the entry point for your runner. Jest, Vitest and Bun get a `toMatchCdkSnapshot` matcher; `node:test` has no `expect` at the time of writing, so it calls `cdkTemplate` directly.
+Import the entry point for your runner. Jest, Vitest and Bun get a `toMatchCdkSnapshot`
+matcher; `node:test` has no `expect`, so it calls `cdkTemplate` directly.
 
 ### node:test
 
-`configureCdkSnapshots()` points `node:test` at `__snapshots__/*.snap` and the shared serializer. Call it once, before any test runs. It replaces the default serializer for _every_ snapshot in the run, not just CDK ones, so snapshots taken elsewhere in the same project will be reformatted.
+`configureCdkSnapshots()` points `node:test` at `__snapshots__/*.snap` and the shared
+serializer. Call it once, before any test runs. It replaces the default serializer for
+_every_ snapshot in the run, not just CDK ones, so snapshots taken elsewhere in the same
+project will be reformatted.
 
 ```js
 import test from "node:test";
@@ -59,6 +74,18 @@ test("my stack", () => {
 });
 ```
 
+`toMatchCdkSnapshot` does not work in concurrent tests: it snapshots through the global
+`expect`, which Vitest cannot attribute to a test running concurrently. There, snapshot
+the template with the test's own `expect` instead, which records the same entry:
+
+```js
+import { cdkTemplate } from "@liflig/cdk-snapshot/vitest";
+
+test.concurrent("my stack", ({ expect }) => {
+  expect(cdkTemplate(stack, { ignoreAssets: true })).toMatchSnapshot();
+});
+```
+
 ### Jest
 
 ```js
@@ -69,9 +96,23 @@ test("my stack", () => {
 });
 ```
 
-The Jest entry point uses the global `expect`, so it throws on import if Jest is configured with `injectGlobals: false`.
+Jest loads this package as ESM, which it does only with its ESM support enabled:
+
+```sh
+NODE_OPTIONS=--experimental-vm-modules jest
+```
+
+A CommonJS test file additionally needs Node 24.9 or later, where Jest can `require()` an
+ESM package. Below that, the test file has to be ESM or go through a transform that
+compiles the package to CommonJS.
+
+The Jest entry point uses the global `expect`, so it throws on import if Jest is
+configured with `injectGlobals: false`.
 
-The matcher also accepts `propertyMatchers`, forwarded to the runner's own snapshot assertion for values the normalizations do not cover:
+### Matcher notes
+
+`toMatchCdkSnapshot` also accepts `propertyMatchers`, forwarded to the runner's own
+snapshot assertion for values the normalizations do not cover:
 
 ```js
 expect(stack).toMatchCdkSnapshot({
@@ -79,30 +120,82 @@ expect(stack).toMatchCdkSnapshot({
 });
 ```
 
-Every entry point also exports `cdkTemplate(stack, options)`. Reach for it to assert on the template without a snapshot. It leaves the stack untouched, so one stack can be synthesized repeatedly with different options.
+Every entry point also exports `cdkTemplate(stack, options)`. Reach for it to assert on
+the template without a snapshot. It leaves the stack untouched, so one stack can be
+synthesized repeatedly with different options.
 
 `toMatchCdkSnapshot` cannot be negated; `.not` throws rather than silently passing.
 
-## Options
-
-| Option                   | Default       | Effect                                                                              |
-| ------------------------ | ------------- | ----------------------------------------------------------------------------------- |
-| `ignoreAssets`           | `false`       | Replaces Lambda `Code`, container `Image` and the whole `Parameters` block with `Any<Object>` |
-| `ignoreBootstrapVersion` | `true`        | Drops the `BootstrapVersion` parameter and its check rule                            |
-| `ignoreCurrentVersion`   | `false`       | Masks the content hash on Lambda `CurrentVersion` logical IDs                        |
-| `ignoreMetadata`         | `false`       | Drops template and resource `Metadata`                                               |
-| `ignoreTags`             | `false`       | Drops `Tags` from resource properties                                                |
-| `ignorePipelineAssets`   | `false`       | Masks asset paths and IDs in CDK Pipelines `cdk-assets` commands                     |
-| `subsetResourceTypes`    | —             | Keeps only resources of these CloudFormation types                                   |
-| `subsetResourceKeys`     | —             | Keeps only resources with these logical IDs                                          |
-| `assetPlaceholder`       | `anyObject`   | Token substituted for asset-derived values                                           |
-| `propertyMatchers`       | —             | Matchers forwarded to the runner's snapshot assertion (matcher only)                 |
+Under Jest and Vitest, `toMatchCdkSnapshot` counts as one assertion towards
+`expect.assertions()`. Bun counts it as two, since its `expect` exposes no way to
+correct the count.
 
-`subsetResourceTypes` and `subsetResourceKeys` intersect: given both, a resource is kept only if it matches both.
-
-`ignoreAssets` replaces the entire `Parameters` block rather than the individual asset parameters, matching what jest-cdk-snapshot does.
+## Options
 
-`anyObject` is exported from the package root. It is an asymmetric matcher that serializes as `Any<Object>` and matches any non-null object. The Bun entry point substitutes `expect.any(Object)` instead, because Bun's serializer only recognizes matchers built by its own `expect`.
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `ignoreAssets` | `boolean` | `false` | Replaces every `Code` property, every container definition's `Image` and the whole `Parameters` block with `Any<Object>` |
+| `ignoreBootstrapVersion` | `boolean` | `true` | Drops the `BootstrapVersion` parameter and its check rule |
+| `ignoreCurrentVersion` | `boolean` | `false` | Masks the content hash on Lambda `CurrentVersion` logical IDs and every reference to them |
+| `ignoreMetadata` | `boolean` | `false` | Drops template and resource `Metadata` |
+| `ignoreTags` | `boolean` | `false` | Drops `Tags` from resource properties |
+| `ignorePipelineAssets` | `boolean` | `false` | Masks asset paths, IDs and destination suffixes in CDK Pipelines `cdk-assets` commands |
+| `subsetResourceTypes` | `string[]` | keep all | Keeps only resources of these CloudFormation types |
+| `subsetResourceKeys` | `string[]` | keep all | Keeps only resources with these logical IDs |
+| `assetPlaceholder` | `unknown` | `anyObject` | Token substituted for asset-derived values |
+| `propertyMatchers` | `Record<string, unknown>` | none | Matchers forwarded to the runner's snapshot assertion; matcher only, `cdkTemplate` does not take it |
+
+`subsetResourceTypes` and `subsetResourceKeys` intersect: given both, a resource is kept
+only if it matches both.
+
+`ignoreAssets` is coarse, matching what jest-cdk-snapshot does:
+
+- It replaces the entire `Parameters` block. Under CDK's default synthesizer no parameter
+  carries an asset hash, so what disappears is the parameters the stack declares itself.
+- It replaces values that are not assets as well, so a change to inline Lambda code, to a
+  `Code.fromBucket` key or to a registry image tag such as `nginx:1.27` does not show.
+- Assets outside Lambda `Code` and container images keep their hash: Lambda layers,
+  `BucketDeployment` sources, Step Functions and API Gateway definitions read from files,
+  and nested stack templates.
+- A function's `currentVersion` logical ID is a hash over its configuration, code
+  included, so a stack that uses it also needs `ignoreCurrentVersion` to stay stable.
+- It does nothing to a template with no `Resources`.
+
+`ignoreTags` drops the `Tags` property of each resource. Tags nested deeper stay, such as
+those `Tags.of()` propagates into a launch template's `TagSpecifications`.
+
+`ignorePipelineAssets` also drops the 8-character suffix CDK appends to each asset
+destination, since that suffix changes with the asset's content too.
+
+`anyObject` is exported from the package root. It is an asymmetric matcher that serializes
+as `Any<Object>` and matches any non-null object. The Bun entry point substitutes
+`expect.any(Object)` instead, because Bun's serializer only recognizes matchers built by
+its own `expect`.
+
+## How it works
+
+Everything is built around one pure function, `cdkTemplate`, which turns a stack into a
+normalized template object. Each runner gets a thin adapter that wraps that function in
+whatever the runner's own snapshot assertion looks like, so snapshots keep the naming and
+format that runner already produces.
+
+## Switching runner
+
+Regenerate the snapshots with the new runner. The templates they record stay the same; the
+diff is limited to how each runner lays out the file around them:
+
+| | Jest | Vitest | node:test | Bun |
+| --- | --- | --- | --- | --- |
+| Header | Jest's, and files without it are rejected | Vitest's | none | Bun's |
+| Name of a test inside `describe` | `suite test 1` | `suite > test 1` | `suite > test 1` | `suite test 1` |
+| Entry order | sorted | sorted | sorted | test order |
+| Single-line snapshot, such as `{}` | inline | inline | on a line of its own | inline |
+| Multi-line string inside a template | starts on its key's line | starts on its key's line | starts on its key's line | string and the comma after it on lines of their own |
+
+Entry order does not affect matching, but it makes a regeneration diff look larger than it
+is: two similar snapshots trading places reads as values changing.
+
+`test/compat.test.ts` pins every row, so a runner that changes its format fails the build.
 
 ## Development
 
@@ -111,20 +204,48 @@ make build   # install, format, typecheck, refresh snapshots, test
 make ci      # what the CI workflow runs: refuses a stale lockfile, fails on an uncommitted snapshot change
 ```
 
-`make snapshots` regenerates the unit snapshots plus the shared fixture under all four runners, which `test/compat.test.ts` then compares against each other.
+`make snapshots` regenerates the unit snapshots plus the shared fixture under all four
+runners, which `test/compat.test.ts` then compares against each other.
+
+`make compat-check` runs only the four runners and fails if their snapshots changed. CI
+runs it on the oldest Node that `engines` in `package.json` allows.
 
 ## Migrating from jest-cdk-snapshot
 
-Change the import. Call sites and `.snap` files stay as they are, since the options, their defaults and the serialization all match.
+Change the import. Call sites and `.snap` files stay as they are, since the options, their
+defaults and the serialization all match.
 
 ```diff
 -import "jest-cdk-snapshot"
 +import "@liflig/cdk-snapshot/jest"
 ```
 
-Verified against liflig-cdk (64 snapshots) and cdk-cloudfront-auth: every snapshot passes under `jest --ci`, and a forced `--updateSnapshot` rewrites nothing.
+Verified against two public CDK libraries, liflig-cdk and cdk-cloudfront-auth: every
+existing snapshot passes under `jest --ci`, and a forced `--updateSnapshot` rewrites
+nothing.
+
+Jest now has to run with ESM support enabled, since this package is ESM — see
+[Jest](#jest).
+
+One option is gone. `yaml` is not supported, so a project snapshotting YAML has to
+regenerate as JSON.
+
+One option masks more. `ignorePipelineAssets` also drops the content-derived suffix that
+recent CDK versions append to asset destinations, which jest-cdk-snapshot keeps. A
+pipeline snapshot taken with it changes once, from `publish "111111111111-eu-west-1-2d2574cc"`
+to `publish "111111111111-eu-west-1"`, and then stays put when asset content changes.
+
+jest-cdk-snapshot's option type also extended `StageSynthesisOptions`, so it accepted
+`skipValidation`, `validateOnSynthesis`, `force`, `errorOnDuplicateSynth` and
+`aspectStabilization` while warning at runtime that they did nothing. Here the type
+checker rejects them; delete them.
+
+## Releases
 
-Two of its options are gone. `yaml` is not supported, so a project snapshotting YAML has to regenerate as JSON. The no-op synthesis options it inherited from `StageSynthesisOptions` — `skipValidation`, `validateOnSynthesis`, `force` — are rejected by the type checker instead of warned about at runtime; delete them.
+Released from `master` by [semantic-release](https://semantic-release.gitbook.io/) on
+every merge, so commit messages follow
+[Conventional Commits](https://www.conventionalcommits.org/). The changelog is the
+[GitHub releases page](https://github.com/capralifecycle/cdk-snapshot/releases).
 
 ## License
 

package/lib/matcher.d.ts

@@ -6,6 +6,13 @@ export interface ExpectLike {
         toMatchSnapshot(propertyMatchers?: Record<string, unknown>): void;
     };
     extend(matchers: Record<string, unknown>): void;
+    /** Jest and Vitest track assertion calls here; Bun has neither method. */
+    getState?(): {
+        assertionCalls: number;
+    };
+    setState?(state: {
+        assertionCalls: number;
+    }): void;
 }
 export type TemplateFn = (stack: Stack, options?: CdkTemplateOptions) => Record<string, unknown>;
 /**

package/lib/matcher.js

@@ -11,6 +11,7 @@ export function registerCdkMatcher(expect, cdkTemplate) {
                 throw new Error("toMatchCdkSnapshot cannot be negated with `.not`.");
             }
             const { propertyMatchers, ...templateOptions } = options;
+            const assertionCalls = expect.getState?.().assertionCalls;
             const assertion = expect(cdkTemplate(received, templateOptions));
             if (propertyMatchers) {
                 assertion.toMatchSnapshot(propertyMatchers);
@@ -18,6 +19,9 @@ export function registerCdkMatcher(expect, cdkTemplate) {
             else {
                 assertion.toMatchSnapshot();
             }
+            // The nested snapshot assertion must not count towards `expect.assertions()`.
+            if (assertionCalls !== undefined)
+                expect.setState?.({ assertionCalls });
             return { pass: true, message: () => "" };
         },
     });

package/lib/node.d.ts

@@ -2,7 +2,7 @@ export { cdkTemplate } from "./index.js";
 export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
 /**
  * Aligns `node:test` with the snapshot location and serialization the other
- * runners use, so one set of snapshot files serves all of them.
+ * runners use, so its snapshots record templates the same way theirs do.
  *
  * Call once, before any test runs.
  */

package/lib/node.js

@@ -4,7 +4,7 @@ import { serialize } from "./serialize.js";
 export { cdkTemplate } from "./index.js";
 /**
  * Aligns `node:test` with the snapshot location and serialization the other
- * runners use, so one set of snapshot files serves all of them.
+ * runners use, so its snapshots record templates the same way theirs do.
  *
  * Call once, before any test runs.
  */

package/lib/normalize.js

@@ -1,7 +1,7 @@
 import { anyObject } from "./placeholder.js";
 const currentVersionRegex = /^(.+CurrentVersion[0-9A-F]{8})[0-9a-f]{32}$/;
 const pipelineCdkAssetsRegex = /cdk-assets\s+--path\s+\\"([^\\/]+)\/.+?assets\.json\\"\s+--verbose\s+publish\s+\\"(.+?)\\"/g;
-const assetDestinationRegex = /:(.*)$/;
+const assetDestinationRegex = /:(.*?)(?:-[0-9a-f]{8})?$/;
 const maskedVersionSuffix = "x".repeat(32);
 /**
  * Returns a copy of `template` with the configured normalizations applied. The
@@ -73,8 +73,9 @@ function maskCurrentVersions(tree) {
     });
 }
 /**
- * `cdk-assets ... publish "<hash>:<destination>"` — the hash changes on every
- * synth, the destination does not.
+ * `cdk-assets ... publish "<hash>:<account>-<region>-<suffix>"` — the hash and
+ * the 8-hex suffix follow the asset's content, the account and region do not.
+ * CDK versions before the suffix emit `<hash>:<account>-<region>`.
  */
 function maskPipelineAssets(tree) {
     transformStrings(tree, (value) => value.replace(pipelineCdkAssetsRegex, (_match, assemblyDir, asset) => {

package/lib/options.d.ts

@@ -1,7 +1,13 @@
 export interface CdkTemplateOptions {
     /**
-     * Replace asset-derived values — Lambda `Code`, container `Image`, and the
-     * template parameters carrying asset hashes — with {@link anyObject}.
+     * Replace every resource's `Code` property, every container definition's
+     * `Image`, and the whole `Parameters` block with
+     * {@link CdkTemplateOptions.assetPlaceholder}.
+     *
+     * Assets elsewhere, such as Lambda layers, keep their hash. A function using
+     * `currentVersion` also needs
+     * {@link CdkTemplateOptions.ignoreCurrentVersion}, since the version's
+     * logical ID hashes the code.
      */
     ignoreAssets?: boolean;
     /**
@@ -13,9 +19,15 @@ export interface CdkTemplateOptions {
     ignoreCurrentVersion?: boolean;
     /** Drop template and resource `Metadata`. */
     ignoreMetadata?: boolean;
-    /** Drop `Tags` from resource properties. */
+    /**
+     * Drop each resource's `Tags` property. Tags nested deeper, such as a launch
+     * template's `TagSpecifications`, are kept.
+     */
     ignoreTags?: boolean;
-    /** Mask asset paths and IDs inside CDK Pipelines `cdk-assets` commands. */
+    /**
+     * Mask asset paths, IDs and destination suffixes inside CDK Pipelines
+     * `cdk-assets` commands.
+     */
     ignorePipelineAssets?: boolean;
     /** Keep only resources of these CloudFormation types. */
     subsetResourceTypes?: string[];

package/lib/placeholder.d.ts

@@ -1,5 +1,6 @@
 /**
- * Stand-in for values that change on every synth, such as asset hashes.
+ * Stand-in for asset-derived values, which change whenever an asset's content
+ * does.
  * Serializes as `Any<Object>` so snapshots match across test runners.
  *
  * Bun accepts only matchers built by its own `expect`; the Bun entry point

package/lib/placeholder.js

@@ -1,5 +1,6 @@
 /**
- * Stand-in for values that change on every synth, such as asset hashes.
+ * Stand-in for asset-derived values, which change whenever an asset's content
+ * does.
  * Serializes as `Any<Object>` so snapshots match across test runners.
  *
  * Bun accepts only matchers built by its own `expect`; the Bun entry point

package/lib/serialize.d.ts

@@ -1,5 +1,6 @@
 /**
- * Serializes a value the way Jest, Vitest and Bun serialize snapshots.
+ * Serializes a value the way Jest and Vitest serialize snapshots. Bun matches
+ * too, except for multi-line strings nested inside the value.
  *
  * `node:test` formats with `JSON.stringify` by default, which would make its
  * snapshots incompatible with the other runners.

package/lib/serialize.js

@@ -1,6 +1,7 @@
 import { format, plugins } from "pretty-format";
 /**
- * Serializes a value the way Jest, Vitest and Bun serialize snapshots.
+ * Serializes a value the way Jest and Vitest serialize snapshots. Bun matches
+ * too, except for multi-line strings nested inside the value.
  *
  * `node:test` formats with `JSON.stringify` by default, which would make its
  * snapshots incompatible with the other runners.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@liflig/cdk-snapshot",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Normalizes synthesized AWS CDK stacks for snapshot testing",
   "type": "module",
   "license": "MIT",
   "author": "Liflig",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.13.0"
   },
   "repository": {
     "type": "git",
@@ -84,13 +84,13 @@
     "pretty-format": "^29.7.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.10",
+    "@biomejs/biome": "2.5.11",
     "@types/bun": "1.4.0",
     "@types/jest": "30.0.0",
     "@types/node": "24.13.3",
-    "aws-cdk-lib": "2.266.0",
+    "aws-cdk-lib": "2.267.0",
     "constructs": "10.8.1",
-    "jest": "30.4.2",
+    "jest": "30.5.0",
     "semantic-release": "25.0.9",
     "typescript": "7.0.2",
     "vitest": "4.1.11"