Testing & Utilities

/**
 * Suite of assertions that can be run on a CDK stack
 */
class Template {
  /**
   * Base your assertions on a synthesized CDK Stack
   */
  static fromStack(stack: Stack): Template;
  
  /**
   * Base your assertions from an existing CloudFormation template
   */
  static fromString(template: string): Template;
  
  /**
   * Base your assertions from an existing CloudFormation template
   */
  static fromJSON(template: { [key: string]: any }): Template;
  
  /**
   * Assert that the given number of resources of the given type exist in the template
   */
  resourceCountIs(type: string, count: number): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains a resource with the given properties
   */
  hasResourceProperties(type: string, props: any): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains a resource with the given logical ID
   */
  hasResource(type: string, props: any): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains an output with the given logical ID and properties
   */
  hasOutput(logicalId: string, props: any): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains a parameter with the given logical ID and properties
   */
  hasParameter(logicalId: string, props: any): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains a mapping with the given logical ID and properties
   */
  hasMapping(logicalId: string, props: any): void;
  
  /**
   * Assert that the CloudFormation template synthesized contains a condition with the given logical ID and properties
   */
  hasCondition(logicalId: string, props: any): void;
  
  /**
   * Get the JSON representation of the template
   */
  toJSON(): { [key: string]: any };
}

/**
 * Partial and special matching during template assertions
 */
class Match {
  /**
   * Use this matcher to assert that the target has a specified value at exactly the given key
   */
  static exact(pattern: any): Matcher;
  
  /**
   * Matches any target which is a subset of the provided pattern
   */
  static objectLike(pattern: { [key: string]: any }): Matcher;
  
  /**
   * Matches any array that contains all of the provided elements
   */
  static arrayContaining(pattern: any[]): Matcher;
  
  /**
   * Matches targets containing nested objects that have at least the provided keys
   */
  static objectContaining(pattern: { [key: string]: any }): Matcher;
  
  /**
   * Matches any string-ified JSON and applies the provided pattern after parsing it
   */
  static serializedJson(pattern: any): Matcher;
  
  /**
   * Matches any target which does NOT follow the provided pattern
   */
  static not(pattern: any): Matcher;
  
  /**
   * Matches any target that is absent from the provided pattern
   */
  static absent(): Matcher;
  
  /**
   * Matches any target
   */
  static anyValue(): Matcher;
  
  /**
   * Matches targets that are strings
   */
  static stringLikeRegexp(pattern: string): Matcher;
}

/**
 * Capture values while matching templates
 */
class Capture {
  constructor();
  
  /**
   * Retrieve the captured value
   */
  asString(): string;
  
  /**
   * Retrieve the captured value as a number
   */
  asNumber(): number;
  
  /**
   * Retrieve the captured value as a boolean
   */
  asBoolean(): boolean;
  
  /**
   * Retrieve the captured value as an array
   */
  asArray(): any[];
  
  /**
   * Retrieve the captured value as an object
   */
  asObject(): { [key: string]: any };
}

/**
 * A CDK Pipeline that uses CodePipeline to deploy CDK applications
 */
class CodePipeline extends PipelineBase {
  constructor(scope: Construct, id: string, props: CodePipelineProps);
  
  /**
   * Add a stage to the pipeline, to be deployed in sequence with other stages
   */
  addStage(stage: Stage, options?: AddStageOpts): StageDeployment;
  
  /**
   * Add a Wave to the pipeline, to be deployed in parallel with other waves
   */
  addWave(id: string, options?: WaveOptions): Wave;
  
  /**
   * Send the current pipeline definition to the engine
   */
  buildPipeline(): void;
  
  readonly cloudAssemblyFileSet: FileSet;
  readonly synth: IFileSetProducer;
  readonly waves: Wave[];
}

/**
 * Instructions for additional steps that are run at the stack level
 */
class CodeBuildStep extends Step {
  constructor(id: string, props: CodeBuildStepProps);
  
  /**
   * Add an additional output file set based on a directory
   */
  addOutputDirectory(directory: string): FileSet;
  
  /**
   * Export a variable from the build
   */
  exportedVariable(variableName: string): string;
  
  readonly commands: string[];
  readonly env: { [key: string]: string };
  readonly envFromCfnOutputs: { [key: string]: CfnOutput };
  readonly grantPrincipal: IPrincipal;
  readonly project: IProject;
  readonly projectName: string;
  readonly role: IRole;
}

import { Template, Match, Capture } from "aws-cdk-lib/assertions";
import { Stack } from "aws-cdk-lib";
import { Bucket } from "aws-cdk-lib/aws-s3";

// Create a test stack
const stack = new Stack();
new Bucket(stack, "TestBucket", {
  versioned: true,
});

// Test the stack
const template = Template.fromStack(stack);

// Assert resource count
template.resourceCountIs("AWS::S3::Bucket", 1);

// Assert resource properties
template.hasResourceProperties("AWS::S3::Bucket", {
  VersioningConfiguration: {
    Status: "Enabled",
  },
});

// Use pattern matching
template.hasResourceProperties("AWS::S3::Bucket", 
  Match.objectLike({
    VersioningConfiguration: Match.anyValue(),
  })
);

// Capture values for further testing
const capture = new Capture();
template.hasResourceProperties("AWS::S3::Bucket", {
  BucketName: capture,
});
expect(capture.asString()).toMatch(/testbucket/i);

interface CodePipelineProps {
  readonly synth: IFileSetProducer;
  readonly artifactBucket?: IBucket;
  readonly assetPublishingCodeBuildDefaults?: AssetPublishingCodeBuildDefaultsOptions;
  readonly cloudAssemblyBucket?: IBucket;
  readonly codeBuildDefaults?: CodeBuildOptions;
  readonly codePipeline?: Pipeline;
  readonly crossAccountKeys?: boolean;
  readonly dockerEnabledForSelfMutation?: boolean;
  readonly dockerEnabledForSynth?: boolean;
  readonly enableKeyRotation?: boolean;
  readonly pipelineName?: string;
  readonly publishAssetsInParallel?: boolean;
  readonly reuseCrossRegionSupportStacks?: boolean;
  readonly role?: IRole;
  readonly selfMutation?: boolean;
  readonly synthCodeBuildDefaults?: CodeBuildOptions;
  readonly useChangeSets?: boolean;
}

interface CodeBuildStepProps extends ShellStepProps {
  readonly buildEnvironment?: BuildEnvironment;
  readonly cache?: Cache;
  readonly fileSystemLocations?: IFileSystemLocation[];
  readonly logging?: LoggingOptions;
  readonly partialBuildSpec?: BuildSpec;
  readonly role?: IRole;
  readonly rolePolicyStatements?: PolicyStatement[];
  readonly securityGroups?: ISecurityGroup[];
  readonly subnetSelection?: SubnetSelection;
  readonly timeout?: Duration;
  readonly vpc?: IVpc;
}

interface ShellStepProps {
  readonly commands: string[];
  readonly additionalInputs?: { [name: string]: IFileSetProducer };
  readonly env?: { [key: string]: string };
  readonly envFromCfnOutputs?: { [key: string]: CfnOutput };
  readonly input?: IFileSetProducer;
  readonly installCommands?: string[];
  readonly primaryOutputDirectory?: string;
}

interface Matcher {
  readonly name: string;
  test(actual: any): MatchResult;
}

interface MatchResult {
  readonly match: boolean;
  readonly message: string;
}