feat: add new integration test runner (#19754)

Creating this PR so that we can iterate on the design of the integration
test runner.

We will create two packages (names up for debate)

1. `@aws-cdk/integ-runner` (this package)
CLI tool that will execute integration tests

2. `@aws-cdk/integ-tests`
Library that is used to create integration test cases. This library will
synthesize an assembly file that will be consumed by the runner.----

### All Submissions:

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

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/master/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/master/INTEGRATION_TESTS.md)?
	* [ ] Did you use `cdk-integ` to deploy the infrastructure and generate the snapshot (i.e. `cdk-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/cloud-assembly-schema/lib/index.ts

@@ -1,3 +1,4 @@
 export * from './cloud-assembly';
 export * from './assets';
 export * from './manifest';
+export * from './integ-tests';

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/commands/common.ts

@@ -0,0 +1,202 @@
+/**
+ * In what scenarios should the CLI ask for approval
+ */
+export enum RequireApproval {
+  /**
+   * Never ask for approval
+   */
+  NEVER = 'never',
+
+  /**
+   * Prompt for approval for any type  of change to the stack
+   */
+  ANYCHANGE = 'any-change',
+
+  /**
+   * Only prompt for approval if there are security related changes
+   */
+  BROADENING = 'broadening'
+}
+
+/**
+ * Default CDK CLI options that apply to all commands
+ */
+export interface DefaultCdkOptions {
+  /**
+   * List of stacks to deploy
+   *
+   * Requried if `all` is not set
+   *
+   * @default - []
+   */
+  readonly stacks?: string[];
+
+  /**
+   * Deploy all stacks
+   *
+   * Requried if `stacks` is not set
+   *
+   * @default - false
+   */
+  readonly all?: boolean;
+
+  /**
+   * command-line for executing your app or a cloud assembly directory
+   * e.g. "node bin/my-app.js"
+   * or
+   * "cdk.out"
+   *
+   * @default - read from cdk.json
+   */
+  readonly app?: string;
+
+
+  /**
+   * Role to pass to CloudFormation for deployment
+   *
+   * @default - use the bootstrap cfn-exec role
+   */
+  readonly roleArn?: string;
+
+  /**
+   * Additional context
+   *
+   * @default - no additional context
+   */
+  readonly context?: { [name: string]: string };
+
+  /**
+   * Print trace for stack warnings
+   *
+   * @default false
+   */
+  readonly trace?: boolean;
+
+  /**
+   * Do not construct stacks with warnings
+   *
+   * @default false
+   */
+  readonly strict?: boolean;
+
+  /**
+   * Perform context lookups.
+   *
+   * Synthesis fails if this is disabled and context lookups need
+   * to be performed
+   *
+   * @default true
+   */
+  readonly lookups?: boolean;
+
+  /**
+    * Ignores synthesis errors, which will likely produce an invalid output
+   *
+   * @default false
+   */
+  readonly ignoreErrors?: boolean;
+
+  /**
+   * Use JSON output instead of YAML when templates are printed
+   * to STDOUT
+   *
+   * @default false
+   */
+  readonly json?: boolean;
+
+  /**
+   * show debug logs
+   *
+   * @default false
+   */
+  readonly verbose?: boolean;
+
+  /**
+   * enable emission of additional debugging information, such as creation stack
+   * traces of tokens
+   *
+   * @default false
+   */
+  readonly debug?: boolean;
+
+  /**
+   * Use the indicated AWS profile as the default environment
+   *
+   * @default - no profile is used
+   */
+  readonly profile?: string;
+
+  /**
+   * Use the indicated proxy. Will read from
+   * HTTPS_PROXY environment if specified
+   *
+   * @default - no proxy
+   */
+  readonly proxy?: string;
+
+  /**
+   * Path to CA certificate to use when validating HTTPS
+   * requests.
+   *
+   * @default - read from AWS_CA_BUNDLE environment variable
+   */
+  readonly caBundlePath?: string;
+
+  /**
+   * Force trying to fetch EC2 instance credentials
+   *
+   * @default - guess EC2 instance status
+   */
+  readonly ec2Creds?: boolean;
+
+  /**
+   * Include "AWS::CDK::Metadata" resource in synthesized templates
+   *
+   * @default true
+   */
+  readonly versionReporting?: boolean;
+
+  /**
+   * Include "aws:cdk:path" CloudFormation metadata for each resource
+   *
+   * @default true
+   */
+  readonly pathMetadata?: boolean;
+
+  /**
+   * Include "aws:asset:*" CloudFormation metadata for resources that use assets
+   *
+   * @default true
+   */
+  readonly assetMetadata?: boolean;
+
+  /**
+   * Copy assets to the output directory
+   *
+   * Needed for local debugging the source files with SAM CLI
+   *
+   * @default false
+   */
+  readonly staging?: boolean;
+
+  /**
+   * Emits the synthesized cloud assembly into a directory
+   *
+   * @default cdk.out
+   */
+  readonly output?: string;
+
+  /**
+   * Show relevant notices
+   *
+   * @default true
+   */
+  readonly notices?: boolean;
+
+  /**
+   * Show colors and other style from console output
+   *
+   * @default true
+   */
+  readonly color?: boolean;
+}

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/commands/deploy.ts

@@ -0,0 +1,97 @@
+import { DefaultCdkOptions, RequireApproval } from './common';
+
+/**
+ * Options to use with cdk deploy
+ */
+export interface DeployOptions extends DefaultCdkOptions {
+  /**
+   * Only perform action on the given stack
+   *
+   * @default false
+   */
+  readonly exclusively?: boolean;
+
+  /**
+   * Name of the toolkit stack to use/deploy
+   *
+   * @default CDKToolkit
+   */
+  readonly toolkitStackName?: string;
+
+  /**
+   * Reuse the assets with the given asset IDs
+   *
+   * @default - do not reuse assets
+   */
+  readonly reuseAssets?: string[];
+
+  /**
+   * Optional name to use for the CloudFormation change set.
+   * If not provided, a name will be generated automatically.
+   *
+   * @default - auto generate a name
+   */
+  readonly changeSetName?: string;
+
+  /**
+   * Always deploy, even if templates are identical.
+   * @default false
+   */
+  readonly force?: boolean;
+
+  /**
+   * Rollback failed deployments
+   *
+   * @default true
+   */
+  readonly rollback?: boolean;
+
+  /**
+   * ARNs of SNS topics that CloudFormation will notify with stack related events
+   *
+   * @default - no notifications
+   */
+  readonly notificationArns?: string[];
+
+  /**
+   * What kind of security changes require approval
+   *
+   * @default RequireApproval.Never
+   */
+  readonly requireApproval?: RequireApproval;
+
+  /**
+   * Whether to execute the ChangeSet
+   * Not providing `execute` parameter will result in execution of ChangeSet
+   * @default true
+   */
+  readonly execute?: boolean;
+
+  /**
+   * Additional parameters for CloudFormation at deploy time
+   * @default {}
+   */
+  readonly parameters?: { [name: string]: string };
+
+  /**
+   * Use previous values for unspecified parameters
+   *
+   * If not set, all parameters must be specified for every deployment.
+   *
+   * @default true
+   */
+  readonly usePreviousParameters?: boolean;
+
+  /**
+   * Path to file where stack outputs will be written after a successful deploy as JSON
+   * @default - Outputs are not written to any file
+   */
+  readonly outputsFile?: string;
+
+  /**
+   * Whether we are on a CI system
+   *
+   * @default false
+   */
+  readonly ci?: boolean;
+}

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/commands/destroy.ts

@@ -0,0 +1,20 @@
+import { DefaultCdkOptions } from './common';
+
+/**
+ * Options to use with cdk destroy
+ */
+export interface DestroyOptions extends DefaultCdkOptions {
+  /**
+   * Do not ask for permission before destroying stacks
+   *
+   * @default false
+   */
+  readonly force?: boolean;
+
+  /**
+   * Only destroy the given stack
+   *
+   * @default false
+   */
+  readonly exclusively?: boolean;
+}

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/commands/index.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './deploy';
+export * from './destroy';

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/index.ts

@@ -0,0 +1,3 @@
+export * from './schema';
+export * from './commands';
+export * from './test-case';

packages/@aws-cdk/cloud-assembly-schema/lib/integ-tests/schema.ts

@@ -0,0 +1,26 @@
+import { TestCase } from './test-case';
+/**
+ * Definitions for the integration testing manifest
+ */
+export interface IntegManifest {
+  /**
+   * Version of the manifest
+   */
+  readonly version: string;
+
+  /**
+   * Enable lookups for this test. If lookups are enabled
+   * then `stackUpdateWorkflow` must be set to false.
+   * Lookups should only be enabled when you are explicitely testing
+   * lookups.
+   *
+   * @default false
+   */
+  readonly enableLookups?: boolean;
+
+  /**
+   * test cases
+   */
+  readonly testCases: { [testName: string]: TestCase };
+}
+