@aws-cdk/integ-runner 2.202.2 → 2.202.3

package/lib/runner/{cdk-integ-helper.d.ts → cdk-test-app.d.ts}

@@ -1,20 +1,17 @@
-import type { TestCase, DefaultCdkOptions } from '@aws-cdk/cloud-assembly-schema';
+import { type TestCase, type DefaultCdkOptions } from '@aws-cdk/cloud-assembly-schema';
 import { IntegTestSuite, LegacyIntegTestSuite } from './integ-test-suite';
+import type { DeployOptions, DestroyOptions, ICdk, WatchEvents } from '../engines/cdk-interface';
 import type { IntegTest } from './integration-tests';
-import type { ICdk } from '../engines/cdk-interface';
 import type { DestructiveChange } from '../workers/common';
 /**
- * Options for creating an integ helper
+ * Options for creating a CDK Cloud Assembly
  */
-export interface CdkIntegHelperOptions {
-    /**
-     * Information about the test to run
-     */
+export interface CdkTestAppOptions {
     readonly test: IntegTest;
     /**
      * The region where the test should be deployed
      */
-    readonly region: string;
+    readonly region?: string;
     /**
      * The AWS profile to use when invoking the CDK CLI
      *
@@ -31,11 +28,14 @@ export interface CdkIntegHelperOptions {
         [name: string]: string;
     };
     /**
-     * tmp cdk.out directory
+     * Where we will write the output of the CDK CLI, including the cloud assembly and the snapshot
      *
-     * @default - directory will be `cdk-integ.out.${testName}`
+     * Should be a string containing `{testName}`, will be used to generate a directory name in the same
+     * directory as the test itself.
+     *
+     * @default 'cdk-integ.out.{testName}.snapshot'
      */
-    readonly integOutDir?: string;
+    readonly outputDirectoryNameTemplate: string;
     /**
      * Instance of the CDK Toolkit Engine to use
      *
@@ -61,12 +61,20 @@ export interface CdkIntegHelperOptions {
      */
     readonly caBundlePath?: string;
     /**
-     * In unit test mode, leave the synth output directories, don't clean them.
+     * In unit test mode, we are using mocks for a lot of calls
      *
-     * Many of our tests use mocks and don't actually synth output directories, they are
-     * static and must not be deleted.
+     * Don't delete directories, and don't do checks whether files actually exist; the
+     * mocks will be there to produce the contents for files that are being read (although
+     * they are not there to pretend to have files themselves).
      */
-    readonly testingUsingMocksLeaveDirectories?: boolean;
+    readonly TESTING_usingMocks?: boolean;
+    /**
+     * We will only read the legacy test information if the test actually produced an output directory.
+     *
+     * For historical reasons the tests have been written so that they will expect to read
+     * legacy test information always. Force that behavior back for tests.
+     */
+    readonly TESTING_forceReadLegacyTestSuite?: boolean;
 }
 /**
  * Whether to synthesize the actual snapshot with lookups enabled or not.
@@ -88,55 +96,23 @@ export type LegacyEnableLookups = true | false | 'dont-care';
  * This is as opposed to other snapshots, which can be generated for example
  * temporarily in a temporary directory, to compare agains the golden snapshot.
  */
-export declare class CdkIntegHelper {
-    /**
-     * Factory method to create an instance of the CdkIntegHelper.
-     *
-     * Hiding the constructor to prevent inheritance.
-     */
-    static create(options: CdkIntegHelperOptions): CdkIntegHelper;
-    /**
-     * The directory where the golden snapshot will be stored
-     */
-    readonly goldenSnapshotDir: string;
+export declare class CdkTestApp {
+    private readonly options;
+    private readonly testSpecificContext?;
+    static forGoldenSnapshot(options: Omit<CdkTestAppOptions, 'outputDirectoryNameTemplate'>): Promise<CdkTestApp>;
+    static forComparison(options: Omit<CdkTestAppOptions, 'outputDirectoryNameTemplate'>): Promise<CdkTestApp>;
+    static forSpecificDirectory(options: CdkTestAppOptions): Promise<CdkTestApp>;
+    static forDeployment(options: Omit<CdkTestAppOptions, 'outputDirectoryNameTemplate'>): Promise<CdkTestApp>;
+    private static create;
     /**
      * An instance of the CDK  CLI
      */
-    readonly cdk: ICdk;
-    /**
-     * Pretty name of the test
-     */
-    readonly testName: string;
-    /**
-     * The value used in the '--app' CLI parameter
-     *
-     * Path to the integ test source file, relative to `this.directory`.
-     */
-    readonly cdkApp: string;
-    /**
-     * The path where the `cdk.context.json` file
-     * will be created
-     */
-    readonly cdkContextPath: string;
-    /**
-     * The working directory that the integration tests will be
-     * executed from
-     */
-    readonly directory: string;
-    /**
-     * The test to run
-     */
-    private readonly test;
+    private readonly cdk;
+    readonly outputDirectory: string;
     /**
      * Default options to pass to the CDK CLI
      */
-    readonly defaultArgs: DefaultCdkOptions;
-    /**
-     * The directory where the CDK will be synthed to
-     *
-     * Relative to cwd.
-     */
-    readonly temporarySnapshotDir: string;
+    private readonly defaultArgs;
     /**
      * The profile to use for the CDK CLI calls
      */
@@ -145,46 +121,49 @@ export declare class CdkIntegHelper {
      * Show output from the integ test run.
      */
     private readonly showOutput;
+    readonly test: IntegTest;
+    synthReproCommand: string;
     _destructiveChanges?: DestructiveChange[];
     private legacyContext?;
-    private _expectedTestSuite?;
-    private _actualSnapshot?;
+    private _testSuite?;
     private _legacyEnableLookups?;
-    private readonly deleteSynthDirectories;
-    /**
-     * Fields that require an async context to initialize.
-     */
-    private _asyncMembers?;
-    /**
-     * Private constructor to prevent inheritance.
-     */
+    readonly appCommand: string;
+    private hasValidRegion;
     private constructor();
-    /**
-     * Async initialization; copy information from an async context into variables so we can access them synchronously later.
-     *
-     * We call this automatically in all public async members, but if a consumer wants to access this context synchronously
-     * without calling an async members first, it needs to call this.
-     */
-    asyncInitialize(): Promise<void>;
-    private get asyncMembers();
     /**
      * Configure the legacy enableLookups value to use when generating the actual snapshot.
      *
      * Must be set before using snapshot methods.
      */
     configureLegacyEnableLookups(enableLookups: LegacyEnableLookups): void;
+    hasOutput(): Promise<boolean>;
     /**
-     * Return the list of actual (i.e. new) test cases for this integration test
+     * Return the test cases inside the output
      */
-    actualTests(): Promise<{
+    testCases(): {
         [testName: string]: TestCase;
-    } | undefined>;
+    };
+    /**
+     * The test suite from the output
+     */
+    get testSuite(): IntegTestSuite | LegacyIntegTestSuite;
+    /**
+     * If the snapshot already exists, load it
+     */
+    loadExistingSuite(): Promise<IntegTestSuite | LegacyIntegTestSuite | undefined>;
+    synthForSnapshotComparison(enableLookupsGuess: LegacyEnableLookups): Promise<IntegTestSuite | LegacyIntegTestSuite>;
+    synthForGoldenSnapshot(destructiveChanges: DestructiveChange[], enableLookups: LegacyEnableLookups): Promise<IntegTestSuite | LegacyIntegTestSuite>;
+    synthForDeployment(): Promise<IntegTestSuite | LegacyIntegTestSuite>;
     /**
-     * Generate a new "actual" snapshot which will be compared to the
-     * existing "expected" snapshot
-     * This will synth and then load the integration test manifest
+     * For a given cloud assembly return a collection of all templates
+     * that should be part of the snapshot and any required meta data.
+     *
+     * @param cloudAssemblyDir - The directory of the cloud assembly to look for snapshots
+     * @param pickStacks - Pick only these stacks from the cloud assembly
+     * @returns A SnapshotAssembly, the collection of all templates in this snapshot and required meta data
      */
-    private generateActualSnapshot;
+    snapshotAssembly(pickStacks?: string[]): SnapshotAssembly;
+    private readAssembly;
     /**
      * Synth the actual application to the given directory, for purposes of generating/validating a snapshot
      *
@@ -205,21 +184,12 @@ export declare class CdkIntegHelper {
      * determine whether to pass the context, and if the new actual snapshot has a
      * different value for `enableLookups`, we will throw away the old snapshot and synth again.
      */
-    private synthActualSnapshot;
-    actualSynthReproCommand(): string[];
-    /**
-     * Returns true if a snapshot already exists for this test
-     */
-    hasSnapshot(): boolean;
-    /**
-     * The test suite from the existing snapshot
-     */
-    expectedTestSuite(): Promise<IntegTestSuite | LegacyIntegTestSuite | undefined>;
-    actualSnapshot(): Promise<SnapshotAndTestDefinition>;
-    /**
-     * The test suite from the new "actual" snapshot
-     */
-    private actualTestSuite;
+    private synth;
+    deploy(deployArgs: Omit<DeployOptions, 'app' | 'requireApproval' | 'profile' | 'output' | 'lookups'>): Promise<import("../engines/cdk-interface").CdkDeployResult>;
+    destroy(destroyArgs: Omit<DestroyOptions, 'app' | 'force' | 'profile' | 'output'>): Promise<void>;
+    watch(watchArgs: Omit<DeployOptions, 'app' | 'requireApproval' | 'profile' | 'output' | 'lookups'>, watchEvents: WatchEvents): Promise<void>;
+    private setReproCommand;
+    private _loadLegacyTestSuite;
     cleanup(): void;
     /**
      * If there are any destructive changes to a stack then this will record
@@ -242,24 +212,13 @@ export declare class CdkIntegHelper {
      * re-zipping on deploy
      */
     private removeAssetsCacheFromSnapshot;
-    /**
-     * Create the new snapshot.
-     *
-     * If lookups are enabled, then we need create the snapshot by synth'ing again
-     * with the dummy context so that each time the test is run on different machines
-     * (and with different context/env) the diff will not change.
-     *
-     * If lookups are disabled (which means the stack is env agnostic) then just copy
-     * the assembly that was output by the deployment
-     */
-    createSnapshot(): Promise<void>;
     /**
      * Perform some cleanup steps after the snapshot is created
      * Anytime the snapshot needs to be modified after creation
      * the logic should live here.
      */
     private cleanupGoldenSnapshot;
-    getContext(additionalContext?: Record<string, any>): Record<string, any>;
+    getContext(forSnapshot: 'snapshot' | 'deployment'): Record<string, any>;
 }
 export declare const DEFAULT_SYNTH_OPTIONS: {
     context: {
@@ -386,8 +345,25 @@ export declare function currentlyRecommendedAwsCdkLibFlags(): {
     "@aws-cdk/core:annotationsInValidationReport": boolean;
     "@aws-cdk/core:defaultCrossStackReferences": string;
 };
-export interface SnapshotAndTestDefinition {
-    readonly testDefinition: IntegTestSuite | LegacyIntegTestSuite;
-    readonly snapshotDirectory: string;
+export interface SnapshotAssembly {
+    /**
+     * Map of stacks that are part of this assembly
+     */
+    [stackName: string]: {
+        /**
+         * All templates for this stack, including nested stacks
+         */
+        templates: {
+            [templateId: string]: any;
+        };
+        /**
+         * List of asset Ids that are used by this assembly
+         */
+        assets: string[];
+    };
 }
-//# sourceMappingURL=cdk-integ-helper.d.ts.map
+/**
+ * Default options to pass to the CDK CLI
+ */
+export declare const DEFAULT_ARGS: DefaultCdkOptions;
+//# sourceMappingURL=cdk-test-app.d.ts.map

package/lib/runner/cdk-test-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdk-test-app.d.ts","sourceRoot":"","sources":["cdk-test-app.ts"],"names":[],"mappings":"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"}