@liflig/cdk-snapshot 1.0.1 → 1.1.0

package/README.md

@@ -2,27 +2,43 @@
 
 [![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, with a CommonJS build of the root and Jest entry points for
+CommonJS Jest projects.
 
 ## 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 +75,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 +97,24 @@ test("my stack", () => {
 });
 ```
 
-The Jest entry point uses the global `expect`, so it throws on import if Jest is configured with `injectGlobals: false`.
+Instead of importing it in each test file, the entry point can be listed once in
+`setupFilesAfterEnv`.
+
+A CommonJS test file, including one ts-jest or babel-jest compiles to CommonJS, loads the
+CommonJS build and needs no configuration. An ESM test file loads the ESM build, and
+needs Jest's ESM support enabled as any ESM test file does:
+
+```sh
+NODE_OPTIONS=--experimental-vm-modules jest
+```
+
+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 +122,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 +206,47 @@ 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, Jest once as ESM and once as CommonJS, 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, or the `setupFilesAfterEnv` entry. Call sites and `.snap` files stay
+as they are, since the options, their defaults and the serialization all match, and the
+Jest configuration stays as it is, CommonJS or ESM.
 
 ```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.
+
+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/cjs/index.d.ts

@@ -0,0 +1,14 @@
+import type { Stack } from "aws-cdk-lib";
+import type { CdkTemplateOptions } from "./options.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+export { anyObject } from "./placeholder.js";
+/**
+ * Synthesizes `stack` to a CloudFormation template with deployment noise
+ * removed, ready to hand to a snapshot assertion.
+ *
+ * The stack is left untouched, so it can be synthesized again with different
+ * options.
+ *
+ * Bun users should import this from `@liflig/cdk-snapshot/bun` instead.
+ */
+export declare function cdkTemplate(stack: Stack, options?: CdkTemplateOptions): Record<string, unknown>;

package/lib/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anyObject = void 0;
+exports.cdkTemplate = cdkTemplate;
+const assertions_1 = require("aws-cdk-lib/assertions");
+const normalize_js_1 = require("./normalize.js");
+var placeholder_js_1 = require("./placeholder.js");
+Object.defineProperty(exports, "anyObject", { enumerable: true, get: function () { return placeholder_js_1.anyObject; } });
+/**
+ * Synthesizes `stack` to a CloudFormation template with deployment noise
+ * removed, ready to hand to a snapshot assertion.
+ *
+ * The stack is left untouched, so it can be synthesized again with different
+ * options.
+ *
+ * Bun users should import this from `@liflig/cdk-snapshot/bun` instead.
+ */
+function cdkTemplate(stack, options = {}) {
+    return (0, normalize_js_1.normalize)(assertions_1.Template.fromStack(stack).toJSON(), options);
+}

package/lib/cjs/jest.d.ts

@@ -0,0 +1,10 @@
+import type { CdkSnapshotOptions } from "./options.js";
+export { cdkTemplate } from "./index.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+declare global {
+    namespace jest {
+        interface Matchers<R, T = {}> {
+            toMatchCdkSnapshot(options?: CdkSnapshotOptions): R;
+        }
+    }
+}

package/lib/cjs/jest.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cdkTemplate = void 0;
+const index_js_1 = require("./index.js");
+const matcher_js_1 = require("./matcher.js");
+var index_js_2 = require("./index.js");
+Object.defineProperty(exports, "cdkTemplate", { enumerable: true, get: function () { return index_js_2.cdkTemplate; } });
+(0, matcher_js_1.registerCdkMatcher)((0, matcher_js_1.requireExpect)("Jest", globalThis.expect), index_js_1.cdkTemplate);

package/lib/cjs/matcher.d.ts

