Add --payload option to zappa invoke command (#1412) (#1432)

Allow passing a JSON payload to invoked functions via
`zappa invoke <env> <func> --payload '{"key": "value"}'`.
The payload keys are merged into the Lambda event dict alongside
the command key, so the invoked function receives them in `event`.

Validates that the payload is valid JSON and a dict, raising a
clear error otherwise.

Co-authored-by: shane <shane.cousins@kiconiaworks.com>

Author: monkut

tests/test_core.py

@@ -2429,6 +2429,95 @@ def test_cli_colorize_invoke_command_bad_string(self):
         colorized_string = zappa_cli.colorize_invoke_command(plain_string)
         self.assertEqual(final_string, colorized_string)
 
+    @mock.patch("zappa.cli.ZappaCLI.format_lambda_response")
+    @mock.patch("zappa.core.Zappa.invoke_lambda_function")
+    def test_invoke_with_payload(self, mock_invoke, mock_format):
+        """Test that --payload merges JSON into the invoke event."""
+        mock_invoke.return_value = {"StatusCode": 200}
+        mock_format.return_value = "ok"
+
+        zappa_cli = ZappaCLI()
+        zappa_cli.api_stage = "dev"
+        zappa_cli.lambda_name = "test-func"
+        zappa_cli.zappa = mock.MagicMock()
+        zappa_cli.zappa.invoke_lambda_function = mock_invoke
+
+        zappa_cli.invoke(
+            "my_app.my_function",
+            payload='{"key1": "value1", "key2": "value2"}',
+        )
+
+        call_args = mock_invoke.call_args
+        sent_payload = json.loads(call_args[0][1])
+        self.assertEqual(sent_payload["command"], "my_app.my_function")
+        self.assertEqual(sent_payload["key1"], "value1")
+        self.assertEqual(sent_payload["key2"], "value2")
+
+    @mock.patch("zappa.cli.ZappaCLI.format_lambda_response")
+    @mock.patch("zappa.core.Zappa.invoke_lambda_function")
+    def test_invoke_with_payload_raw_python(self, mock_invoke, mock_format):
+        """Test that --payload works with --raw."""
+        mock_invoke.return_value = {"StatusCode": 200}
+        mock_format.return_value = "ok"
+
+        zappa_cli = ZappaCLI()
+        zappa_cli.api_stage = "dev"
+        zappa_cli.lambda_name = "test-func"
+        zappa_cli.zappa = mock.MagicMock()
+        zappa_cli.zappa.invoke_lambda_function = mock_invoke
+
+        zappa_cli.invoke(
+            "print('hello')",
+            raw_python=True,
+            payload='{"extra": "data"}',
+        )
+
+        call_args = mock_invoke.call_args
+        sent_payload = json.loads(call_args[0][1])
+        self.assertEqual(sent_payload["raw_command"], "print('hello')")
+        self.assertEqual(sent_payload["extra"], "data")
+
+    def test_invoke_with_invalid_payload_json(self):
+        """Test that invalid JSON in --payload raises ClickException."""
+        zappa_cli = ZappaCLI()
+        zappa_cli.api_stage = "dev"
+        zappa_cli.lambda_name = "test-func"
+        zappa_cli.zappa = mock.MagicMock()
+
+        with self.assertRaises(ClickException) as cm:
+            zappa_cli.invoke("my_app.my_function", payload="not-valid-json")
+        self.assertIn("--payload must be valid JSON", str(cm.exception))
+
+    def test_invoke_with_non_dict_payload(self):
+        """Test that a non-dict JSON payload raises ClickException."""
+        zappa_cli = ZappaCLI()
+        zappa_cli.api_stage = "dev"
+        zappa_cli.lambda_name = "test-func"
+        zappa_cli.zappa = mock.MagicMock()
+
+        with self.assertRaises(ClickException) as cm:
+            zappa_cli.invoke("my_app.my_function", payload='["a", "b"]')
+        self.assertIn("--payload must be a JSON object", str(cm.exception))
+
+    @mock.patch("zappa.cli.ZappaCLI.format_lambda_response")
+    @mock.patch("zappa.core.Zappa.invoke_lambda_function")
+    def test_invoke_without_payload(self, mock_invoke, mock_format):
+        """Test that invoke without --payload works as before."""
+        mock_invoke.return_value = {"StatusCode": 200}
+        mock_format.return_value = "ok"
+
+        zappa_cli = ZappaCLI()
+        zappa_cli.api_stage = "dev"
+        zappa_cli.lambda_name = "test-func"
+        zappa_cli.zappa = mock.MagicMock()
+        zappa_cli.zappa.invoke_lambda_function = mock_invoke
+
+        zappa_cli.invoke("my_app.my_function")
+
+        call_args = mock_invoke.call_args
+        sent_payload = json.loads(call_args[0][1])
+        self.assertEqual(sent_payload, {"command": "my_app.my_function"})
+
     @mock.patch("zappa.cli.ZappaCLI.colorize_invoke_command")
     @mock.patch("zappa.cli.ZappaCLI.format_invoke_command")
     def test_cli_format_lambda_response(self, mock_format, mock_colorize):

zappa/cli.py

@@ -325,6 +325,10 @@ def handle(self, argv=None):
             "--qualifier",
             help="The qualifier (version or alias) of the lambda version to invoke. $LATEST if omitted.",
         )
+        invoke_parser.add_argument(
+            "--payload",
+            help="A JSON string of key/value pairs to include in the event passed to the function.",
+        )
         invoke_parser.add_argument("command_rest")
 
         ##
@@ -658,6 +662,7 @@ def dispatch_command(self, command, stage):
                 no_color=self.vargs["no_color"],
                 client_context=self.vargs["client_context"],
                 qualifier=self.vargs["qualifier"],
+                payload=self.vargs.get("payload"),
             )
         elif command == "manage":  # pragma: no cover
             if not self.vargs.get("command_rest"):
@@ -1543,7 +1548,9 @@ def unschedule(self):
             removed_arns = self.zappa.remove_async_sns_topic(self.lambda_name)
             click.echo("SNS Topic removed: %s" % ", ".join(removed_arns))
 
-    def invoke(self, function_name, raw_python=False, command=None, no_color=False, client_context=None, qualifier=None):
+    def invoke(
+        self, function_name, raw_python=False, command=None, no_color=False, client_context=None, qualifier=None, payload=None
+    ):
         """
         Invoke a remote function.
         """
@@ -1557,6 +1564,18 @@ def invoke(self, function_name, raw_python=False, command=None, no_color=False,
             command = {"raw_command": function_name}
         else:
             command = {key: function_name}
+
+        if payload:
+            import json as json_module
+
+            try:
+                payload_dict = json_module.loads(payload)
+            except (ValueError, TypeError) as e:
+                raise ClickException("--payload must be valid JSON: {}".format(e))
+            if not isinstance(payload_dict, dict):
+                raise ClickException("--payload must be a JSON object (dict), not {}.".format(type(payload_dict).__name__))
+            command.update(payload_dict)
+
         client_context = base64.b64encode(client_context.encode("utf-8")).decode("utf-8") if client_context else None
 
         # Can't use hjson