feat(aws-codebuild): Introduce a CodePipeline test Action. (#873)

packages/@aws-cdk/aws-cloudformation/test/test.pipeline-actions.ts

@@ -196,6 +196,10 @@ class StageDouble implements cpapi.IStage, cpapi.IInternalStage {
     this.pipelineRole = pipelineRole;
   }
 
+  public grantPipelineBucketRead() {
+    throw new Error('Unsupported');
+  }
+
   public grantPipelineBucketReadWrite() {
     throw new Error('Unsupported');
   }

packages/@aws-cdk/aws-codebuild/README.md

@@ -75,7 +75,30 @@ You can also add the Project to the Pipeline directly:
 
 ```ts
 // equivalent to the code above:
-project.addBuildToPipeline(buildStage, 'CodeBuild');
+const buildAction = project.addBuildToPipeline(buildStage, 'CodeBuild');
+```
+
+In addition to the build Action,
+there is also a test Action.
+It works very similarly to the build Action,
+the only difference is that the test Action does not always produce an output artifact.
+
+Examples:
+
+```ts
+new codebuild.PipelineTestAction(this, 'IntegrationTest', {
+    stage: buildStage,
+    project,
+    // outputArtifactName is optional - if you don't specify it,
+    // the Action will have an undefined `outputArtifact` property
+    outputArtifactName: 'IntegrationTestOutput',
+});
+
+// equivalent to the code above:
+project.addTestToPipeline(buildStage, 'IntegrationTest', {
+    // of course, this property is optional here as well
+    outputArtifactName: 'IntegrationTestOutput',
+});
 ```
 
 ### Using Project as an event target

packages/@aws-cdk/aws-codebuild/lib/pipeline-actions.ts

@@ -44,33 +44,84 @@ export class PipelineBuildAction extends codepipeline.BuildAction {
     // https://qiita.com/ikeisuke/items/2fbc0b80b9bbd981b41f
 
     super(parent, name, {
-      stage: props.stage,
-      runOrder: props.runOrder,
       provider: 'CodeBuild',
-      inputArtifact: props.inputArtifact,
-      outputArtifactName: props.outputArtifactName,
       configuration: {
-        ProjectName: props.project.projectName
-      }
+        ProjectName: props.project.projectName,
+      },
+      ...props,
     });
 
-    const actions = [
+    setCodeBuildNeededPermissions(props.stage, props.project, true);
+  }
+}
+
+/**
+ * Common properties for creating {@link PipelineTestAction} -
+ * either directly, through its constructor,
+ * or through {@link ProjectRef#addTestToPipeline}.
+ */
+export interface CommonPipelineTestActionProps extends codepipeline.CommonActionProps {
+  /**
+   * The source to use as input for this test.
+   *
+   * @default CodePipeline will use the output of the last Action from a previous Stage as input
+   */
+  inputArtifact?: codepipeline.Artifact;
+
+  /**
+   * The optional name of the output artifact.
+   * If you provide a value here,
+   * then the `outputArtifact` property of your Action will be non-null.
+   * If you don't, `outputArtifact` will be `null`.
+   *
+   * @default the Action will not have an output artifact
+   */
+  outputArtifactName?: string;
+}
+
+/**
+ * Construction properties of the {@link PipelineTestAction CodeBuild test CodePipeline Action}.
+ */
+export interface PipelineTestActionProps extends CommonPipelineTestActionProps,
+    codepipeline.CommonActionConstructProps {
+  /**
+   * The build Project.
+   */
+  project: ProjectRef;
+}
+
+export class PipelineTestAction extends codepipeline.TestAction {
+  constructor(parent: cdk.Construct, name: string, props: PipelineTestActionProps) {
+    super(parent, name, {
+      provider: 'CodeBuild',
+      configuration: {
+        ProjectName: props.project.projectName,
+      },
+      ...props,
+    });
+
+    // the Action needs write permissions only if it's producing an output artifact
+    setCodeBuildNeededPermissions(props.stage, props.project, !!props.outputArtifactName);
+  }
+}
+
+function setCodeBuildNeededPermissions(stage: codepipeline.IStage, project: ProjectRef,
+                                       needsPipelineBucketWrite: boolean) {
+  // grant the Pipeline role the required permissions to this Project
+  stage.pipelineRole.addToPolicy(new iam.PolicyStatement()
+    .addResource(project.projectArn)
+    .addActions(
       'codebuild:BatchGetBuilds',
       'codebuild:StartBuild',
       'codebuild:StopBuild',
-    ];
+    ));
 
