integ-tests: better assertion data handling

Describe the feature

Currently assertions can do retrieve data with two different purposes.

Retrieve data in order to assert against all or part of the data
Retrieve data in order to return part of it to be used by other resources in the stack.

For example, If I want to retrieve a message from a SQS queue

{
  "Messages": [
    {
      "Body":
      "{\"LifecycleTransition\":\"autoscaling:EC2_INSTANCE_LAUNCHING\",\"LifecycleActionToken\":\"some_token\"}"
    }
  ]
}

I would first retrieve the data

const message = integ.assertions.awsApiCall('SQS', 'receiveMessage', {
  QueueUrl: queueUrl,
});

And then I might want to assert some value

message.assertAtPath(
  'Messages.0.Body.LifecycleTransition', 
  ExpectedResult.stringLikeRegexp('autoscaling:EC2_INSTANCE_LAUNCHING'),
).waitForAssertions();

Or I might want to retrieve a value to use later

const token = message.getAttString('Messsages.0.Body.LifecycleActionToken');

In this case the custom resource should only return the token (currently it returns the entire object and you just get a reference to the token attribute).

Use Case

See above

Proposed Solution

Currently we retrieve the data and (optionally) flatten it in the sdk handler. We are also automatically attempting to parse any JSON strings in the response. Instead we should just be returning the entire response from this handler and allow the other handlers to process the data.

Using the above example, the sdk handler would return the entire message response as is. Then the assertion handler would perform any assertions and return the result of the assertion. To do this we need to introduce some functionality to parse any JSON strings that are part of the response.

One method could be to introduce some special string like <PARSE> which tells the provider to parse the next item.

message.assertAtPath('Messages.0.<PARSE>.Body.LifecycleTransition', ...);

This same method could be used in the handler that will return any values

message.getAttString('Messages.0.<PARSE>.Body.LifecycleActionToken');

Other Information

No response

Acknowledgements

[X] I may be able to implement this feature request
[ ] This feature might incur a breaking change

CDK version used

any

Environment details (OS name and version, etc.)

any

aws / aws-cdk