Merge branch 'main' into fix/stepfunctions-tasks-logs-polocy

.github/workflows/request-cli-integ-test.yml

@@ -19,7 +19,7 @@ jobs:
           persist-credentials: false
       - name: Find changed cli files
         id: changed-cli-files
-        uses: tj-actions/changed-files@408093d9ff9c134c33b974e0722ce06b9d6e8263
+        uses: tj-actions/changed-files@95690f9ece77c1740f4a55b7f1de9023ed6b1f87
         with:
           base_sha: ${{ github.event.pull_request.base.sha }}
           files_yaml: |
@@ -46,7 +46,7 @@ jobs:
           git config --global user.email 'aws-cdk-automation@users.noreply.github.com'
           git push --force --atomic https://github.com/${{ github.repository }}.git FETCH_HEAD:test-main-pipeline
       - name: Explain next steps
-        uses: thollander/actions-comment-pull-request@d61db783da9abefc3437960d0cce08552c7c004f
+        uses: thollander/actions-comment-pull-request@1d3973dc4b8e1399c0620d3f2b1aa5e795465308
         with:
           message: |
             :arrow_right: **PR build request submitted to `test-main-pipeline`** :arrow_left:

CONTRIBUTING.md

@@ -485,16 +485,14 @@ CDK integration tests.
 
 ### Step 4: Pull Request
 
