feat(assertions): major improvements to the capture feature (#17713)

There are three major changes around the capture feature of assertions.

Firstly, when there are multiple targets (say, Resource in the
CloudFormation template) that matches the given condition, any
`Capture` defined in the condition will contain only the last matched
resource.
Convert the `Capture` class into an iterable so all matching values can
be retrieved.

Secondly, add support to allow sub-patterns to be specified to the
`Capture` class. This allows further conditions be specified, via
Matchers or literals, when a value is to be captured.

Finally, this fixes a bug with the current implementation where
`Capture` contains the results of the last matched section, irrespective
of whether that section matched with the rest of the matcher or not.

fixes #17009

----

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

Author: Niranjan Jayakar

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

@@ -399,3 +399,67 @@ template.hasResourceProperties('Foo::Bar', {
 fredCapture.asArray(); // returns ["Flob", "Cat"]
 waldoCapture.asString(); // returns "Qux"
 ```
+
+With captures, a nested pattern can also be specified, so that only targets
+that match the nested pattern will be captured. This pattern can be literals or
+further Matchers.
+
+```ts
+// Given a template -
+// {
+//   "Resources": {
+//     "MyBar1": {
+//       "Type": "Foo::Bar",
+//       "Properties": {
+//         "Fred": ["Flob", "Cat"],
+//       }
+//     }
+//     "MyBar2": {
+//       "Type": "Foo::Bar",
+//       "Properties": {
+//         "Fred": ["Qix", "Qux"],
+//       }
+//     }
+//   }
+// }
+
+const capture = new Capture(Match.arrayWith(['Cat']));
+template.hasResourceProperties('Foo::Bar', {
+  Fred: capture,
+});
+
+capture.asArray(); // returns ['Flob', 'Cat']
+```
+
+When multiple resources match the given condition, each `Capture` defined in
+the condition will capture all matching values. They can be paged through using
+the `next()` API. The following example illustrates this -
+
+```ts
+// Given a template -
+// {
+//   "Resources": {
+//     "MyBar": {
+//       "Type": "Foo::Bar",
+//       "Properties": {
+//         "Fred": "Flob",
+//       }
+//     },
+//     "MyBaz": {
+//       "Type": "Foo::Bar",
+//       "Properties": {
+//         "Fred": "Quib",
+//       }
+//     }
+//   }
+// }
+
+const fredCapture = new Capture();
+template.hasResourceProperties('Foo::Bar', {
+  Fred: fredCapture,
+});
+
+fredCapture.asString(); // returns "Flob"
+fredCapture.next();     // returns true
+fredCapture.asString(); // returns "Quib"
+```

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

@@ -1,3 +1,4 @@
+import { Match } from '.';
 import { Matcher, MatchResult } from './matcher';
 import { Type, getType } from './private/type';
 
@@ -8,31 +9,63 @@ import { Type, getType } from './private/type';
  */
 export class Capture extends Matcher {
   public readonly name: string;
-  private value: any = null;
+  /** @internal */
+  public _captured: any[] = [];
+  private idx = 0;
 
-  constructor() {
+  /**
+   * Initialize a new capture
+   * @param pattern a nested pattern or Matcher.
+   * If a nested pattern is provided `objectLike()` matching is applied.
+   */
+  constructor(private readonly pattern?: any) {
     super();
     this.name = 'Capture';
   }
 
   public test(actual: any): MatchResult {
-    this.value = actual;
-
     const result = new MatchResult(actual);
     if (actual == null) {
-      result.push(this, [], `Can only capture non-nullish values. Found ${actual}`);
+      return result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Can only capture non-nullish values. Found ${actual}`,
+      });
     }
+
+    if (this.pattern !== undefined) {
+      const innerMatcher = Matcher.isMatcher(this.pattern) ? this.pattern : Match.objectLike(this.pattern);
+      const innerResult = innerMatcher.test(actual);
+      if (innerResult.hasFailed()) {
+        return innerResult;
+      }
+    }
+
+    result.recordCapture({ capture: this, value: actual });
     return result;
   }
 
