feat(assertions): match into serialized json

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

@@ -321,6 +321,47 @@ assert.hasResourceProperties('Foo::Bar', Match.objectLike({
 }});
 ```
 
+### Serialized JSON
+
+Often, we find that some CloudFormation Resource types declare properties as a string,
+but actually expect JSON serialized as a string.
+For example, the [`BuildSpec` property of `AWS::CodeBuild::Project`][Pipeline BuildSpec],
+the [`Definition` property of `AWS::StepFunctions::StateMachine`][StateMachine Definition],
+to name a couple.
+
+The `Match.serializedJson()` matcher allows deep matching within a stringified JSON.
+
+```ts
+// Given a template -
+// {
+// "Resources": {
+// "MyBar": {
+// "Type": "Foo::Bar",
+// "Properties": {
+// "Baz": "{ \"Fred\": [\"Waldo\", \"Willow\"] }"
+// }
+// }
+// }
+// }
+
+// The following will NOT throw an assertion error
+assert.hasResourceProperties('Foo::Bar', {
+ Baz: Match.serializedJson({
+ Fred: Match.arrayWith(["Waldo"]),
+ }),
+});
+
+// The following will throw an assertion error
+assert.hasResourceProperties('Foo::Bar', {
+ Baz: Match.serializedJson({
+ Fred: ["Waldo", "Johnny"],
+ }),
+});
+```
+
+[Pipeline BuildSpec]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codebuild-project-source.html#cfn-codebuild-project-source-buildspec
+[StateMachine Definition]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-stepfunctions-statemachine.html#cfn-stepfunctions-statemachine-definition
+
 ## Capturing Values
 
 This matcher APIs documented above allow capturing values in the matching entry

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

@@ -65,6 +65,14 @@ export abstract class Match {
  return new NotMatch('not', pattern);
  }
 
+ /**
+ * Matches any string-encoded JSON and applies the specified pattern after parsing it.
+ * @param pattern the pattern to match after parsing the encoded JSON.
+ */
+ public static serializedJson(pattern: any): Matcher {
+ return new SerializedJson('serializedJson', pattern);
+ }
+
  /**
  * Matches any non-null value at the target.
  */
@@ -265,6 +273,42 @@ class ObjectMatch extends Matcher {
  }
 }
 
+class SerializedJson extends Matcher {
+ constructor(
+ public readonly name: string,
+ private readonly pattern: any,
+ ) {
+ super();
+ };
+
+ 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)}`);
+ return result;
+ }
+ let parsed;
+ try {
+ parsed = JSON.parse(actual);
+ } catch (err) {
+ if (err instanceof SyntaxError) {
+ result.push(this, [], 'Invalid JSON string');
+ return result;
+ } else {
+ throw err;
+ }
+ }
+
+ if (parsed == null) {
+ result.push(this, [], 'Invalid JSON string');
+ }
+ const matcher = Matcher.isMatcher(this.pattern) ? this.pattern : new LiteralMatch(this.name, this.pattern);
+ const innerResult = matcher.test(parsed);
+ result.compose(`(${this.name})`, innerResult);
+ return result;
+ }
+}
+
 class NotMatch extends Matcher {
  constructor(
  public readonly name: string,

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

@@ -323,18 +323,57 @@ describe('Matchers', () => {
  expectFailure(matcher, {}, ['Missing key at /foo']);
  });
  });
+
+ describe('serializedJson()', () => {
+ let matcher: Matcher;
+
+ test('all types', () => {
+ matcher = Match.serializedJson({ Foo: 'Bar', Baz: 3, Boo: true, Fred: [1, 2] });
+ expectPass(matcher, '{ "Foo": "Bar", "Baz": 3, "Boo": true, "Fred": [1, 2] }');
+ });
+
+ test('simple match', () => {
+ matcher = Match.serializedJson({ Foo: 'Bar' });
+ expectPass(matcher, '{ "Foo": "Bar" }');
+
+ expectFailure(matcher, '{ "Foo": "Baz" }', ['Expected Bar but received Baz at (serializedJson)/Foo']);
+ expectFailure(matcher, '{ "Foo": 4 }', ['Expected type string but received number at (serializedJson)/Foo']);
+ expectFailure(matcher, '{ "Bar": "Baz" }', [
+ 'Unexpected key at (serializedJson)/Bar',
+ 'Missing key at (serializedJson)/Foo',
+ ]);
+ });
+
+ test('nested matcher', () => {
+ matcher = Match.serializedJson(Match.objectLike({
+ Foo: Match.arrayWith(['Bar']),
+ }));
+
+ expectPass(matcher, '{ "Foo": ["Bar"] }');
+ expectPass(matcher, '{ "Foo": ["Bar", "Baz"] }');
+ expectPass(matcher, '{ "Foo": ["Bar", "Baz"], "Fred": "Waldo" }');
+
+ expectFailure(matcher, '{ "Foo": ["Baz"] }', ['Missing element [Bar] at pattern index 0 at (serializedJson)/Foo']);
+ expectFailure(matcher, '{ "Bar": ["Baz"] }', ['Missing key at (serializedJson)/Foo']);
+ });
+ });
 });
 
 function expectPass(matcher: Matcher, target: any): void {
- expect(matcher.test(target).hasFailed()).toEqual(false);
+ const result = matcher.test(target);
+ if (result.hasFailed()) {
+ fail(result.toHumanStrings()); // eslint-disable-line jest/no-jasmine-globals
+ }
 }
 
 function expectFailure(matcher: Matcher, target: any, expected: (string | RegExp)[] = []): void {
  const result = matcher.test(target);
  expect(result.failCount).toBeGreaterThan(0);
  const actual = result.toHumanStrings();
- if (expected.length > 0) {
- expect(actual.length).toEqual(expected.length);
+ if (expected.length > 0 && actual.length !== expected.length) {
+ // only do this if the lengths are different, so as to display a nice failure message.
+ // otherwise need to use `toMatch()` to support RegExp
+ expect(actual).toEqual(expected);
  }
  for (let i = 0; i < expected.length; i++) {
  const e = expected[i];