docs: update INTEGRATION_TESTS.md

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:
@@ -247,7 +244,7 @@ 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,12 +259,32 @@ 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
+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.
+
+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: