(integ-runner): IntegTestRunner ignores profile from testcase cdkCommandOptions.

[eriytt]

Describe the bug

Profiles specified in IntegTests like so:

new IntegTest(someApp, "sometest", {
...
  cdkCommandOptions: {
    deploy: {
      args: {
        profile: "some-profile",
      },
...

seems to be ignored during deploy. I believe it happens here:
https://github.com/aws/aws-cdk-cli/blob/main/packages/%40aws-cdk/integ-runner/lib/runner/integ-test-runner.ts#L249

where actualTestCase.cdkCommandOptions.deploy.args.profile is completely disregarded.

This is a problem that has occurred before, and I believe it was fixed somewhere around 2.194.2, but I can't seem to find the corresponding issue right now, maybe there never was one. I know the fix was commited the exact. same day I pinpointed the problem back then.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Version

2.194.2

Expected Behavior

Profile from cdkCommandOptions should be used if specified.

Current Behavior

Default profile (or from --profiles on command line) is used.

Reproduction Steps

• Specify test with cdkCommandOptions.deploy.args.profile
• Run test with some other default profile
• Check cloudtrail for example for ExecuteChangeSet and not the userIdentity

Possible Solution

            profile: actualTestCase.cdkCommandOptions?.deploy?.args?.profile ?? this.profile,

Additional Information/Context

We use this to test deployment with different sets of permissions.

CDK CLI Version

2.1027.0 (build 5fc1b13)

Framework Version

No response

Node.js Version

v22.22.1

OS

All

Language

TypeScript

Language Version

No response

Other information

No response

[sai-ray]

Hey @eriytt , thanks for bringing this up. The repro steps and the pointer to the code made it much easier to track down. Have a fix up in #1232.

The profile value actually does reach the engine correctly through the spread, so the issue was one level deeper than integ-test-runner.ts:249 . ToolkitLibRunnerEngine was creating a single Toolkit with credentials locked at construction and was never checking the per-call profile. This was a capability that worked implicitly in the old cli-wrapper engine but got lost when the toolkit-lib engine took over.

[mrgrain]

We are also planning to deprecate the cdkCommandOptions option feature in the near future (integ-tests-alpha is still experimental).

We use this feature, specifically the profile and toolkitStackName to test deployment of some of our tests/stacks with limited credentials. Is there some planned per-IntegTest replacement for cdkCommandOptions planned?

@eriytt To be clear, we are committed to supporting valid and useful use cases. I believe yours is one. Can you give me some more details on how you are using this feature? Specifically I am curious if if you need profile and toolkitStackName to be defined with the test case or if a integ-runner based solution would be suitable for you.

Our current thinking is that test cases should not define implementation details like that. Instead that's part of the test running regime (i.e. integ-runner). What we think test cases should do is declare requirements, e.g. only run this in certain regions.

Background

cdkCommandOptions currently allows setting options for deploy and destroy (full list). It includes all options, including some that don't make sense (like color) and a lot of them were never supported, even in the old cli based engine.

Then there are options like profile that are flat out conflicting with integ-runner itself. What happens if your test case specifies profile foo but intege-runner is executed with intege-runner --profiles baz,bar? What should happen?

Finally, to us, it seems inconsistent to have independent options for deploy and destroy. Why should they use a different profile or proxy config?

Going forward

There's a relatively clear list of features we want to carry over and keep supporting in one way or another. This is what I've got so far:

Features that belong on IntegTest as top-level props

These are genuinely per-test-case concerns — they describe what the test needs, not how to run it:

• expectError + expectedMessage → expectDeployFailure - negative testing (asserting deploy fails with a specific message) is valuable
• deploy.args.parameters → cfnParameters - some stacks use CfnParameter and need values passed at deploy time via --parameters. Without this, there's no way to write integ tests for parameter-driven stacks.

Features that belong on integ-runner

These are environment/runner concerns. The person running the tests should control them, not the test definition. Notably, some of these actively conflict with runner-level config (e.g. what happens if the test specifies profile foo but
integ-runner is executed with --profiles baz,bar?):

• deploy.enabled / destroy.enabled - which workflow steps to run is a runner decision, not a test declaration (e.g. integ-runner --synth-only)
• profile, roleArn - credential/identity config (@eriytt - we think the right model is something like integ-runner --profile limited-creds or a runner config file, rather than baking it into the test)
• toolkitStackName - bootstrap config, should be a runner-level setting (@eriytt - would that work for you as a runner setting?)
• rollback - fits with the existing --no-clean flag as a runner-level execution concern, might need extending
• proxy, caBundlePath, ec2Creds - network/credential environment config

Settings we are inclined to drop

These are either internal runner implementation details that should never be user-configurable, redundant with what the runner already manages, or were never actually supported:

• outputsFile - the IntegTest assertions API (httpApiCall, awsApiCall, etc.) provides a better way to validate post-deploy state
• context - context can already be provided via App and Stack constructs at synth time
• concurrency - the runner controls parallelism
• stacks, all, exclusively - the runner already knows which stacks to deploy from the test case
• execute, force, staging - the runner manages the deploy lifecycle
• notificationArns - niche; not sure if used or ever worked in practice
• requireApproval - the runner always sets this to NEVER
• usePreviousParameters, reuseAssets, changeSetName - too low-level; the runner handles these
• app, output - controlled by the runner
• assetMetadata, pathMetadata, versionReporting, lookups, notices, strict, ignoreErrors - synthesis/metadata flags managed by the runner
• verbose, debug, trace, color, json, ci - internal runner output controls

---

We'd love feedback on this breakdown. If you have a use case that doesn't fit neatly into the above, please let us know - we want to make sure we're not dropping anything that people actually depend on.