-    props.stage.pipelineRole.addToPolicy(new iam.PolicyStatement()
-      .addResource(props.project.projectArn)
-      .addActions(...actions));
-
-    // allow codebuild to read and write artifacts to the pipline's artifact bucket.
-    if (props.project.role) {
-      props.stage.grantPipelineBucketReadWrite(props.project.role);
+  // allow the Project access to the Pipline's artifact Bucket
+  if (project.role) {
+    if (needsPipelineBucketWrite) {
+      stage.grantPipelineBucketReadWrite(project.role);
+    } else {
+      stage.grantPipelineBucketRead(project.role);
     }
-
-    // policy must be added as a dependency to the pipeline!!
-    // TODO: grants - build.addResourcePermission() and also make sure permission
-    // includes the pipeline role AWS principal.
   }
 }

packages/@aws-cdk/aws-codebuild/lib/project.ts

@@ -8,7 +8,10 @@ import s3 = require('@aws-cdk/aws-s3');
 import cdk = require('@aws-cdk/cdk');
 import { BuildArtifacts, CodePipelineBuildArtifacts, NoBuildArtifacts } from './artifacts';
 import { cloudformation } from './codebuild.generated';
-import { CommonPipelineBuildActionProps, PipelineBuildAction } from './pipeline-actions';
+import {
+  CommonPipelineBuildActionProps, CommonPipelineTestActionProps,
+  PipelineBuildAction, PipelineTestAction
+} from './pipeline-actions';
 import { BuildSource, NoSource } from './source';
 
 const CODEPIPELINE_TYPE = 'CODEPIPELINE';
@@ -97,6 +100,23 @@ export abstract class ProjectRef extends cdk.Construct implements events.IEventR
     });
   }
 
+  /**
+   * Convenience method for creating a new {@link PipelineTestAction} test Action,
+   * and adding it to the given Stage.
+   *
+   * @param stage the Pipeline Stage to add the new Action to
+   * @param name the name of the newly created Action
+   * @param props the properties of the new Action
+   * @returns the newly created {@link PipelineBuildAction} test Action
+   */
+  public addTestToPipeline(stage: codepipeline.IStage, name: string, props: CommonPipelineTestActionProps = {}): PipelineTestAction {
+    return new PipelineTestAction(this, name, {
+      stage,
+      project: this,
+      ...props,
+    });
+  }
+
   /**
    * Defines a CloudWatch event rule triggered when the build project state
    * changes. You can filter specific build status events using an event

packages/@aws-cdk/aws-codepipeline-api/lib/action.ts

@@ -92,6 +92,12 @@ export interface IStage {
    */
   readonly _internal: IInternalStage;
 