@@ -0,0 +1,29 @@
+import type { Stack } from "aws-cdk-lib";
+import type { CdkTemplateOptions } from "./options.js";
+/** The part of a runner's `expect` this matcher relies on. */
+export interface ExpectLike {
+    (actual: unknown): {
+        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>;
+/**
+ * Registers `toMatchCdkSnapshot` on the runner's `expect`.
+ *
+ * The matcher delegates to the runner's own snapshot assertion, so snapshots
+ * keep the naming and format that runner already produces.
+ */
+export declare function registerCdkMatcher(expect: ExpectLike, cdkTemplate: TemplateFn): void;
+/**
+ * Narrows the `expect` a runner injected to the shape the matcher needs, or
+ * explains what to do when the runner injected nothing.
+ */
+export declare function requireExpect(runner: string, injected: unknown): ExpectLike;

package/lib/cjs/matcher.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCdkMatcher = registerCdkMatcher;
+exports.requireExpect = requireExpect;
+/**
+ * Registers `toMatchCdkSnapshot` on the runner's `expect`.
+ *
+ * The matcher delegates to the runner's own snapshot assertion, so snapshots
+ * keep the naming and format that runner already produces.
+ */
+function registerCdkMatcher(expect, cdkTemplate) {
+    expect.extend({
+        toMatchCdkSnapshot(received, options = {}) {
+            if (this?.isNot) {
+                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);
+            }
+            else {
+                assertion.toMatchSnapshot();
+            }
+            // The nested snapshot assertion must not count towards `expect.assertions()`.
+            if (assertionCalls !== undefined)
+                expect.setState?.({ assertionCalls });
+            return { pass: true, message: () => "" };
+        },
+    });
+}
+/**
+ * Narrows the `expect` a runner injected to the shape the matcher needs, or
+ * explains what to do when the runner injected nothing.
+ */
+function requireExpect(runner, injected) {
+    const candidate = injected;
+    if (typeof candidate?.extend !== "function") {
+        throw new Error(`@liflig/cdk-snapshot: ${runner} did not inject a global \`expect\`. Enable global injection, or use cdkTemplate() directly.`);
+    }
+    return candidate;
+}

package/lib/cjs/normalize.d.ts

@@ -0,0 +1,13 @@
+import type { CdkTemplateOptions } from "./options.js";
+/** A synthesized CloudFormation template. */
+export type Template = Record<string, any>;
+/**
+ * Returns a copy of `template` with the configured normalizations applied. The
+ * argument is left untouched: `Template.fromStack` hands out the assembly's
+ * cached template object, so mutating it would corrupt every later assertion
+ * on the same stack.
+ *
+ * Step order is significant: earlier steps can remove structures that later
+ * ones inspect.
+ */
+export declare function normalize(template: Template, options?: CdkTemplateOptions): Template;

package/lib/cjs/normalize.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = normalize;
+const placeholder_js_1 = require("./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 = /:(.*?)(?:-[0-9a-f]{8})?$/;
+const maskedVersionSuffix = "x".repeat(32);
+/**
+ * Returns a copy of `template` with the configured normalizations applied. The
+ * argument is left untouched: `Template.fromStack` hands out the assembly's
+ * cached template object, so mutating it would corrupt every later assertion
+ * on the same stack.
+ *
+ * Step order is significant: earlier steps can remove structures that later
+ * ones inspect.
+ */
+function normalize(template, options = {}) {
+    const { ignoreAssets = false, ignoreBootstrapVersion = true, ignoreCurrentVersion = false, ignoreMetadata = false, ignoreTags = false, ignorePipelineAssets = false, subsetResourceTypes, subsetResourceKeys, assetPlaceholder = placeholder_js_1.anyObject, } = options;
+    const result = structuredClone(template);
+    if (ignoreBootstrapVersion)
+        stripBootstrapVersion(result);
+    if (ignoreAssets)
+        stripAssets(result, assetPlaceholder);
+    if (ignoreCurrentVersion)
+        maskCurrentVersions(result);
+    if (ignorePipelineAssets)
+        maskPipelineAssets(result);
+    if (subsetResourceTypes) {
+        keepResources(result, (_key, resource) => subsetResourceTypes.includes(resource?.Type));
+    }
+    if (subsetResourceKeys) {
+        keepResources(result, (key) => subsetResourceKeys.includes(key));
+    }
+    if (ignoreMetadata)
+        stripMetadata(result);
+    if (ignoreTags)
+        stripTags(result);
+    return result;
+}
+function stripBootstrapVersion(template) {
+    const { Parameters, Rules } = template;
+    if (Parameters) {
+        delete Parameters.BootstrapVersion;
+        if (Object.keys(Parameters).length === 0)
+            delete template.Parameters;
+    }
+    if (Rules) {
+        delete Rules.CheckBootstrapVersion;
+        if (Object.keys(Rules).length === 0)
+            delete template.Rules;
+    }
+}
+function stripAssets(template, placeholder) {
+    if (!template.Resources)
+        return;
+    if (template.Parameters) {
+        template.Parameters = placeholder;
+    }
+    for (const resource of Object.values(template.Resources)) {
+        const properties = resource?.Properties;
+        if (!properties)
+            continue;
+        if (properties.Code) {
+            properties.Code = placeholder;
+        }
+        for (const definition of properties.ContainerDefinitions ?? []) {
+            definition.Image = placeholder;
+        }
+    }
+}
+function maskCurrentVersions(tree) {
+    transformStrings(tree, (value) => {
+        const match = currentVersionRegex.exec(value);
+        return match ? `${match[1]}${maskedVersionSuffix}` : value;
+    });
+}
+/**
+ * `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) => {
+        const destination = assetDestinationRegex.exec(asset)?.[1] || "<ASSET_ID>";
+        return `cdk-assets --path "<${assemblyDir}>" --verbose publish "${destination}"`;
+    }));
+}
+/** Rewrites every string in `tree`, object keys included, in place. */
+function transformStrings(tree, transform) {
+    if (tree == null || typeof tree !== "object")
+        return;
+    if (Array.isArray(tree)) {
+        for (let i = 0; i < tree.length; i++) {
+            const value = tree[i];
+            if (typeof value === "string") {
+                tree[i] = transform(value);
+            }
+            else {
+                transformStrings(value, transform);
+            }
+        }
+        return;
+    }
+    const record = tree;
+    for (const [key, value] of Object.entries(record)) {
+        const newKey = transform(key);
+        if (newKey !== key) {
+            record[newKey] = value;
+            delete record[key];
+        }
+        if (typeof value === "string") {
+            record[newKey] = transform(value);
+        }
+        else {
+            transformStrings(value, transform);
+        }
+    }
+}
+function keepResources(template, keep) {
+    if (!template.Resources)
+        return;
+    for (const [key, resource] of Object.entries(template.Resources)) {
+        if (!keep(key, resource)) {
+            delete template.Resources[key];
+        }
+    }
+}
+function stripMetadata(template) {
+    delete template.Metadata;
+    for (const resource of Object.values(template.Resources ?? {})) {
+        delete resource?.Metadata;
+    }
+}
+function stripTags(template) {
+    for (const resource of Object.values(template.Resources ?? {})) {
+        const properties = resource?.Properties;
+        if (properties?.Tags)
+            delete properties.Tags;
+    }
+}

package/lib/cjs/options.d.ts

@@ -0,0 +1,49 @@
+export interface CdkTemplateOptions {
+    /**
+     * 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;
+    /**
+     * Drop the CDK-managed `BootstrapVersion` parameter and its check rule.
+     * Defaults to `true`.
+     */
+    ignoreBootstrapVersion?: boolean;
+    /** Mask the content hash suffix on Lambda `CurrentVersion` logical IDs. */
+    ignoreCurrentVersion?: boolean;
+    /** Drop template and resource `Metadata`. */
+    ignoreMetadata?: boolean;
+    /**
+     * Drop each resource's `Tags` property. Tags nested deeper, such as a launch
+     * template's `TagSpecifications`, are kept.
+     */
+    ignoreTags?: boolean;
+    /**
+     * Mask asset paths, IDs and destination suffixes inside CDK Pipelines
+     * `cdk-assets` commands.
+     */
+    ignorePipelineAssets?: boolean;
+    /** Keep only resources of these CloudFormation types. */
+    subsetResourceTypes?: string[];
+    /** Keep only resources with these logical IDs. */
+    subsetResourceKeys?: string[];
+    /**
+     * Token substituted for asset-derived values. Defaults to a matcher
+     * serializing as `Any<Object>`; the Bun entry point overrides it.
+     */
+    assetPlaceholder?: unknown;
+}
+/** {@link CdkTemplateOptions} plus what only the snapshot matcher can apply. */
+export interface CdkSnapshotOptions extends CdkTemplateOptions {
+    /**
+     * Property matchers handed to the runner's snapshot assertion, for values
+     * the normalizations do not cover.
+     */
+    propertyMatchers?: Record<string, unknown>;
+}

package/lib/cjs/options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/cjs/placeholder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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
+ * substitutes one.
+ */
+export declare const anyObject: unknown;

package/lib/cjs/placeholder.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anyObject = void 0;
+/**
+ * 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
+ * substitutes one.
+ */
+exports.anyObject = {
+    $$typeof: Symbol.for("jest.asymmetricMatcher"),
+    asymmetricMatch: (actual) => typeof actual === "object" && actual !== null,
+    toString: () => "Any",
+    getExpectedType: () => "Object",
+    toAsymmetricMatcher: () => "Any<Object>",
+};

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.1",
+  "version": "1.1.0",
   "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",
@@ -28,12 +28,18 @@
     "bun",
     "node-test"
   ],
-  "main": "./lib/index.js",
-  "types": "./lib/index.d.ts",
+  "main": "./lib/cjs/index.js",
+  "types": "./lib/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js",
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      },
       "default": "./lib/index.js"
     },
     "./bun": {
@@ -42,8 +48,14 @@
       "default": "./lib/bun.js"
     },
     "./jest": {
-      "types": "./lib/jest.d.ts",
-      "import": "./lib/jest.js",
+      "import": {
+        "types": "./lib/jest.d.ts",
+        "default": "./lib/jest.js"
+      },
+      "require": {
+        "types": "./lib/cjs/jest.d.ts",
+        "default": "./lib/cjs/jest.js"
+      },
       "default": "./lib/jest.js"
     },
     "./node": {
@@ -62,7 +74,7 @@
     "lib/**/*"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > lib/cjs/package.json",
     "test": "bun test ./test",
     "snapshots": "bun test ./test --update-snapshots",
     "typecheck": "tsc -p tsconfig.check.json",