feat(assertions): capture matching value

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

@@ -184,7 +184,9 @@ assert.hasResourceProperties('Foo::Bar', {
 The `Match.objectEquals()` API can be used to assert a target as a deep exact
 match.
 
-In addition, the `Match.absentProperty()` can be used to specify that a specific
+### Presence and Absence
+
+The `Match.absentProperty()` matcher can be used to specify that a specific
 property should not exist on the target. This can be used within `Match.objectLike()`
 or outside of any matchers.
 
@@ -218,6 +220,42 @@ assert.hasResourceProperties('Foo::Bar', {
 });
 ```
 
+The `Match.anyValue()` matcher can be used to specify that a specific value should be found
+at the location. This matcher will fail if when the target location has null-ish values
+(i.e., `null` or `undefined`).
+
+This matcher can be combined with any of the other matchers.
+
+```ts
+// Given a template -
+// {
+// "Resources": {
+// "MyBar": {
+// "Type": "Foo::Bar",
+// "Properties": {
+// "Fred": {
+// "Wobble": ["Flob", "Flib"],
+// }
+// }
+// }
+// }
+// }
+
+// The following will NOT throw an assertion error
+assert.hasResourceProperties('Foo::Bar', {
+ Fred: {
+ Wobble: [Match.anyValue(), "Flip"],
+ },
+});
+
+// The following will throw an assertion error
+assert.hasResourceProperties('Foo::Bar', {
+ Fred: {
+ Wimble: Match.anyValue(),
+ },
+});
+```
+
 ### Array Matchers
 
 The `Match.arrayWith()` API can be used to assert that the target is equal to or a subset
@@ -283,6 +321,37 @@ assert.hasResourceProperties('Foo::Bar', Match.objectLike({
 }});
 ```
 
+## Capturing Values
+
+This matcher APIs documented above allow capturing values in the matching entry
+(Resource, Output, Mapping, etc.). The following code captures a string from a
+matching resource.
+
+```ts
+// Given a template -
+// {
+// "Resources": {
+// "MyBar": {
+// "Type": "Foo::Bar",
+// "Properties": {
+// "Fred": ["Flob", "Cat"],
+// "Waldo": ["Qix", "Qux"],
+// }
+// }
+// }
+// }
+
+const fredCapture = new Capture();
+const waldoCapture = new Capture();
+assert.hasResourceProperties('Foo::Bar', {
+ Fred: fredCapture,
+ Waldo: ["Qix", waldoCapture],
+});
+
+fredCapture.asArray(); // returns ["Flob", "Cat"]
+waldoCapture.asString(); // returns "Qux"
+```
+
 ## Strongly typed languages
 
 Some of the APIs documented above, such as `templateMatches()` and

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

@@ -0,0 +1,98 @@
+import { Matcher, MatchResult } from './matcher';
+import { Type, getType } from './private/type';
+
+/**
+ * Capture values while matching templates.
+ * Using an instance of this class within a Matcher will capture the matching value.
+ * The `as*()` APIs on the instance can be used to get the captured value.
+ */
+export class Capture extends Matcher {
+ public readonly name: string;
+ private value: any = null;
+
+ constructor() {
+ 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;
+ }
+
+ /**
+ * 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.reportIncorrectType('string');
+ }
+
+ /**
+ * Retrieve the captured value as a number.
+ * 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.reportIncorrectType('number');
+ }
+
+ /**
+ * Retrieve the captured value as a boolean.
+ * 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.reportIncorrectType('boolean');
+ }
+
+ /**
+ * Retrieve the captured value as an array.
+ * 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.reportIncorrectType('array');
+ }
+
+ /**
+ * Retrieve the captured value as a JSON object.
+ * 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.reportIncorrectType('object');
+ }
+
+ private checkNotNull(): void {
+ if (this.value == null) {
+ 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)}`);
+ }
+}

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

@@ -1,3 +1,4 @@
+export * from './capture';
 export * from './template';
 export * from './match';
 export * from './matcher';

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

@@ -1,4 +1,5 @@
 import { Matcher, MatchResult } from './matcher';
+import { getType } from './private/type';
 import { ABSENT } from './vendored/assert';
 
 /**
@@ -63,6 +64,13 @@ export abstract class Match {
  public static not(pattern: any): Matcher {
  return new NotMatch('not', pattern);
  }
+
+ /**
+ * Matches any non-null value at the target.
+ */
+ public static anyValue(): Matcher {
+ return new AnyMatch('anyValue');
+ }
 }
 
 /**
@@ -141,22 +149,22 @@ interface ArrayMatchOptions {
  * Match class that matches arrays.
  */
 class ArrayMatch extends Matcher {
- private readonly partial: boolean;
+ private readonly subsequence: boolean;
 
  constructor(
  public readonly name: string,
  private readonly pattern: any[],
  options: ArrayMatchOptions = {}) {
 
  super();
- this.partial = options.subsequence ?? true;
+ this.subsequence = options.subsequence ?? true;
  }
 
  public test(actual: any): MatchResult {
  if (!Array.isArray(actual)) {
  return new MatchResult(actual).push(this, [], `Expected type array but received ${getType(actual)}`);
  }
- if (!this.partial && this.pattern.length !== actual.length) {
+ 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}`);
  }
 
@@ -166,10 +174,16 @@ class ArrayMatch extends Matcher {
  const result = new MatchResult(actual);
  while (patternIdx < this.pattern.length && actualIdx < actual.length) {
  const patternElement = this.pattern[patternIdx];
+
  const matcher = Matcher.isMatcher(patternElement) ? patternElement : new LiteralMatch(this.name, patternElement);
+ if (this.subsequence && matcher instanceof AnyMatch) {
+ // array subsequence matcher is not compatible with anyValue() matcher. They don't make sense to be used together.
+ throw new Error('The Matcher anyValue() cannot be nested within arrayWith()');
+ }
+
  const innerResult = matcher.test(actual[actualIdx]);
 
- if (!this.partial || !innerResult.hasFailed()) {
+ if (!this.subsequence || !innerResult.hasFailed()) {
  result.compose(`[${actualIdx}]`, innerResult);
  patternIdx++;
  actualIdx++;
@@ -271,6 +285,16 @@ class NotMatch extends Matcher {
  }
 }
 
-function getType(obj: any): string {
- return Array.isArray(obj) ? 'array' : typeof obj;
+class AnyMatch extends Matcher {
+ constructor(public readonly name: string) {
+ super();
+ }
+
+ public test(actual: any): MatchResult {
+ const result = new MatchResult(actual);
+ if (actual == null) {
+ result.push(this, [], 'Expected a value but found none');
+ }
+ return result;
+ }
 }

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

@@ -17,6 +17,8 @@ export abstract class Matcher {
 
  /**
  * Test whether a target matches the provided pattern.
+ * Every Matcher must implement this method.
+ * This method will be invoked by the assertions framework. Do not call this method directly.
  * @param actual the target to match
  * @return the list of match failures. An empty array denotes a successful match.
  */

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

@@ -0,0 +1,5 @@
+export type Type = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'array';
+
+export function getType(obj: any): Type {
+ return Array.isArray(obj) ? 'array' : typeof obj;
+}

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

@@ -0,0 +1,69 @@
+import { Capture, Match } from '../lib';
+
+describe('Capture', () => {
+ test('uncaptured', () => {
+ const capture = new Capture();
+ expect(() => capture.asString()).toThrow(/No value captured/);
+ });
+
+ test('nullish', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: capture });
+
+ const result = matcher.test({ foo: null });
+ expect(result.failCount).toEqual(1);
+ expect(result.toHumanStrings()[0]).toMatch(/Can only capture non-nullish values/);
+ });
+
+ test('asString()', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: capture });
+
+ matcher.test({ foo: 'bar' });
+ expect(capture.asString()).toEqual('bar');
+
+ matcher.test({ foo: 3 });
+ expect(() => capture.asString()).toThrow(/expected to be string but found number/);
+ });
+
+ test('asNumber()', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: capture });
+
+ matcher.test({ foo: 3 });
+ expect(capture.asNumber()).toEqual(3);
+
+ matcher.test({ foo: 'bar' });
+ expect(() => capture.asNumber()).toThrow(/expected to be number but found string/);
+ });
+
+ test('asArray()', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: capture });
+
+ matcher.test({ foo: ['bar'] });
+ expect(capture.asArray()).toEqual(['bar']);
+
+ matcher.test({ foo: 'bar' });
+ expect(() => capture.asArray()).toThrow(/expected to be array but found string/);
+ });
+
+ test('asObject()', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: capture });
+
+ matcher.test({ foo: { fred: 'waldo' } });
+ expect(capture.asObject()).toEqual({ fred: 'waldo' });
+
+ matcher.test({ foo: 'bar' });
+ expect(() => capture.asObject()).toThrow(/expected to be object but found string/);
+ });
+
+ test('nested within an array', () => {
+ const capture = new Capture();
+ const matcher = Match.objectEquals({ foo: ['bar', capture] });
+
+ matcher.test({ foo: ['bar', 'baz'] });
+ expect(capture.asString()).toEqual('baz');
+ });
+});