@aws-cdk/integ-runner 2.200.0 → 2.200.2

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

@@ -4,9 +4,9 @@ import type { IntegTest } from './integration-tests';
 import type { ICdk } from '../engines/cdk-interface';
 import type { DestructiveChange } from '../workers/common';
 /**
- * Options for creating an integration test runner
+ * Options for creating an integ helper
  */
-export interface IntegRunnerOptions {
+export interface CdkIntegHelperOptions {
     /**
      * Information about the test to run
      */
@@ -62,16 +62,36 @@ export interface IntegRunnerOptions {
     readonly caBundlePath?: string;
 }
 /**
- * The different components of a test name
+ * Whether to synthesize the actual snapshot with lookups enabled or not.
+ *
+ * If either `true` or `false`, we send context in or not while synthesizing,
+ * and if the generated snapshot test definition requests a different value we
+ * will synth again.
+ *
+ * For `dont-care`, we do send in the context but we never resynth.
  */
+export type LegacyEnableLookups = true | false | 'dont-care';
 /**
- * Represents an Integration test runner
+ * Class with some helper routines for running CDK snapshots and integration tests.
+ *
+ * A "golden snapshot" is the snapshot that is stored permanently in version
+ * control, that new runs are compared against (stored in a directory named
+ * `<test-name>.snapshot`).
+ *
+ * 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 abstract class IntegRunner {
+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 snapshot will be stored
+     * The directory where the golden snapshot will be stored
      */
-    readonly snapshotDir: string;
+    readonly goldenSnapshotDir: string;
     /**
      * An instance of the CDK  CLI
      */
@@ -85,50 +105,54 @@ export declare abstract class IntegRunner {
      *
      * Path to the integ test source file, relative to `this.directory`.
      */
-    protected readonly cdkApp: string;
+    readonly cdkApp: string;
     /**
      * The path where the `cdk.context.json` file
      * will be created
      */
-    protected readonly cdkContextPath: string;
+    readonly cdkContextPath: string;
     /**
      * The working directory that the integration tests will be
      * executed from
      */
-    protected readonly directory: string;
+    readonly directory: string;
     /**
      * The test to run
      */
-    protected readonly test: IntegTest;
+    private readonly test;
     /**
      * Default options to pass to the CDK CLI
      */
-    protected readonly defaultArgs: DefaultCdkOptions;
+    readonly defaultArgs: DefaultCdkOptions;
     /**
      * The directory where the CDK will be synthed to
      *
      * Relative to cwd.
      */
-    protected readonly cdkOutDir: string;
+    readonly cdkOutDir: string;
     /**
      * The profile to use for the CDK CLI calls
      */
-    protected readonly profile?: string;
+    readonly profile?: string;
     /**
      * Show output from the integ test run.
      */
-    protected readonly showOutput: boolean;
-    protected _destructiveChanges?: DestructiveChange[];
+    private readonly showOutput;
+    _destructiveChanges?: DestructiveChange[];
     private legacyContext?;
     private _expectedTestSuite?;
-    private _actualTestSuite?;
-    constructor(options: IntegRunnerOptions);
+    private _actualSnapshot?;
+    private _legacyEnableLookups?;
     /**
-     * Return the list of expected (i.e. existing) test cases for this integration test
+     * Private constructor to prevent inheritance.
      */
-    expectedTests(): Promise<{
-        [testName: string]: TestCase;
-    } | undefined>;
+    private constructor();
+    /**
+     * Configure the legacy enableLookups value to use when generating the actual snapshot.
+     *
+     * Must be set before using snapshot methods.
+     */
+    configureLegacyEnableLookups(enableLookups: LegacyEnableLookups): void;
     /**
      * Return the list of actual (i.e. new) test cases for this integration test
      */
@@ -140,7 +164,29 @@ export declare abstract class IntegRunner {
      * existing "expected" snapshot
      * This will synth and then load the integration test manifest
      */
-    generateActualSnapshot(): Promise<IntegTestSuite | LegacyIntegTestSuite>;
+    private generateActualSnapshot;
+    /**
+     * Synth the actual application to the given directory, for purposes of generating/validating a snapshot
+     *
+     * `legacyEnableLookups` is to preserve historical behavior for a while:
+     * traditionally, the application would only be seeded with context if
+     * `enableLookups` was true, and this information would come from the test
+     * definition.
+     *
+     * - Since the test definition comes from inside the app, this requires a
+     *   synth just to get the test definition, and then another synth to generate
+     *   the actual snapshot with the correct context, which is time consuming.
+     * - Given that the context is fixed and fake, it could always have been passed.
+     *
+     * However, the snapshot contents themselves depend on the context flag, and changing
+     * this behavior now invalidates all snapshots everywhere, which is annoying for upgrading.
+     *
+     * So we will use the behavior from the GOLDEN SNAPSHOT's test definition to
+     * 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
      */
@@ -148,11 +194,12 @@ export declare abstract class IntegRunner {
     /**
      * The test suite from the existing snapshot
      */
-    protected expectedTestSuite(): Promise<IntegTestSuite | LegacyIntegTestSuite | undefined>;
+    expectedTestSuite(): Promise<IntegTestSuite | LegacyIntegTestSuite | undefined>;
+    actualSnapshot(): Promise<SnapshotAndTestDefinition>;
     /**
      * The test suite from the new "actual" snapshot
      */
-    protected actualTestSuite(): Promise<IntegTestSuite | LegacyIntegTestSuite>;
+    private actualTestSuite;
     /**
      * Load the integ manifest which contains information
      * on how to execute the tests
@@ -160,8 +207,8 @@ export declare abstract class IntegRunner {
      * from the cloud assembly. If it doesn't exist, then we fallback to the
      * "legacy mode" and create a manifest from pragma
      */
-    protected loadManifest(dir?: string): Promise<IntegTestSuite | LegacyIntegTestSuite>;
-    protected cleanup(): void;
+    loadManifest(dir?: string): Promise<IntegTestSuite | LegacyIntegTestSuite>;
+    cleanup(): void;
     /**
      * If there are any destructive changes to a stack then this will record
      * those in the manifest.json file
@@ -176,13 +223,13 @@ export declare abstract class IntegRunner {
      * disabled and then delete assets that relate to that stack. It does that
      * by reading the asset manifest for the stack and deleting the asset source
      */
-    protected removeAssetsFromSnapshot(): Promise<void>;
+    private removeAssetsFromSnapshot;
     /**
      * Remove the asset cache (.cache/) files from the snapshot.
      * These are a cache of the asset zips, but we are fine with
      * re-zipping on deploy
      */
-    protected removeAssetsCacheFromSnapshot(): void;
+    private removeAssetsCacheFromSnapshot;
     /**
      * Create the new snapshot.
      *
@@ -193,14 +240,14 @@ export declare abstract class IntegRunner {
      * If lookups are disabled (which means the stack is env agnostic) then just copy
      * the assembly that was output by the deployment
      */
-    protected createSnapshot(): Promise<void>;
+    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 cleanupSnapshot;
-    protected getContext(additionalContext?: Record<string, any>): Record<string, any>;
+    private cleanupGoldenSnapshot;
+    getContext(additionalContext?: Record<string, any>): Record<string, any>;
 }
 export declare const DEFAULT_SYNTH_OPTIONS: {
     context: {
@@ -325,4 +372,8 @@ export declare function currentlyRecommendedAwsCdkLibFlags(): {
     "@aws-cdk/aws-batch:defaultToAL2023": boolean;
     "@aws-cdk/core:annotationsInValidationReport": boolean;
 };
-//# sourceMappingURL=runner-base.d.ts.map
+export interface SnapshotAndTestDefinition {
+    readonly testDefinition: IntegTestSuite | LegacyIntegTestSuite;
+    readonly snapshotDirectory: string;
+}
+//# sourceMappingURL=cdk-integ-helper.d.ts.map

package/lib/runner/cdk-integ-helper.d.ts.map

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