+  /**
+   * When multiple results are captured, move the iterator to the next result.
+   * @returns true if another capture is present, false otherwise
+   */
+  public next(): boolean {
+    if (this.idx < this._captured.length - 1) {
+      this.idx++;
+      return true;
+    }
+    return false;
+  }
+
   /**
    * Retrieve the captured value as a string.
    * An error is generated if no value is captured or if the value is not a string.
    */
   public asString(): string {
-    this.checkNotNull();
-    if (getType(this.value) === 'string') {
-      return this.value;
+    this.validate();
+    const val = this._captured[this.idx];
+    if (getType(val) === 'string') {
+      return val;
     }
     this.reportIncorrectType('string');
   }
@@ -42,9 +75,10 @@ export class Capture extends Matcher {
    * An error is generated if no value is captured or if the value is not a number.
    */
   public asNumber(): number {
-    this.checkNotNull();
-    if (getType(this.value) === 'number') {
-      return this.value;
+    this.validate();
+    const val = this._captured[this.idx];
+    if (getType(val) === 'number') {
+      return val;
     }
     this.reportIncorrectType('number');
   }
@@ -54,9 +88,10 @@ export class Capture extends Matcher {
    * An error is generated if no value is captured or if the value is not a boolean.
    */
   public asBoolean(): boolean {
-    this.checkNotNull();
-    if (getType(this.value) === 'boolean') {
-      return this.value;
+    this.validate();
+    const val = this._captured[this.idx];
+    if (getType(val) === 'boolean') {
+      return val;
     }
     this.reportIncorrectType('boolean');
   }
@@ -66,9 +101,10 @@ export class Capture extends Matcher {
    * An error is generated if no value is captured or if the value is not an array.
    */
   public asArray(): any[] {
-    this.checkNotNull();
-    if (getType(this.value) === 'array') {
-      return this.value;
+    this.validate();
+    const val = this._captured[this.idx];
+    if (getType(val) === 'array') {
+      return val;
     }
     this.reportIncorrectType('array');
   }
@@ -78,21 +114,22 @@ export class Capture extends Matcher {
    * An error is generated if no value is captured or if the value is not an object.
    */
   public asObject(): { [key: string]: any } {
-    this.checkNotNull();
-    if (getType(this.value) === 'object') {
-      return this.value;
+    this.validate();
+    const val = this._captured[this.idx];
+    if (getType(val) === 'object') {
+      return val;
     }
     this.reportIncorrectType('object');
   }
 
-  private checkNotNull(): void {
-    if (this.value == null) {
+  private validate(): void {
+    if (this._captured.length === 0) {
       throw new Error('No value captured');
     }
   }
 
   private reportIncorrectType(expected: Type): never {
-    throw new Error(`Captured value is expected to be ${expected} but found ${getType(this.value)}. ` +
-      `Value is ${JSON.stringify(this.value, undefined, 2)}`);
+    throw new Error(`Captured value is expected to be ${expected} but found ${getType(this._captured[this.idx])}. ` +
+      `Value is ${JSON.stringify(this._captured[this.idx], undefined, 2)}`);
   }
 }

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

@@ -124,12 +124,20 @@ class LiteralMatch extends Matcher {
 
     const result = new MatchResult(actual);
     if (typeof this.pattern !== typeof actual) {
-      result.push(this, [], `Expected type ${typeof this.pattern} but received ${getType(actual)}`);
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected type ${typeof this.pattern} but received ${getType(actual)}`,
+      });
       return result;
     }
 
     if (actual !== this.pattern) {
-      result.push(this, [], `Expected ${this.pattern} but received ${actual}`);
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected ${this.pattern} but received ${actual}`,
+      });
     }
 
     return result;
@@ -166,10 +174,18 @@ class ArrayMatch extends Matcher {
 
   public test(actual: any): MatchResult {
     if (!Array.isArray(actual)) {
-      return new MatchResult(actual).push(this, [], `Expected type array but received ${getType(actual)}`);
+      return new MatchResult(actual).recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected type array but received ${getType(actual)}`,
+      });
     }
     if (!this.subsequence && this.pattern.length !== actual.length) {
-      return new MatchResult(actual).push(this, [], `Expected array of length ${this.pattern.length} but received ${actual.length}`);
+      return new MatchResult(actual).recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected array of length ${this.pattern.length} but received ${actual.length}`,
+      });
     }
 
     let patternIdx = 0;
@@ -200,7 +216,11 @@ class ArrayMatch extends Matcher {
     for (; patternIdx < this.pattern.length; patternIdx++) {
       const pattern = this.pattern[patternIdx];
       const element = (Matcher.isMatcher(pattern) || typeof pattern === 'object') ? ' ' : ` [${pattern}] `;
-      result.push(this, [], `Missing element${element}at pattern index ${patternIdx}`);
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Missing element${element}at pattern index ${patternIdx}`,
+      });
     }
 
     return result;
@@ -236,21 +256,33 @@ class ObjectMatch extends Matcher {
 
   public test(actual: any): MatchResult {
     if (typeof actual !== 'object' || Array.isArray(actual)) {
-      return new MatchResult(actual).push(this, [], `Expected type object but received ${getType(actual)}`);
+      return new MatchResult(actual).recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected type object but received ${getType(actual)}`,
+      });
     }
 
     const result = new MatchResult(actual);
     if (!this.partial) {
       for (const a of Object.keys(actual)) {
         if (!(a in this.pattern)) {
-          result.push(this, [`/${a}`], 'Unexpected key');
+          result.recordFailure({
+            matcher: this,
+            path: [`/${a}`],
+            message: 'Unexpected key',
+          });
         }
       }
     }
 
     for (const [patternKey, patternVal] of Object.entries(this.pattern)) {
       if (!(patternKey in actual) && !(patternVal instanceof AbsentMatch)) {
-        result.push(this, [`/${patternKey}`], 'Missing key');
+        result.recordFailure({
+          matcher: this,
+          path: [`/${patternKey}`],
+          message: 'Missing key',
+        });
         continue;
       }
       const matcher = Matcher.isMatcher(patternVal) ?
@@ -275,15 +307,23 @@ class SerializedJson extends Matcher {
   public test(actual: any): MatchResult {
     const result = new MatchResult(actual);
     if (getType(actual) !== 'string') {
-      result.push(this, [], `Expected JSON as a string but found ${getType(actual)}`);
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Expected JSON as a string but found ${getType(actual)}`,
+      });
       return result;
     }
     let parsed;
     try {
       parsed = JSON.parse(actual);
     } catch (err) {
       if (err instanceof SyntaxError) {
-        result.push(this, [], `Invalid JSON string: ${actual}`);
+        result.recordFailure({
+          matcher: this,
+          path: [],
+          message: `Invalid JSON string: ${actual}`,
+        });
         return result;
       } else {
         throw err;
@@ -311,7 +351,11 @@ class NotMatch extends Matcher {
     const innerResult = matcher.test(actual);
     const result = new MatchResult(actual);
     if (innerResult.failCount === 0) {
-      result.push(this, [], `Found unexpected match: ${JSON.stringify(actual, undefined, 2)}`);
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: `Found unexpected match: ${JSON.stringify(actual, undefined, 2)}`,
+      });
     }
     return result;
   }
@@ -325,7 +369,11 @@ class AnyMatch extends Matcher {
   public test(actual: any): MatchResult {
     const result = new MatchResult(actual);
     if (actual == null) {
-      result.push(this, [], 'Expected a value but found none');
+      result.recordFailure({
+        matcher: this,
+        path: [],
+        message: 'Expected a value but found none',
+      });
     }
     return result;
   }