-* Create a commit with your changes and push them to a
-  [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+* Create a [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the CDK repository.
+* Create a new branch for your change, and push the change commits on it.
   > [!IMPORTANT]
-  > We will not be able to accept your contribution if you do not allow commits to your PR branch, as it introduces
-  > friction in our review process and breaks our automation that syncs with the main branch. In these scenarios, we will close
-  > your pull request and ask that you recreate it with the necessary permissions.
-  > This means that you must contribute from a fork within your personal account (as opposed to an organization owned account) and also develop
-  > your contribution on a branch other than `main`. See
-  > [Allowing changes to a pull request branch created from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
-  > for more information.
+  > Your pull request must be based off of a branch in a personal account (not an organization owned account, and not the `main` branch).
+  > You must also have the setting enabled that [allows the CDK team to push changes to your branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) (this setting is enabled by default for personal accounts,
+  > and cannot be enabled for organization owned accounts).
+  > The reason for this is that our automation needs to synchronize your branch with our `main` after it has been approved, and
+  > we cannot do that if we cannot push to your branch.
   
   > [!NOTE]
   > CDK core members can push to a branch on the AWS CDK repo (naming convention: `<user>/<feature-bug-name>`).

INTEGRATION_TESTS.md

@@ -24,7 +24,7 @@ All Construct libraries in the CDK code base have integration tests that serve t
    This is done by running `yarn integ` which will run `cdk deploy` across all of the integration tests in that package.
    If you are developing a new integration test or for some other reason want to work on a single integration test
    over and over again without running through all the integration tests you can do so using
-   `yarn integ integ.test-name.js` .Remember to set up AWS credentials before doing this.
+   `yarn integ integ.test-name.js`. Remember to set up AWS credentials before doing this.
 3. (Optionally) Acts as a way to validate that constructs set up the CloudFormation resources as expected.
    A successful CloudFormation deployment does not mean that the resources are set up correctly.
 
@@ -75,8 +75,7 @@ you have good test coverage.
 
 ### Creating a Test
 
-An integration tests is any file located in the `test/` directory that has a name that starts with `integ.`
-(e.g. `integ.*.ts`).
+Integration tests for stable modules live in `@aws-cdk-testing/framework-integ/test/MODULE_NAME/test/`. Alpha module integ tests still live in their `test/` directories. Names of integration tests start with integ (e.g. `integ.*.ts`).
 
 To create a new integration test, first create a new file, for example `integ.my-new-construct.ts`.
 The contents of this file should be a CDK app. For example, a very simple integration test for a
@@ -86,7 +85,7 @@ _integ.lambda.ts_
 ```ts
 import * as iam from 'aws-cdk-lib/aws-iam';
 import * as cdk from 'aws-cdk-lib/core';
-import * as lambda from '../lib';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
 import * as integ from '@aws-cdk/integ-tests-alpha';
 
 const app = new cdk.App();
@@ -102,8 +101,6 @@ const fn = new lambda.Function(stack, 'MyLambda', {
 new integ.IntegTest(app, 'LambdaTest', {
   testCases: [stack],
 });
-
-app.synth();
 ```
 
 To run the test you would run:
@@ -243,11 +240,13 @@ want to validate that the _integration_ connecting `StepFunctions` to the `Event
 way to do that is to actually trigger the `StateMachine` and validate that it was successful.
 
 ```ts
+import * as integ from '@aws-cdk/integ-tests-alpha';
+
 declare const app: App;
 declare const sm: sfn.StateMachine;
 declare const stack: Stack;
 
-const testCase = new IntegTest(app, 'PutEvents', {
+const testCase = new integ.IntegTest(app, 'PutEvents', {
   testCases: [stack],
 });
 
@@ -262,21 +261,47 @@ const describe = testCase.assertions.awsApiCall('StepFunctions', 'describeExecut
 });
 
 // assert the results
-describe.expect(ExpectedResult.objectLike({
+describe.expect(integ.ExpectedResult.objectLike({
   status: 'SUCCEEDED',
 }));
 ```
 
-Not every test requires an assertion. We typically do not need to assert CloudFormation behavior. For example, if we create an S3 Bucket
+If we want to pick out certain values from the api call response, we can use the `assertAtPath()` method, as in the [integ.pipeline-with-additional-inputs.ts](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk-testing/framework-integ/test/pipelines/test/integ.pipeline-with-additional-inputs.ts) integ test. Note that using the `outputPaths` optional parameter on the `awsApiCall()` function often interacts poorly with the `expect()` function. 
+
+```ts
+import * as integ from '@aws-cdk/integ-tests-alpha';
+
+declare const app: App;
+declare const stack: Stack;
+declare const pipelineName: string;
+declare const expectedString: string;
+
+const testCase = new integ.IntegTest(app, 'PipelineAdditionalInputsTest', {
+  testCases: [stack],
+});
+
+const source = testCase.assertions.awsApiCall('CodePipeline', 'GetPipeline', {
+  name: pipelineName,
+});
+
+// assert the value at the given path matches the expected string
+// the numbers index arryas in the json response object
+source.assertAtPath('pipeline.stages.0.actions.0.name', integ.ExpectedResult.stringLikeRegexp(expectedString));
+```
+A helpful trick is to deploy the integ test with `--no-clean` and then make the api call locally. We can then trace the path to specific values easily. For example, `> aws codepipeline get-pipeline --name MyFirstPipeline`.
+
+Adding assertions is prefered on all new integ tests; however, it is not strictly required. We typically do not need to assert CloudFormation behavior. For example, if we create an S3 Bucket
 with Encryption, we do not need to assert that Encryption is set on the bucket. We can trust that the CloudFormation behavior works.
 Some things you should look for in deciding if the test needs an assertion:
 
-- Integrations between services (i.e. integration libraries like `aws-cdk-lib/aws-lambda-destinations`, `aws-cdk-lib/aws-stepfunctions-tasks`, etc)
-- Anything that bundles or deploys custom code (i.e. does a Lambda function bundled with `aws-cdk-lib/aws-lambda-nodejs` still invoke or did we break bundling behavior)
+- Integrations between services (i.e. integration libraries like `aws-cdk-lib/aws-lambda-destinations`, `aws-cdk-lib/aws-stepfunctions-tasks`, etc).
+- All custom resources. Must assert the expected behavior of the lambda is correct.
+- Anything that bundles or deploys custom code (i.e. does a Lambda function bundled with `aws-cdk-lib/aws-lambda-nodejs` still invoke or did we break bundling behavior).
 - IAM/Networking connections.
   - This one is a bit of a judgement call. Most things do not need assertions, but sometimes we handle complicated configurations involving IAM permissions or
     Networking access.
 
+
 ## Running Integration Tests
 
 Most of the time you will only need to run integration tests for an individual module (i.e. `aws-lambda`). Other times you may need to run tests across multiple modules.