feat(assertions): added getResourceId method to Template (#33521)

### Reason for this change

Sometimes you want to correlate how cloudformation resources correlate to each other.
CDK synthesizes the template expectedly with `Ref` and `Fn:GetAtt`.

Currently you'll have to do something like this to verify that a bucketpolicy is attached to the correct bucket:
```ts
const resources = template.findResources('AWS::S3::Bucket', {
  Properties: {
    BucketName: 'my-bucket',
  }
})

const keys = Object.keys(resources)
if (keys.length === 0) {
    throw new Error('Resource not found.')
}
if (keys.length !== 1) {
    throw new Error('Resource is not unique.')
}
const bucket = keys[0]

template.hasResourceProperties('AWS::S3::BucketPolicy', {
  Bucket: {
    Ref: bucket,
  },
 // ....
})

```

### Description of changes

Added method `getResourceId` on `Template` to retrieve a distinct match's resource id.
```ts
// throws AssertionError on none or multiple matches
const bucket = template.getResourceId('AWS::S3::Bucket', {
  Properties: {
    BucketName: 'my-bucket',
  }
})

template.hasResourceProperties('AWS::S3::BucketPolicy', {
  Bucket: {
    Ref: bucket,
  },
  // ....
})

```


### Description of how you validated changes
Unit tests. Integration tests not applicable.

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*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

@@ -135,6 +135,36 @@ Beyond assertions, the module provides APIs to retrieve matching resources.
 The `findResources()` API is complementary to the `hasResource()` API, except,
 instead of asserting its presence, it returns the set of matching resources.
 
+Similarly, the `getResourceId()` API is complementary to the `findResources()` API,
+except it expects only one matching resource, and returns the matched resource's resource id.
+Useful for asserting that certain cloudformation resources correlate expectedly.
+
+```ts
+// Assert that a certain bucket denies unsecure communication
+const bucket = template.getResourceId('AWS::S3::Bucket', {
+  Properties: {
+    BucketName: 'my-bucket',
+  }
+})
+
+template.hasResourceProperties('AWS::S3::BucketPolicy', {
+  Bucket: {
+    Ref: bucket,
+  },
+  PolicyDocument: {
+    Statement: [
+      {
+        Effect: 'Deny',
+        Action: 's3:*',
+        Principal: { AWS: '*' },
+        Condition: { Bool: { 'aws:SecureTransport': 'false' } },
+      },
+    ],
+  }
+})
+
+```
+
 By default, the `hasResource()` and `hasResourceProperties()` APIs perform deep
 partial object matching. This behavior can be configured using matchers.
 See subsequent section on [special matchers](#special-matchers).

packages/aws-cdk-lib/assertions/lib/private/resources.ts

@@ -1,6 +1,6 @@
 import { Match, Matcher } from '..';
 import { AbsentMatch } from './matchers/absent';
-import { formatAllMismatches, matchSection, formatSectionMatchFailure } from './section';
+import { formatAllMismatches, matchSection, formatSectionMatchFailure, formatAllMatches } from './section';
 import { Resource, Template } from './template';
 
 export function findResources(template: Template, type: string, props: any = {}): { [key: string]: { [key: string]: any } } {
@@ -14,6 +14,30 @@ export function findResources(template: Template, type: string, props: any = {})
   return result.matches;
 }
 
+export function getResourceId(template: Template, type: string, props: any = {}): { resourceId?: string; matchError?: string } {
+  const section = template.Resources ?? {};
+  const result = matchSection(filterType(section, type), props);
+
+  if (!result.match) {
+    return {
+      matchError: formatSectionMatchFailure(`resources with type ${type}`, result),
+    };
+  }
+
+  const resourceIds = Object.keys(result.matches);
+
+  if (resourceIds.length !== 1) {
+    return {
+      matchError: [
+        `Template has ${resourceIds.length} matches, expected only one.`,
+        formatAllMatches(result.matches),
+      ].join('\n'),
+    };
+  }
+
+  return { resourceId: resourceIds[0] };
+}
+
 export function allResources(template: Template, type: string, props: any): string | void {
   const section = template.Resources ?? {};
   const result = matchSection(filterType(section, type), props);

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

@@ -7,7 +7,7 @@ import { checkTemplateForCyclicDependencies } from './private/cyclic';
 import { findMappings, hasMapping } from './private/mappings';
 import { findOutputs, hasOutput } from './private/outputs';
 import { findParameters, hasParameter } from './private/parameters';
-import { allResources, allResourcesProperties, countResources, countResourcesProperties, findResources, hasResource, hasResourceProperties } from './private/resources';
+import { allResources, allResourcesProperties, countResources, countResourcesProperties, findResources, getResourceId, hasResource, hasResourceProperties } from './private/resources';
 import { Template as TemplateType } from './private/template';
 import { Stack, Stage } from '../../core';
 import { AssertionError } from './private/error';
@@ -134,6 +134,28 @@ export class Template {
     return findResources(this.template, type, props);
   }
 
+  /**
+   * Get the Resource ID of a matching resource, expects only to find one match.
+   * Throws AssertionError if none or multiple resources were found.
+   * @param type the resource type; ex: `AWS::S3::Bucket`
+   * @param props by default, matches all resources with the given type.
+   * @returns The resource id of the matched resource.
+   * Performs a partial match via `Match.objectLike()`.
+   */
+  public getResourceId(type: string, props: any = {}): string {
+    const { resourceId, matchError } = getResourceId(this.template, type, props);
+
+    if (matchError) {
+      throw new AssertionError(matchError);
+    }
+
+    if (!resourceId) {
+      throw new AssertionError('unexpected: resourceId was undefined');
+    }
+
+    return resourceId;
+  }
+
   /**
    * Assert that all resources of the given type contain the given definition in the
    * CloudFormation template.

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

@@ -561,6 +561,114 @@ describe('Template', () => {
     });
   });
 
+  describe('getResourceId', () => {
+    test('matching resource type', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expect(inspect.getResourceId('Foo::Bar')).toEqual('Foo');
+    });
+
+    test('no matching resource type', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Baz',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expectToThrow(
+        () => inspect.getResourceId('Foo::Bar'),
+        ['Template has 0 resources with type Foo::Bar'],
+      );
+    });
+
+    test('matching resource props', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expect(inspect.getResourceId('Foo::Bar', { Properties: { fred: 'waldo' } })).toEqual('Foo');
+    });
+
+    test('no matching resource props', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expectToThrow(
+        () => inspect.getResourceId('Foo::Bar', { Properties: { baz: 'quz' } }),
+        [
+          'Template has 1 resources with type Foo::Bar, but none match as expected',
+          /Expected quz but received qux/,
+        ],
+      );
+    });
+
+    test('multiple matching resources', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', { type: 'Foo::Bar' });
+      new CfnResource(stack, 'Bar', { type: 'Foo::Bar' });
+
+      const inspect = Template.fromStack(stack);
+      expectToThrow(
+        () => inspect.getResourceId('Foo::Bar'),
+        [
+          'Template has 2 matches, expected only one.',
+          /Foo/, /Foo::Bar/,
+          /Bar/, /Foo::Bar/,
+        ],
+      );
+    });
+
+    test('multiple matching resources props', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+      new CfnResource(stack, 'Bar', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expectToThrow(
+        () => inspect.getResourceId('Foo::Bar', { Properties: { baz: 'qux' } }),
+        [
+          'Template has 2 matches, expected only one.',
+          /Foo/, /Foo::Bar/,
+          /Bar/, /Foo::Bar/,
+        ],
+      );
+    });
+
+    test('multiple resources only one match', () => {
+      const stack = new Stack();
+      new CfnResource(stack, 'Foo', {
+        type: 'Foo::Bar',
+        properties: { baz: 'qux', fred: 'waldo' },
+      });
+      new CfnResource(stack, 'Bar', {
+        type: 'Foo::Bar',
+        properties: { bax: 'qux', fred: 'waldo' },
+      });
+
+      const inspect = Template.fromStack(stack);
+      expect(inspect.getResourceId('Foo::Bar', { Properties: { bax: 'qux' } })).toEqual('Bar');
+    });
+  });
+
   describe('allResources', () => {
     test('all resource of type match', () => {
       const stack = new Stack();