feat(assertions): add function for verifying the number of matching r…

…esource properties (#21707)

This PR adds the `Template.resourcePropertiesCountIs()` method for counting the number of resources of a specified type whose `Properties` section matches given properties.

Implements: #21706

----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/main/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

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

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

@@ -76,6 +76,17 @@ in a template.
 template.resourceCountIs('Foo::Bar', 2);
 ```
 
+You can also count the number of resources of a specific type whose `Properties`
+section contains the specified properties:
+
+```ts
+template.resourcePropertiesCountIs('Foo::Bar', {
+ Foo: 'Bar',
+ Baz: 5,
+ Qux: [ 'Waldo', 'Fred' ],
+}, 1);
+```
+
 ## Resource Matching & Retrieval
 
 Beyond resource counting, the module also allows asserting that a resource with

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

@@ -32,11 +32,12 @@ export function hasResource(template: Template, type: string, props: any): strin
 }
 
 export function hasResourceProperties(template: Template, type: string, props: any): string | void {
- // amended needs to be a deep copy to avoid modifying the template.
- let amended = JSON.parse(JSON.stringify(template));
+ let amended = template;
 
  // special case to exclude AbsentMatch because adding an empty Properties object will affect its evaluation.
  if (!Matcher.isMatcher(props) || !(props instanceof AbsentMatch)) {
+ // amended needs to be a deep copy to avoid modifying the template.
+ amended = JSON.parse(JSON.stringify(template));
  amended = addEmptyProperties(amended);
  }
 
@@ -52,6 +53,27 @@ export function countResources(template: Template, type: string): number {
  return Object.entries(types).length;
 }
 
+export function countResourcesProperties(template: Template, type: string, props: any): number {
+ let amended = template;
+
+ // special case to exclude AbsentMatch because adding an empty Properties object will affect its evaluation.
+ if (!Matcher.isMatcher(props) || !(props instanceof AbsentMatch)) {
+ // amended needs to be a deep copy to avoid modifying the template.
+ amended = JSON.parse(JSON.stringify(template));
+ amended = addEmptyProperties(amended);
+ }
+
+ const section = amended.Resources ?? {};
+ const result = matchSection(filterType(section, type), Match.objectLike({
+ Properties: props,
+ }));
+
+ if (result.match) {
+ return Object.keys(result.matches).length;
+ }
+ return 0;
+}
+
 function addEmptyProperties(template: Template): Template {
  let section = template.Resources ?? {};
 

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

@@ -8,7 +8,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 { countResources, findResources, hasResource, hasResourceProperties } from './private/resources';
+import { countResources, countResourcesProperties, findResources, hasResource, hasResourceProperties } from './private/resources';
 import { Template as TemplateType } from './private/template';
 
 /**
@@ -71,6 +71,20 @@ export class Template {
  }
  }
 
+ /**
+ * Assert that the given number of resources of the given type and properties exists in the
+ * CloudFormation template.
+ * @param type the resource type; ex: `AWS::S3::Bucket`
+ * @param props the 'Properties' section of the resource as should be expected in the template.
+ * @param count number of expected instances
+ */
+ public resourcePropertiesCountIs(type: string, props: any, count: number): void {
+ const counted = countResourcesProperties(this.template, type, props);
+ if (counted !== count) {
+ throw new Error(`Expected ${count} resources of type ${type} but found ${counted}`);
+ }
+ }
+
  /**
  * Assert that a resource of the given type and properties exists in the
  * CloudFormation template.

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

@@ -124,6 +124,93 @@ describe('Template', () => {
  });
  });
 
+ describe('resourcePropertiesCountIs', () => {
+ test('resource exists', () => {
+ const stack = new Stack();
+ new CfnResource(stack, 'Resource', {
+ type: 'Foo::Bar',
+ properties: { baz: 'qux' },
+ });
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'qux' }, 1);
+
+ expect(() => {
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'qux' }, 0);
+ }).toThrow('Expected 0 resources of type Foo::Bar but found 1');
+ expect(() => {
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'qux' }, 2);
+ }).toThrow('Expected 2 resources of type Foo::Bar but found 1');
+ expect(() => {
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'nope' }, 1);
+ }).toThrow('Expected 1 resources of type Foo::Bar but found 0');
+ expect(() => {
+ inspect.resourcePropertiesCountIs('Foo::Baz', { baz: 'qux' }, 1);
+ }).toThrow('Expected 1 resources of type Foo::Baz but found 0');
+ });
+ test('no resource', () => {
+ const stack = new Stack();
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'qux' }, 0);
+
+ expect(() => {
+ inspect.resourcePropertiesCountIs('Foo::Bar', { baz: 'qux' }, 1);
+ }).toThrow('Expected 1 resources of type Foo::Bar but found 0');
+ });
+ test('absent - with properties', () => {
+ const stack = new Stack();
+ new CfnResource(stack, 'Foo', {
+ type: 'Foo::Bar',
+ properties: { baz: 'qux' },
+ });
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', {
+ bar: Match.absent(),
+ }, 1);
+ inspect.resourcePropertiesCountIs('Foo::Bar', {
+ baz: Match.absent(),
+ }, 0);
+ });
+ test('absent - no properties', () => {
+ const stack = new Stack();
+ new CfnResource(stack, 'Foo', {
+ type: 'Foo::Bar',
+ });
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', {
+ bar: Match.absent(),
+ baz: 'qux',
+ }, 0);
+ inspect.resourcePropertiesCountIs('Foo::Bar', Match.absent(), 1);
+ });
+ test('not - with properties', () => {
+ const stack = new Stack();
+ new CfnResource(stack, 'Foo', {
+ type: 'Foo::Bar',
+ properties: { baz: 'qux' },
+ });
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', Match.not({
+ baz: 'boo',
+ }), 1);
+ });
+ test('not - no properties', () => {
+ const stack = new Stack();
+ new CfnResource(stack, 'Foo', {
+ type: 'Foo::Bar',
+ });
+
+ const inspect = Template.fromStack(stack);
+ inspect.resourcePropertiesCountIs('Foo::Bar', Match.not({
+ baz: 'qux',
+ }), 1);
+ });
+ });
+
  describe('templateMatches', () => {
  test('matches', () => {
  const app = new App();