Feature: add is_batch_send to anymail_test_params

Make it easier for tests to check whether messages
would fall under Anymail's batch-send logic.

See #249.

CHANGELOG.rst

@@ -46,6 +46,13 @@ Fixes
   (Thanks to `@coupa-anya`_ for reporting the issue.)
 
 
+Other
+~~~~~
+
+* In Anymail's test EmailBackend, add `is_batch_send` boolean to `anymail_test_params`
+  to help tests check whether a sent message would fall under Anymail's batch-send logic.
+
+
 v8.4
 ----
 

anymail/backends/test.py

@@ -39,7 +39,7 @@ class EmailBackend(AnymailBaseBackend):
 
     def post_to_esp(self, payload, message):
         # Keep track of the sent messages and params (for test cases)
-        message.anymail_test_params = payload.params
+        message.anymail_test_params = payload.get_params()
         mail.outbox.append(message)
         try:
             # Tests can supply their own message.test_response:
@@ -73,6 +73,12 @@ class TestPayload(BasePayload):
         self.params = {}
         self.recipient_emails = []
 
+    def get_params(self):
+        # Test backend callers can check message.anymail_test_params['is_batch_send']
+        # to verify whether Anymail thought the message should use batch send logic.
+        self.params['is_batch_send'] = self.is_batch()
+        return self.params
+
     def set_from_email(self, email):
         self.params['from'] = email
 

docs/tips/test_backend.rst

@@ -9,7 +9,7 @@ by loading a dummy EmailBackend that accumulates messages
 in memory rather than sending them. That works just fine with Anymail.
 
 Anymail also includes its own "test" EmailBackend. This is intended primarily for
-Anymail's own internal tests, but you may find it useful for some of your test cases, too:
+Anymail's internal testing, but you may find it useful for some of your test cases, too:
 
 * Like Django's locmem EmailBackend, Anymail's test EmailBackend collects sent messages
   in :data:`django.core.mail.outbox`.
@@ -50,3 +50,12 @@ Here's an example:
 
             # Or verify the Anymail params, including any merged settings defaults:
             self.assertTrue(mail.outbox[0].anymail_test_params["track_clicks"])
+
+Note that :data:`django.core.mail.outbox` is an "outbox," not an attempt to represent end users'
+*inboxes*. When using Django's default locmem EmailBackend, each outbox item represents a single
+call to an SMTP server. With Anymail's test EmailBackend, each outbox item represents a single
+call to an ESP's send API. (Anymail does not try to simulate how an ESP might further process
+the message for that API call: Anymail can't render :ref:`esp-stored-templates`, and it keeps a
+:ref:`batch send<batch-send>` message as a single outbox item, representing the single ESP API call
+that will send multiple messages. You can check ``outbox[n].anymail_test_params['is_batch_send']``
+to see if a message would fall under Anymail's batch send logic.)

tests/test_general_backend.py

@@ -508,28 +508,28 @@ class AlternativePartsTests(TestBackendTestCase):
 class BatchSendDetectionTestCase(TestBackendTestCase):
     """Tests shared code to consistently determine whether to use batch send"""
 
-    def setUp(self):
-        super().setUp()
-        self.backend = TestBackend()
-
     def test_default_is_not_batch(self):
-        payload = self.backend.build_message_payload(self.message, {})
+        self.message.send()
-        self.assertFalse(payload.is_batch())
+        params = self.get_send_params()
+        self.assertFalse(params['is_batch_send'])
 
     def test_merge_data_implies_batch(self):
         self.message.merge_data = {}  # *anything* (even empty dict) implies batch
-        payload = self.backend.build_message_payload(self.message, {})
+        self.message.send()
-        self.assertTrue(payload.is_batch())
+        params = self.get_send_params()
+        self.assertTrue(params['is_batch_send'])
 
     def test_merge_metadata_implies_batch(self):
         self.message.merge_metadata = {}  # *anything* (even empty dict) implies batch
-        payload = self.backend.build_message_payload(self.message, {})
+        self.message.send()
-        self.assertTrue(payload.is_batch())
+        params = self.get_send_params()
+        self.assertTrue(params['is_batch_send'])
 
     def test_merge_global_data_does_not_imply_batch(self):
         self.message.merge_global_data = {}
-        payload = self.backend.build_message_payload(self.message, {})
+        self.message.send()
-        self.assertFalse(payload.is_batch())
+        params = self.get_send_params()
+        self.assertFalse(params['is_batch_send'])
 
     def test_cannot_call_is_batch_during_init(self):
         # It's tempting to try to warn about unsupported batch features in setters,