fix: address PR aws#8299 review feedback for nested stack changeset support

- Fix recursion bug: use is_parent=True for proper 3+ level nesting
- Eliminate ~70 lines of duplicated inline logic via recursive call
- Replace sys.stdout.write with click.echo() for consistency
- Fix do_cli signature: align include_nested_stacks position with cli() call
- Fix guided mode: propagate user's include_nested_stacks flag (not hardcoded)
- Restore full assert_called_with in unit tests
- Add 9 new unit tests for nested stack display and error handling
- Improve integration test assertions for [Nested Stack:] header
- Coverage improved from 93.86% to 94.07% (above 94% threshold)

Author: dcabib

samcli/commands/deploy/command.py

@@ -271,17 +271,17 @@ def do_cli(
     metadata,
     guided,
     confirm_changeset,
-    include_nested_stacks=True,
-    region=None,
-    profile=None,
-    signing_profiles=None,
-    resolve_s3=False,
-    config_file=None,
-    config_env=None,
-    resolve_image_repos=False,
-    disable_rollback=False,
-    on_failure=None,
-    max_wait_duration=60,
+    include_nested_stacks,
+    region,
+    profile,
+    signing_profiles,
+    resolve_s3,
+    config_file,
+    config_env,
+    resolve_image_repos,
+    disable_rollback,
+    on_failure,
+    max_wait_duration,
 ):
     """
     Implementation of the ``cli`` method
@@ -312,6 +312,7 @@ def do_cli(
             config_env=config_env,
             config_file=config_file,
             disable_rollback=disable_rollback,
+            include_nested_stacks=include_nested_stacks,
         )
         guided_context.run()
     else:

samcli/commands/deploy/guided_context.py

@@ -62,6 +62,7 @@ def __init__(
         config_env=None,
         config_file=None,
         disable_rollback=None,
+        include_nested_stacks=True,
     ):
         self.template_file = template_file
         self.stack_name = stack_name
@@ -95,6 +96,7 @@ def __init__(
         self.color = Colored()
         self.function_provider = None
         self.disable_rollback = disable_rollback
+        self.include_nested_stacks = include_nested_stacks
 
     @property
     def guided_capabilities(self):
@@ -584,7 +586,7 @@ def run(self):
                 region=self.guided_region,
                 profile=self.guided_profile,
                 confirm_changeset=self.confirm_changeset,
-                include_nested_stacks=True,
+                include_nested_stacks=self.include_nested_stacks,
                 capabilities=self._capabilities,
                 signing_profiles=self.signing_profiles,
                 disable_rollback=self.disable_rollback,

samcli/lib/deploy/deployer.py

@@ -25,6 +25,7 @@
 from typing import Dict, List, Optional
 
 import botocore
+import click
 
 from samcli.commands._utils.table_print import MIN_OFFSET, newline_per_item, pprint_column_names, pprint_columns
 from samcli.commands.deploy import exceptions as deploy_exceptions
@@ -336,95 +337,25 @@ def _display_changeset_changes(
                     color=row_color,
                 )
 
-        # Recursively display nested stack changes with pagination
+        # Recursively display nested stack changes
         # Only process nested stacks when is_parent=True to avoid duplicates
         if is_parent:
             for nested in nested_changesets:
                 try:
                     # Display nested stack header
-                    sys.stdout.write(f"\n[Nested Stack: {nested['logical_id']}]\n")
-                    sys.stdout.flush()
-
-                    # Use paginator for nested changesets to handle large changesets
-                    nested_paginator = self._client.get_paginator("describe_change_set")
-                    nested_iterator = nested_paginator.paginate(ChangeSetName=nested["changeset_id"])
-
-                    nested_has_changes = False
-                    # Track nested-nested stacks for recursive processing
-                    deeply_nested_changesets = []
-
-                    for nested_item in nested_iterator:
-                        nested_cf_changes = nested_item.get("Changes", [])
-                        for change in nested_cf_changes:
-                            nested_has_changes = True
-                            resource_props = change.get("ResourceChange", {})
-                            action = resource_props.get("Action")
-                            resource_type = resource_props.get("ResourceType")
-                            logical_id = resource_props.get("LogicalResourceId")
-                            replacement = resource_props.get("Replacement")
-
-                            # Check for deeply nested stacks (3+ levels)
-                            deeply_nested_changeset_id = resource_props.get("ChangeSetId")
-                            if resource_type == "AWS::CloudFormation::Stack" and deeply_nested_changeset_id:
-                                deeply_nested_changesets.append(
-                                    {"changeset_id": deeply_nested_changeset_id, "logical_id": logical_id}
-                                )
-
-                            row_color = self.deploy_color.get_changeset_action_color(action=action)
-                            pprint_columns(
-                                columns=[
-                                    changes_showcase.get(action, action),
-                                    logical_id,
-                                    resource_type,
-                                    "N/A" if replacement is None else replacement,
-                                ],
-                                width=kwargs["width"],
-                                margin=kwargs["margin"],
-                                format_string=DESCRIBE_CHANGESET_FORMAT_STRING,
-                                format_args=kwargs["format_args"],
-                                columns_dict=DESCRIBE_CHANGESET_DEFAULT_ARGS.copy(),
-                                color=row_color,
-                            )
-
-                    if not nested_has_changes:
-                        pprint_columns(
-                            columns=["-", "-", "-", "-"],
-                            width=kwargs["width"],
-                            margin=kwargs["margin"],
-                            format_string=DESCRIBE_CHANGESET_FORMAT_STRING,
-                            format_args=kwargs["format_args"],
-                            columns_dict=DESCRIBE_CHANGESET_DEFAULT_ARGS.copy(),
+                    click.echo(f"\n[Nested Stack: {nested['logical_id']}]")
+
+                    # Get the stack name from the changeset to support recursive call
+                    nested_response = self._client.describe_change_set(ChangeSetName=nested["changeset_id"])
+                    nested_stack_name = nested_response.get("StackName")
+                    if nested_stack_name:
+                        # Recursively call to display nested changes (supports arbitrary nesting depth)
+                        self._display_changeset_changes(
+                            nested["changeset_id"], nested_stack_name, is_parent=True, **kwargs
                         )
-
-                    # Recursively process deeply nested stacks (3+ levels)
-                    for deeply_nested in deeply_nested_changesets:
-                        # Get the stack name from the changeset to support recursive call
-                        try:
-                            deeply_nested_response = self._client.describe_change_set(
-                                ChangeSetName=deeply_nested["changeset_id"]
-                            )
-                            deeply_nested_stack_name = deeply_nested_response.get("StackName")
-                            if deeply_nested_stack_name:
-                                # Print header for deeply nested stack
-                                sys.stdout.write(f"\n[Nested Stack: {deeply_nested['logical_id']}]\n")
-                                sys.stdout.flush()
-                                # Recursively call to display deeply nested changes
-                                self._display_changeset_changes(
-                                    deeply_nested["changeset_id"], deeply_nested_stack_name, is_parent=False, **kwargs
-                                )
-                        except Exception as e:
-                            LOG.debug(
-                                "Failed to describe deeply nested changeset %s: %s", deeply_nested["changeset_id"], e
-                            )
-                            sys.stdout.write(
-                                f"\n[Nested Stack: {deeply_nested['logical_id']}] - Unable to fetch changes: {str(e)}\n"
-                            )
-                            sys.stdout.flush()
-
                 except Exception as e:
                     LOG.debug("Failed to describe nested changeset %s: %s", nested["changeset_id"], e)
-                    sys.stdout.write(f"Unable to fetch changes: {str(e)}\n")
-                    sys.stdout.flush()
+                    click.echo(f"Unable to fetch changes: {str(e)}")
 
         return changes if changeset_found else None
 

schema/samcli.json

@@ -1233,7 +1233,7 @@
           "properties": {
             "parameters": {
               "title": "Parameters for the deploy command",
-              "description": "Available parameters for the deploy command:\n* guided:\nSpecify this flag to allow SAM CLI to guide you through the deployment using guided prompts.\n* template_file:\nAWS SAM template which references built artifacts for resources in the template. (if applicable)\n* no_execute_changeset:\nIndicates whether to execute the change set. Specify this flag to view stack changes before executing the change set.\n* fail_on_empty_changeset:\nSpecify whether AWS SAM CLI should return a non-zero exit code if there are no changes to be made to the stack. Defaults to a non-zero exit code.\n* confirm_changeset:\nPrompt to confirm if the computed changeset is to be deployed by SAM CLI.\n* disable_rollback:\nPreserves the state of previously provisioned resources when an operation fails.\n* on_failure:\nProvide an action to determine what will happen when a stack fails to create. Three actions are available:\n\n- ROLLBACK: This will rollback a stack to a previous known good state.\n\n- DELETE: The stack will rollback to a previous state if one exists, otherwise the stack will be deleted.\n\n- DO_NOTHING: The stack will not rollback or delete, this is the same as disabling rollback.\n\nDefault behaviour is ROLLBACK.\n\n\n\nThis option is mutually exclusive with --disable-rollback/--no-disable-rollback. You can provide\n--on-failure or --disable-rollback/--no-disable-rollback but not both at the same time.\n* max_wait_duration:\nMaximum duration in minutes to wait for the deployment to complete.\n* stack_name:\nName of the AWS CloudFormation stack.\n* s3_bucket:\nAWS S3 bucket where artifacts referenced in the template are uploaded.\n* image_repository:\nAWS ECR repository URI where artifacts referenced in the template are uploaded.\n* image_repositories:\nMapping of Function Logical ID to AWS ECR Repository URI.\n\nExample: Function_Logical_ID=ECR_Repo_Uri\nThis option can be specified multiple times.\n* force_upload:\nIndicates whether to override existing files in the S3 bucket. Specify this flag to upload artifacts even if they match existing artifacts in the S3 bucket.\n* s3_prefix:\nPrefix name that is added to the artifact's name when it is uploaded to the AWS S3 bucket.\n* kms_key_id:\nThe ID of an AWS KMS key that is used to encrypt artifacts that are at rest in the AWS S3 bucket.\n* role_arn:\nARN of an IAM role that AWS Cloudformation assumes when executing a deployment change set.\n* use_json:\nIndicates whether to use JSON as the format for the output AWS CloudFormation template. YAML is used by default.\n* resolve_s3:\nAutomatically resolve AWS S3 bucket for non-guided deployments. Enabling this option will also create a managed default AWS S3 bucket for you. If one does not provide a --s3-bucket value, the managed bucket will be used. Do not use --guided with this option.\n* resolve_image_repos:\nAutomatically create and delete ECR repositories for image-based functions in non-guided deployments. A companion stack containing ECR repos for each function will be deployed along with the template stack. Automatically created image repositories will be deleted if the corresponding functions are removed.\n* metadata:\nMap of metadata to attach to ALL the artifacts that are referenced in the template.\n* notification_arns:\nARNs of SNS topics that AWS Cloudformation associates with the stack.\n* tags:\nList of tags to associate with the stack.\n* parameter_overrides:\nString that contains AWS CloudFormation parameter overrides encoded as key=value pairs.\n* signing_profiles:\nA string that contains Code Sign configuration parameters as FunctionOrLayerNameToSign=SigningProfileName:SigningProfileOwner Since signing profile owner is optional, it could also be written as FunctionOrLayerNameToSign=SigningProfileName\n* no_progressbar:\nDoes not showcase a progress bar when uploading artifacts to S3 and pushing docker images to ECR\n* capabilities:\nList of capabilities that one must specify before AWS Cloudformation can create certain stacks.\n\nAccepted Values: CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_RESOURCE_POLICY, CAPABILITY_AUTO_EXPAND.\n\nLearn more at: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html\n* profile:\nSelect a specific profile from your credential file to get AWS credentials.\n* region:\nSet the AWS Region of the service. (e.g. us-east-1)\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
+              "description": "Available parameters for the deploy command:\n* guided:\nSpecify this flag to allow SAM CLI to guide you through the deployment using guided prompts.\n* template_file:\nAWS SAM template which references built artifacts for resources in the template. (if applicable)\n* no_execute_changeset:\nIndicates whether to execute the change set. Specify this flag to view stack changes before executing the change set.\n* fail_on_empty_changeset:\nSpecify whether AWS SAM CLI should return a non-zero exit code if there are no changes to be made to the stack. Defaults to a non-zero exit code.\n* confirm_changeset:\nPrompt to confirm if the computed changeset is to be deployed by SAM CLI.\n* include_nested_stacks:\nDisplay changes for nested stacks in the changeset. For large nested stack hierarchies, use --no-include-nested-stacks to reduce output verbosity. Defaults to displaying nested stack changes.\n* disable_rollback:\nPreserves the state of previously provisioned resources when an operation fails.\n* on_failure:\nProvide an action to determine what will happen when a stack fails to create. Three actions are available:\n\n- ROLLBACK: This will rollback a stack to a previous known good state.\n\n- DELETE: The stack will rollback to a previous state if one exists, otherwise the stack will be deleted.\n\n- DO_NOTHING: The stack will not rollback or delete, this is the same as disabling rollback.\n\nDefault behaviour is ROLLBACK.\n\n\n\nThis option is mutually exclusive with --disable-rollback/--no-disable-rollback. You can provide\n--on-failure or --disable-rollback/--no-disable-rollback but not both at the same time.\n* max_wait_duration:\nMaximum duration in minutes to wait for the deployment to complete.\n* stack_name:\nName of the AWS CloudFormation stack.\n* s3_bucket:\nAWS S3 bucket where artifacts referenced in the template are uploaded.\n* image_repository:\nAWS ECR repository URI where artifacts referenced in the template are uploaded.\n* image_repositories:\nMapping of Function Logical ID to AWS ECR Repository URI.\n\nExample: Function_Logical_ID=ECR_Repo_Uri\nThis option can be specified multiple times.\n* force_upload:\nIndicates whether to override existing files in the S3 bucket. Specify this flag to upload artifacts even if they match existing artifacts in the S3 bucket.\n* s3_prefix:\nPrefix name that is added to the artifact's name when it is uploaded to the AWS S3 bucket.\n* kms_key_id:\nThe ID of an AWS KMS key that is used to encrypt artifacts that are at rest in the AWS S3 bucket.\n* role_arn:\nARN of an IAM role that AWS Cloudformation assumes when executing a deployment change set.\n* use_json:\nIndicates whether to use JSON as the format for the output AWS CloudFormation template. YAML is used by default.\n* resolve_s3:\nAutomatically resolve AWS S3 bucket for non-guided deployments. Enabling this option will also create a managed default AWS S3 bucket for you. If one does not provide a --s3-bucket value, the managed bucket will be used. Do not use --guided with this option.\n* resolve_image_repos:\nAutomatically create and delete ECR repositories for image-based functions in non-guided deployments. A companion stack containing ECR repos for each function will be deployed along with the template stack. Automatically created image repositories will be deleted if the corresponding functions are removed.\n* metadata:\nMap of metadata to attach to ALL the artifacts that are referenced in the template.\n* notification_arns:\nARNs of SNS topics that AWS Cloudformation associates with the stack.\n* tags:\nList of tags to associate with the stack.\n* parameter_overrides:\nString that contains AWS CloudFormation parameter overrides encoded as key=value pairs.\n* signing_profiles:\nA string that contains Code Sign configuration parameters as FunctionOrLayerNameToSign=SigningProfileName:SigningProfileOwner Since signing profile owner is optional, it could also be written as FunctionOrLayerNameToSign=SigningProfileName\n* no_progressbar:\nDoes not showcase a progress bar when uploading artifacts to S3 and pushing docker images to ECR\n* capabilities:\nList of capabilities that one must specify before AWS Cloudformation can create certain stacks.\n\nAccepted Values: CAPABILITY_IAM, CAPABILITY_NAMED_IAM, CAPABILITY_RESOURCE_POLICY, CAPABILITY_AUTO_EXPAND.\n\nLearn more at: https://docs.aws.amazon.com/serverlessrepo/latest/devguide/acknowledging-application-capabilities.html\n* profile:\nSelect a specific profile from your credential file to get AWS credentials.\n* region:\nSet the AWS Region of the service. (e.g. us-east-1)\n* beta_features:\nEnable/Disable beta features.\n* debug:\nTurn on debug logging to print debug message generated by AWS SAM CLI and display timestamps.\n* save_params:\nSave the parameters provided via the command line to the configuration file.",
               "type": "object",
               "properties": {
                 "guided": {
@@ -1263,6 +1263,12 @@
                   "type": "boolean",
                   "description": "Prompt to confirm if the computed changeset is to be deployed by SAM CLI."
                 },
+                "include_nested_stacks": {
+                  "title": "include_nested_stacks",
+                  "type": "boolean",
+                  "description": "Display changes for nested stacks in the changeset. For large nested stack hierarchies, use --no-include-nested-stacks to reduce output verbosity. Defaults to displaying nested stack changes.",
+                  "default": true
+                },
                 "disable_rollback": {
                   "title": "disable_rollback",
                   "type": "boolean",

tests/integration/deploy/test_nested_stack_changeset.py

@@ -7,7 +7,7 @@
 from unittest import skipIf
 
 from tests.integration.deploy.deploy_integ_base import DeployIntegBase
-from tests.testing_utils import RUNNING_ON_CI, RUNNING_TEST_FOR_MASTER_ON_CI, RUN_BY_CANARY
+from tests.testing_utils import RUN_BY_CANARY, RUNNING_ON_CI, RUNNING_TEST_FOR_MASTER_ON_CI
 
 
 @skipIf(
@@ -58,9 +58,10 @@ def test_deploy_with_nested_stack_shows_nested_changes(self):
         # Should contain parent stack changes
         self.assertIn("CloudFormation stack changeset", stdout)
 
-        # For a stack with nested resources, verify the changes are shown
-        # The actual nested stack display depends on the template structure
-        # At minimum, verify no errors occurred and changeset was created
+        # Verify nested stack header is displayed (validates nested stack feature)
+        self.assertIn("[Nested Stack:", stdout)
+
+        # Verify no errors occurred
         self.assertNotIn("Error", stdout)
         self.assertNotIn("Failed", stdout)
 
@@ -93,6 +94,9 @@ def test_deploy_nested_stack_with_parameters(self):
         # Verify changeset was created
         self.assertIn("CloudFormation stack changeset", stdout)
 
+        # Verify nested stack header is displayed (validates nested stack feature)
+        self.assertIn("[Nested Stack:", stdout)
+
         # Verify no errors
         self.assertNotIn("Error", stdout)
         self.assertNotIn("Failed", stdout)