+  /* Grants read permissions to the Pipeline's S3 Bucket to the given Identity.
+   *
+   * @param identity the IAM Identity to grant the permissions to
+   */
+  grantPipelineBucketRead(identity: iam.IPrincipal): void;
+
   /**
    * Grants read & write permissions to the Pipeline's S3 Bucket to the given Identity.
    *
@@ -238,25 +244,6 @@ export abstract class Action extends cdk.Construct {
   }
 }
 
-// export class TestAction extends Action {
-//   constructor(parent: Stage, name: string, provider: string, artifactBounds: ActionArtifactBounds, configuration?: any) {
-//     super(parent, name, {
-//       category: ActionCategory.Test,
-//       provider,
-//       artifactBounds,
-//       configuration
-//     });
-//   }
-// }
-
-// export class CodeBuildTest extends TestAction {
-//   constructor(parent: Stage, name: string, project: codebuild.ProjectArnAttribute) {
-//     super(parent, name, 'CodeBuild', { minInputs: 1, maxInputs: 1, minOutputs: 0, maxOutputs: 1 }, {
-//       ProjectName: project
-//     });
-//   }
-// }
-
 // export class ElasticBeanstalkDeploy extends DeployAction {
 //   constructor(parent: Stage, name: string, applicationName: string, environmentName: string) {
 //     super(parent, name, 'ElasticBeanstalk', { minInputs: 1, maxInputs: 1, minOutputs: 0, maxOutputs: 0 }, {

packages/@aws-cdk/aws-codepipeline-api/lib/index.ts

@@ -3,4 +3,5 @@ export * from './action';
 export * from './build-action';
 export * from './deploy-action';
 export * from './source-action';
+export * from './test-action';
 export * from './validation';

packages/@aws-cdk/aws-codepipeline-api/lib/test-action.ts

@@ -0,0 +1,74 @@
+import cdk = require("@aws-cdk/cdk");
+import { Action, ActionCategory, CommonActionConstructProps, CommonActionProps } from "./action";
+import { Artifact } from "./artifact";
+
+/**
+ * Construction properties of the low-level {@link TestAction test Action}.
+ */
+export interface TestActionProps extends CommonActionProps, CommonActionConstructProps {
+  /**
+   * The source to use as input for this test.
+   *
+   * @default CodePipeline will use the output of the last Action from a previous Stage as input
+   */
+  inputArtifact?: Artifact;
+
+  /**
+   * The optional name of the output artifact.
+   * If you provide a value here,
+   * then the `outputArtifact` property of your Action will be non-null.
+   * If you don't, `outputArtifact` will be `null`.
+   *
+   * @default the Action will not have an output artifact
+   */
+  outputArtifactName?: string;
+
+  /**
+   * The service provider that the action calls.
+   *
+   * @example 'CodeBuild'
+   */
+  provider: string;
+
+  /**
+   * The source action owner (could be 'AWS', 'ThirdParty' or 'Custom').
+   *
+   * @default 'AWS'
+   */
+  owner?: string;
+
+  /**
+   * The action's configuration. These are key-value pairs that specify input values for an action.
+   * For more information, see the AWS CodePipeline User Guide.
+   *
+   * http://docs.aws.amazon.com/codepipeline/latest/userguide/reference-pipeline-structure.html#action-requirements
+   */
+  configuration?: any;
+}
+
+/**
+ * The low-level test Action.
+ *
+ * Test Actions are very similar to build Actions -
+ * the difference is that test Actions don't have to have an output artifact.
+ *
+ * You should never need to use this class directly,
+ * instead preferring the concrete implementations,
+ * like {@link codebuild.PipelineTestAction}.
+ */
+export abstract class TestAction extends Action {
+  public readonly outputArtifact?: Artifact;
+
+  constructor(parent: cdk.Construct, name: string, props: TestActionProps) {
+    super(parent, name, {
+      category: ActionCategory.Test,
+      artifactBounds: { minInputs: 1, maxInputs: 1, minOutputs: 0, maxOutputs: 0 },
+      ...props,
+    });
+
+    this.addInputArtifact(props.inputArtifact);
+    if (props.outputArtifactName) {
+      this.outputArtifact = this.addOutputArtifact(props.outputArtifactName);
+    }
+  }
+}

packages/@aws-cdk/aws-codepipeline/lib/stage.ts

@@ -110,6 +110,10 @@ export class Stage extends cdk.Construct implements actions.IStage, actions.IInt
     return this.validateHasActions();
   }
 
+  public grantPipelineBucketRead(identity: iam.IPrincipal): void {
+    this.pipeline.artifactBucket.grantRead(identity);
+  }
+
   public grantPipelineBucketReadWrite(identity: iam.IPrincipal): void {
     this.pipeline.artifactBucket.grantReadWrite(identity);
   }