feat(assertions): add stack tagging assertions (#29247)

Adds a `Tag` class to the assertions library that permits assertions against tags on synthesized CDK stacks.

Tags on AWS resources can be checked via assertions with the Template class, but since stack tags only appear on the cloud assembly manifest as a sibling of the template, a separate assertion mechanism is required.

> [!NOTE]
> Previously submitted as #27633, which was closed automatically while waiting for review.
>
> This PR is complete to the best of my knowledge, needing only an exemption from integration tests. As far as I can tell, this area of the library has no integration tests directly associated.

### API

```ts
class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasValues(props: any): void;
  public all(): { [key: string]: string };
}
```

### Usage

This new class permits tests of the form:

```ts
import { App, Stack } from 'aws-cdk-lib';
import { Tags } from 'aws-cdk-lib/assertions';

const app = new App();
const stack = new Stack(app, 'MyStack', {
  tags: {
    'tag-name': 'tag-value'
  }
});

const tags = Tags.fromStack(stack);

// using a default 'objectLike' Matcher
tags.hasValues({
  'tag-name': 'tag-value'
});

// or another Matcher
tags.hasValues({
  'tag-name': Match.anyValue()
});
```

You can also get the set of tags to test them in other ways:

```ts
tags.all()
```

## Issues

### No tags case

One might expect that the case where no tags are present would match `undefined` or `null`, but since the Cloud Assembly API defaults tags to `{}` when none are present, this isn't possible. It's also not practical to directly test the `artifact.manifest.properties.tags` value directly, as there is a legacy case that the API handles. This means that the `artifact.tags` property is the best value to check against.

The tests for this PR show that matching with `Match.absent()` will fail when there are no tags, but testing against the empty object will succeed.

I think that this behaviour (defaulting to empty) will be OK, but potentially require a callout on the assertion method.

### API method naming

The current suggested API went through some evolution, starting with:

```ts
class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasTags(props: any): void;
  public getTags():  { [key: string]: string };
}
```
But this stuttered, and `getTags()` wasn't compatible with Java.

I considered:

```ts
class Tags {
  public static fromStack(stack: Stack) : Tags;
  public hasValues(props: any): void;
  public values():  { [key: string]: string };
}
```
and
```ts
class Tags {
  public static fromStack(stack: Stack) : Tags;
  public has(props: any): void;
  public all():  { [key: string]: string };
}
```

... before settling on a mix of the two. I think the current iteration fits with the rest of the `assertions` API and makes sense by itself, but very open to changes.

Closes #27620.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

packages/aws-cdk-lib/assertions/README.md

@@ -595,3 +595,57 @@ Annotations.fromStack(stack).hasError(
   Match.stringLikeRegexp('.*Foo::Bar.*'),
 );
 ```
+
+## Asserting Stack tags
+
+Tags applied to a `Stack` are not part of the rendered template: instead, they
+are included as properties in the Cloud Assembly Manifest. To test that stacks
+are tagged as expected, simple assertions can be written.
+
+Given the following setup:
+
+```ts nofixture
+import { App, Stack } from 'aws-cdk-lib';
+import { Tags } from 'aws-cdk-lib/assertions';
+
+const app = new App();
+const stack = new Stack(app, 'MyStack', {
+  tags: {
+    'tag-name': 'tag-value',
+  },
+});
+```
+
+It is possible to test against these values:
+
+```ts
+const tags = Tags.fromStack(stack);
+
+// using a default 'objectLike' Matcher
+tags.hasValues({
+  'tag-name': 'tag-value',
+});
+
+// ... with Matchers embedded
+tags.hasValues({
+  'tag-name': Match.stringLikeRegexp('value'),
+});
+
+// or another object Matcher at the top level
+tags.hasValues(Match.objectEquals({
+  'tag-name': Match.anyValue(),
+}));
+```
+
+When tags are not defined on the stack, it is represented as an empty object
+rather than `undefined`. To make this more obvious, there is a `hasNone()`
+method that can be used in place of `Match.exactly({})`. If `Match.absent()` is
+passed, an error will result.
+
+```ts
+// no tags present
+Tags.fromStack(stack).hasNone();
+
+// don't use absent() at the top level, it won't work
+expect(() => { Tags.fromStack(stack).hasValues(Match.absent()); }).toThrow(/will never match/i);
+```

packages/aws-cdk-lib/assertions/lib/index.ts

@@ -2,4 +2,5 @@ export * from './capture';
 export * from './template';
 export * from './match';
 export * from './matcher';
-export * from './annotations';
+export * from './annotations';
+export * from './tags';

packages/aws-cdk-lib/assertions/lib/tags.ts

@@ -0,0 +1,91 @@
+import { Match } from './match';
+import { Matcher } from './matcher';
+import { Stack, Stage } from '../../core';
+
+type ManifestTags = { [key: string]: string };
+
+/**
+ * Allows assertions on the tags associated with a synthesized CDK stack's
+ * manifest. Stack tags are not part of the synthesized template, so can only be
+ * checked from the manifest in this manner.
+ */
+export class Tags {
+  /**
+   * Find tags associated with a synthesized CDK `Stack`.
+   *
+   * @param stack the CDK Stack to find tags on.
+   */
+  public static fromStack(stack: Stack): Tags {
+    return new Tags(getManifestTags(stack));
+  }
+
+  private readonly _tags: ManifestTags;
+
+  private constructor(tags: ManifestTags) {
+    this._tags = tags;
+  }
+
+  /**
+   * Assert that the given Matcher or object matches the tags associated with
+   * the synthesized CDK Stack's manifest.
+   *
+   * @param tags the expected set of tags. This should be a
+   * string or Matcher object.
+   */
+  public hasValues(tags: any): void {
+    // The Cloud Assembly API defaults tags to {} when undefined. Using
+    // Match.absent() will not work as the caller expects, so we push them
+    // towards a working API.
+    if (Matcher.isMatcher(tags) && tags.name === 'absent') {
+      throw new Error(
+        'Match.absent() will never match Tags because "{}" is the default value. Use Tags.hasNone() instead.',
+      );
+    }
+
+    const matcher = Matcher.isMatcher(tags) ? tags : Match.objectLike(tags);
+
+    const result = matcher.test(this.all());
+    if (result.hasFailed()) {
+      throw new Error(
+        'Stack tags did not match as expected:\n' + result.renderMismatch(),
+      );
+    }
+  }
+
+  /**
+   * Assert that the there are no tags associated with the synthesized CDK
+   * Stack's manifest.
+   *
+   * This is a convenience method over `hasValues(Match.exact({}))`, and is
+   * present because the more obvious method of detecting no tags
+   * (`Match.absent()`) will not work. Manifests default the tag set to an empty
+   * object.
+   */
+  public hasNone(): void {
+    this.hasValues(Match.exact({}));
+  }
+
+  /**
+   * Get the tags associated with the manifest. This will be an empty object if
+   * no tags were supplied.
+   *
+   * @returns The tags associated with the stack's synthesized manifest.
+   */
+  public all(): ManifestTags {
+    return this._tags;
+  }
+}
+
+function getManifestTags(stack: Stack): ManifestTags {
+  const root = stack.node.root;
+  if (!Stage.isStage(root)) {
+    throw new Error('unexpected: all stacks must be part of a Stage or an App');
+  }
+
+  // synthesis is not forced: the stack will only be synthesized once regardless
+  // of the number of times this is called.
+  const assembly = root.synth();
+
+  const artifact = assembly.getStackArtifact(stack.artifactId);
+  return artifact.tags;
+}

packages/aws-cdk-lib/assertions/test/tags.test.ts

@@ -0,0 +1,136 @@
+import { App, Stack } from '../../core';
+import { Match, Tags } from '../lib';
+
+describe('Tags', () => {
+  let app: App;
+
+  beforeEach(() => {
+    app = new App();
+  });
+
+  describe('hasValues', () => {
+    test('simple match', () => {
+      const stack = new Stack(app, 'stack', {
+        tags: { 'tag-one': 'tag-one-value' },
+      });
+      const tags = Tags.fromStack(stack);
+      tags.hasValues({
+        'tag-one': 'tag-one-value',
+      });
+    });
+
+    test('with matchers', () => {
+      const stack = new Stack(app, 'stack', {
+        tags: { 'tag-one': 'tag-one-value' },
+      });
+      const tags = Tags.fromStack(stack);
+      tags.hasValues({
+        'tag-one': Match.anyValue(),
+      });
+    });
+
+    describe('given multiple tags', () => {
+      const stack = new Stack(app, 'stack', {
+        tags: {
+          'tag-one': 'tag-one-value',
+          'tag-two': 'tag-2-value',
+          'tag-three': 'tag-3-value',
+          'tag-four': 'tag-4-value',
+        },
+      });
+      const tags = Tags.fromStack(stack);
+
+      test('partial match succeeds', ()=>{
+        tags.hasValues({
+          'tag-one': Match.anyValue(),
+        });
+      });
+
+      test('complex match succeeds', ()=>{
+        tags.hasValues(Match.objectEquals({
+          'tag-one': Match.anyValue(),
+          'non-existent': Match.absent(),
+          'tag-three': Match.stringLikeRegexp('-3-'),
+          'tag-two': 'tag-2-value',
+          'tag-four': Match.anyValue(),
+        }));
+      });
+    });
+
+    test('no tags with absent matcher will fail', () => {
+      const stack = new Stack(app, 'stack');
+      const tags = Tags.fromStack(stack);
+
+      // Since the tags are defaulted to the empty object, using the `absent()`
+      // matcher will never work, instead throwing an error.
+      expect(() => tags.hasValues(Match.absent())).toThrow(
+        /^match.absent\(\) will never match Tags/i,
+      );
+    });
+
+    test('no tags matches empty object successfully', () => {
+      const stack = new Stack(app, 'stack');
+      const tags = Tags.fromStack(stack);
+
+      tags.hasValues(Match.exact({}));
+    });
+
+    test('no match', () => {
+      const stack = new Stack(app, 'stack', {
+        tags: { 'tag-one': 'tag-one-value' },
+      });
+      const tags = Tags.fromStack(stack);
+
+      expect(() =>
+        tags.hasValues({
+          'tag-one': 'mismatched value',
+        }),
+      ).toThrow(/Expected mismatched value but received tag-one-value/);
+    });
+  });
+
+  describe('hasNone', () => {
+    test.each([undefined, {}])('matches empty: %s', (v) => {
+      const stack = new Stack(app, 'stack', { tags: v });
+      const tags = Tags.fromStack(stack);
+
+      tags.hasNone();
+    });
+
+    test.each(<Record<string, string>[]>[
+      { ['tagOne']: 'single-tag' },
+      { ['tagOne']: 'first-value', ['tag-two']: 'second-value' },
+    ])('does not match with values: %s', (v) => {
+      const stack = new Stack(app, 'stack', { tags: v });
+      const tags = Tags.fromStack(stack);
+
+      expect(() => tags.hasNone()).toThrow(/unexpected key/i);
+    });
+  });
+
+  describe('all', () => {
+    test('simple match', () => {
+      const stack = new Stack(app, 'stack', {
+        tags: { 'tag-one': 'tag-one-value' },
+      });
+      const tags = Tags.fromStack(stack);
+      expect(tags.all()).toStrictEqual({
+        'tag-one': 'tag-one-value',
+      });
+    });
+
+    test('no tags', () => {
+      const stack = new Stack(app, 'stack');
+      const tags = Tags.fromStack(stack);
+
+      expect(tags.all()).toStrictEqual({});
+    });
+
+    test('empty tags', () => {
+      const stack = new Stack(app, 'stack', { tags: {} });
+      const tags = Tags.fromStack(stack);
+
+      expect(tags.all()).toStrictEqual({});
+    });
+  });
+});

packages/aws-cdk-lib/rosetta/assertions/default.ts-fixture

@@ -1,9 +1,10 @@
 import { Construct } from 'constructs';
 import { Aspects, CfnResource, Stack } from 'aws-cdk-lib';
-import { Annotations, Capture, Match, Template } from 'aws-cdk-lib/assertions';
+import { Annotations, Capture, Match, Tags, Template } from 'aws-cdk-lib/assertions';
 
 interface Expect {
   toEqual(what: any): void;
+  toThrow(what?: any): void;
 }
 
 declare function expect(what: any): Expect;