feat(assertions): throw typed errors (aws#33382)

### Issue 

Relates to aws#32569 

### Description of changes

Introduces a new `AssertionError` and uses it.

### Describe any new or updated permissions being added

n/a

### Description of how you validated changes

Existing tests. Exemptions granted as this is a refactor of existing code.

### 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*

Author: mrgrain

packages/@aws-cdk/integ-tests-alpha/test/assertions/providers/lambda-handler/base.test.ts

@@ -245,9 +245,9 @@ describe('CustomResourceHandler', () => {
   });
 });
 
-function nockUp(_predicate: (body: CloudFormationResponse) => boolean) {
+function nockUp(predicate: (body: CloudFormationResponse) => boolean) {
   return nock('https://someurl.com')
-    .put('/')
+    .put('/', predicate)
     .reply(200);
 }
 

packages/aws-cdk-lib/.eslintrc.js

@@ -16,7 +16,7 @@ baseConfig.rules['import/no-extraneous-dependencies'] = [
 
 // no-throw-default-error
 const enableNoThrowDefaultErrorIn = [
-  'aws-backup',
+  'assertions',
   'assets',
   'aws-amplify',
   'aws-amplifyuibuilder',
@@ -30,6 +30,7 @@ const enableNoThrowDefaultErrorIn = [
   'aws-appmesh',
   'aws-autoscaling',
   'aws-autoscaling-common',  
+  'aws-backup',
   'aws-batch',
   'aws-cognito',
   'aws-elasticloadbalancing',
@@ -46,7 +47,6 @@ const enableNoThrowDefaultErrorIn = [
   'aws-ssmincidents',
   'aws-ssmquicksetup',
   'aws-synthetics',
-  'cloudformation-include',
   'aws-route53',
   'aws-route53-patterns',
   'aws-route53-targets',
@@ -61,7 +61,6 @@ const enableNoThrowDefaultErrorIn = [
   'aws-ssmincidents',
   'aws-ssmquicksetup',
   'aws-synthetics',
-  'cx-api',
   'aws-s3',
   'aws-s3-assets',
   'aws-s3-deployment',
@@ -70,6 +69,8 @@ const enableNoThrowDefaultErrorIn = [
   'aws-s3objectlambda',
   'aws-s3outposts',
   'aws-s3tables',
+  'cloudformation-include',
+  'cx-api',
   'pipelines',
 ];
 baseConfig.overrides.push({

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

@@ -2,6 +2,7 @@ import { Messages } from './private/message';
 import { findMessage, hasMessage, hasNoMessage } from './private/messages';
 import { Stack, Stage } from '../../core';
 import { SynthesisMessage } from '../../cx-api';
+import { AssertionError } from './private/error';
 
 /**
  * Suite of assertions that can be run on a CDK Stack.
@@ -31,7 +32,7 @@ export class Annotations {
   public hasError(constructPath: string, message: any): void {
     const matchError = hasMessage(this._messages, constructPath, constructMessage('error', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -44,7 +45,7 @@ export class Annotations {
   public hasNoError(constructPath: string, message: any): void {
     const matchError = hasNoMessage(this._messages, constructPath, constructMessage('error', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -67,7 +68,7 @@ export class Annotations {
   public hasWarning(constructPath: string, message: any): void {
     const matchError = hasMessage(this._messages, constructPath, constructMessage('warning', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -80,7 +81,7 @@ export class Annotations {
   public hasNoWarning(constructPath: string, message: any): void {
     const matchError = hasNoMessage(this._messages, constructPath, constructMessage('warning', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -103,7 +104,7 @@ export class Annotations {
   public hasInfo(constructPath: string, message: any): void {
     const matchError = hasMessage(this._messages, constructPath, constructMessage('info', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -116,7 +117,7 @@ export class Annotations {
   public hasNoInfo(constructPath: string, message: any): void {
     const matchError = hasNoMessage(this._messages, constructPath, constructMessage('info', message));
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -156,7 +157,7 @@ function convertMessagesTypeToArray(messages: Messages): SynthesisMessage[] {
 function toMessages(stack: Stack): any {
   const root = stack.node.root;
   if (!Stage.isStage(root)) {
-    throw new Error('unexpected: all stacks must be part of a Stage or an App');
+    throw new AssertionError('unexpected: all stacks must be part of a Stage or an App');
   }
 
   // to support incremental assertions (i.e. "expect(stack).toNotContainSomething(); doSomething(); expect(stack).toContainSomthing()")

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

@@ -1,5 +1,6 @@
 import { Match } from '.';
 import { Matcher, MatchResult } from './matcher';
+import { AssertionError } from './private/error';
 import { Type, getType } from './private/type';
 
 /**
@@ -124,12 +125,12 @@ export class Capture extends Matcher {
 
   private validate(): void {
     if (this._captured.length === 0) {
-      throw new Error('No value captured');
+      throw new AssertionError('No value captured');
     }
   }
 
   private reportIncorrectType(expected: Type): never {
-    throw new Error(`Captured value is expected to be ${expected} but found ${getType(this._captured[this.idx])}. ` +
+    throw new AssertionError(`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-lib/assertions/lib/match.ts

@@ -1,4 +1,5 @@
 import { Matcher, MatchResult } from './matcher';
+import { AssertionError } from './private/error';
 import { AbsentMatch } from './private/matchers/absent';
 import { sortKeyComparator } from './private/sorting';
 import { SparseMatrix } from './private/sparse-matrix';
@@ -116,7 +117,7 @@ class LiteralMatch extends Matcher {
     this.partialObjects = options.partialObjects ?? false;
 
     if (Matcher.isMatcher(this.pattern)) {
-      throw new Error('LiteralMatch cannot directly contain another matcher. ' +
+      throw new AssertionError('LiteralMatch cannot directly contain another matcher. ' +
         'Remove the top-level matcher or nest it more deeply.');
     }
   }
@@ -253,7 +254,7 @@ class ArrayMatch extends Matcher {
       const matcherName = matcher.name;
       if (matcherName == 'absent' || matcherName == 'anyValue') {
         // array subsequence matcher is not compatible with anyValue() or absent() matcher. They don't make sense to be used together.
-        throw new Error(`The Matcher ${matcherName}() cannot be nested within arrayWith()`);
+        throw new AssertionError(`The Matcher ${matcherName}() cannot be nested within arrayWith()`);
       }
 
       const innerResult = matcher.test(actual[actualIdx]);

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

@@ -1,3 +1,4 @@
+import { AssertionError } from './error';
 import { Resource, Template } from './template';
 
 /**
@@ -28,7 +29,7 @@ export function checkTemplateForCyclicDependencies(template: Template): void {
         cycleResources[logicalId] = template.Resources?.[logicalId];
       }
 
-      throw new Error(`Template is undeployable, these resources have a dependency cycle: ${cycle.join(' -> ')}:\n\n${JSON.stringify(cycleResources, undefined, 2)}`);
+      throw new AssertionError(`Template is undeployable, these resources have a dependency cycle: ${cycle.join(' -> ')}:\n\n${JSON.stringify(cycleResources, undefined, 2)}`);
     }
 
     for (const [logicalId, _] of free) {
@@ -163,7 +164,7 @@ function findCycle(deps: ReadonlyMap<string, ReadonlySet<string>>): string[] {
     const cycle = recurse(node, [node]);
     if (cycle) { return cycle; }
   }
-  throw new Error('No cycle found. Assertion failure!');
+  throw new AssertionError('No cycle found. Assertion failure!');
 
   function recurse(node: string, path: string[]): string[] | undefined {
     for (const dep of deps.get(node) ?? []) {

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

@@ -0,0 +1,36 @@
+const ASSERTION_ERROR_SYMBOL = Symbol.for('@aws-cdk/assertions.AssertionError');
+
+/**
+ * An AssertionError is thrown from the assertions module when an assertion fails.
+ * Assertion errors are directly connected to an assertion a user wrote.
+ *
+ * Not all errors from the assertions module are automatically AssertionErrors.
+ * When a pre-condition is incorrect (e.g. disallowed use of a matcher),
+ * throwing an UnscopedValidationError is more appropriate.
+ *
+ * @internal
+ */
+export class AssertionError extends Error {
+  #time: string;
+
+  /**
+   * The time the error was thrown.
+   */
+  public get time(): string {
+    return this.#time;
+  }
+
+  public get type(): 'assertion' {
+    return 'assertion';
+  }
+
+  constructor(msg: string) {
+    super(msg);
+
+    Object.setPrototypeOf(this, AssertionError.prototype);
+    Object.defineProperty(this, ASSERTION_ERROR_SYMBOL, { value: true });
+
+    this.name = new.target.name;
+    this.#time = new Date().toISOString();
+  }
+}

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

@@ -1,6 +1,7 @@
 import { Match } from './match';
 import { Matcher } from './matcher';
 import { Stack, Stage } from '../../core';
+import { AssertionError } from './private/error';
 
 type ManifestTags = { [key: string]: string };
 
@@ -37,7 +38,7 @@ export class Tags {
     // Match.absent() will not work as the caller expects, so we push them
     // towards a working API.
     if (Matcher.isMatcher(tags) && tags.name === 'absent') {
-      throw new Error(
+      throw new AssertionError(
         'Match.absent() will never match Tags because "{}" is the default value. Use Tags.hasNone() instead.',
       );
     }
@@ -46,7 +47,7 @@ export class Tags {
 
     const result = matcher.test(this.all());
     if (result.hasFailed()) {
-      throw new Error(
+      throw new AssertionError(
         'Stack tags did not match as expected:\n' + result.renderMismatch(),
       );
     }
@@ -79,7 +80,7 @@ export class Tags {
 function getManifestTags(stack: Stack): ManifestTags {
   const root = stack.node.root;
   if (!Stage.isStage(root)) {
-    throw new Error('unexpected: all stacks must be part of a Stage or an App');
+    throw new AssertionError('unexpected: all stacks must be part of a Stage or an App');
   }
 
   // synthesis is not forced: the stack will only be synthesized once regardless

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

@@ -10,6 +10,7 @@ import { findParameters, hasParameter } from './private/parameters';
 import { allResources, allResourcesProperties, countResources, countResourcesProperties, findResources, hasResource, hasResourceProperties } from './private/resources';
 import { Template as TemplateType } from './private/template';
 import { Stack, Stage } from '../../core';
+import { AssertionError } from './private/error';
 
 /**
  * Suite of assertions that can be run on a CDK stack.
@@ -74,7 +75,7 @@ export class Template {
   public resourceCountIs(type: string, count: number): void {
     const counted = countResources(this.template, type);
     if (counted !== count) {
-      throw new Error(`Expected ${count} resources of type ${type} but found ${counted}`);
+      throw new AssertionError(`Expected ${count} resources of type ${type} but found ${counted}`);
     }
   }
 
@@ -88,7 +89,7 @@ export class Template {
   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}`);
+      throw new AssertionError(`Expected ${count} resources of type ${type} but found ${counted}`);
     }
   }
 
@@ -103,7 +104,7 @@ export class Template {
   public hasResourceProperties(type: string, props: any): void {
     const matchError = hasResourceProperties(this.template, type, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -118,7 +119,7 @@ export class Template {
   public hasResource(type: string, props: any): void {
     const matchError = hasResource(this.template, type, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -144,7 +145,7 @@ export class Template {
   public allResources(type: string, props: any): void {
     const matchError = allResources(this.template, type, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -159,7 +160,7 @@ export class Template {
   public allResourcesProperties(type: string, props: any): void {
     const matchError = allResourcesProperties(this.template, type, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -173,7 +174,7 @@ export class Template {
   public hasParameter(logicalId: string, props: any): void {
     const matchError = hasParameter(this.template, logicalId, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -198,7 +199,7 @@ export class Template {
   public hasOutput(logicalId: string, props: any): void {
     const matchError = hasOutput(this.template, logicalId, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -223,7 +224,7 @@ export class Template {
   public hasMapping(logicalId: string, props: any): void {
     const matchError = hasMapping(this.template, logicalId, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -248,7 +249,7 @@ export class Template {
   public hasCondition(logicalId: string, props: any): void {
     const matchError = hasCondition(this.template, logicalId, props);
     if (matchError) {
-      throw new Error(matchError);
+      throw new AssertionError(matchError);
     }
   }
 
@@ -272,7 +273,7 @@ export class Template {
     const result = matcher.test(this.template);
 
     if (result.hasFailed()) {
-      throw new Error([
+      throw new AssertionError([
         'Template did not match as expected. The following mismatches were found:',
         ...result.toHumanStrings().map(s => `\t${s}`),
       ].join('\n'));
@@ -297,7 +298,7 @@ export interface TemplateParsingOptions {
 function toTemplate(stack: Stack): any {
   const stage = Stage.of(stack);
   if (!Stage.isStage(stage)) {
-    throw new Error('unexpected: all stacks must be part of a Stage or an App');
+    throw new AssertionError('unexpected: all stacks must be part of a Stage or an App');
   }
 
   const assembly = stage.synth();