Add max responses field to study

exp/tests/test_study_views.py

@@ -31,7 +31,8 @@
     StudyDetailView,
     StudyPreviewDetailView,
 )
-from studies.models import Lab, Study, StudyType
+from studies.helpers import ResponseEligibility
+from studies.models import Lab, Response, Study, StudyType
 from studies.permissions import LabPermission, StudyPermission
 
 
@@ -672,6 +673,171 @@ def test_update_trigger_object_no_attr(
         mock_request.POST.keys.assert_not_called()
 
 
+@override_settings(CELERY_TASK_ALWAYS_EAGER=True)
+@override_settings(CELERY_TASK_EAGER_PROPAGATES=True)
+@patch("studies.helpers.send_mail")
+class ActivateStudyMaxResponsesTestCase(TestCase):
+    """Integration tests for the check_if_at_max_responses workflow guard.
+
+    When a researcher tries to activate a study (from approved or paused state),
+    the transition should be blocked if the study has already reached its
+    max_responses limit.
+    """
+
+    def setUp(self):
+        self.client = Force2FAClient()
+        self.user = G(User, is_active=True, is_researcher=True)
+        self.lab = G(Lab, name="Activation Test Lab", approved_to_test=True)
+        self.lab.researchers.add(self.user)
+
+        self.study = G(
+            Study,
+            image=SimpleUploadedFile(
+                name="small.gif",
+                content=(
+                    b"\x47\x49\x46\x38\x39\x61\x01\x00\x01\x00\x00\x00\x00\x21\xf9\x04"
+                    b"\x01\x0a\x00\x01\x00\x2c\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02"
+                    b"\x02\x4c\x01\x00\x3b"
+                ),
+                content_type="image/gif",
+            ),
+            study_type=StudyType.get_external(),
+            creator=self.user,
+            lab=self.lab,
+            name="Activation Test Study",
+            built=True,
+        )
+        self.study.admin_group.user_set.add(self.user)
+        assign_perm(
+            StudyPermission.CHANGE_STUDY_STATUS.prefixed_codename,
+            self.user,
+            self.study,
+        )
+        self.client.force_login(self.user)
+
+        self.change_status_url = reverse(
+            "exp:change-study-status", kwargs={"pk": self.study.pk}
+        )
+
+    def _create_eligible_responses(self, count):
+        """Create eligible, non-preview responses for the study."""
+        participant = G(User, is_active=True)
+        child = G(
+            Child,
+            user=participant,
+            given_name="Test child",
+            birthday=datetime.date.today() - datetime.timedelta(days=30),
+        )
+        for _ in range(count):
+            r = Response.objects.create(
+                study=self.study,
+                child=child,
+                study_type=self.study.study_type,
+                demographic_snapshot=participant.latest_demographics,
+                completed=True,
+                is_preview=False,
+            )
+            Response.objects.filter(pk=r.pk).update(
+                eligibility=[ResponseEligibility.ELIGIBLE]
+            )
+
+    def _get_error_messages(self, response):
+        """Extract error-level messages from a followed response."""
+        from django.contrib.messages import constants
+
+        return [m for m in response.context["messages"] if m.level == constants.ERROR]
+
+    def _get_success_messages(self, response):
+        """Extract success-level messages from a followed response."""
+        from django.contrib.messages import constants
+
+        return [m for m in response.context["messages"] if m.level == constants.SUCCESS]
+
+    def test_activate_blocked_from_approved_when_at_max_responses(self, mock_send_mail):
+        """Activating an approved study fails when max_responses has been reached."""
+        self.study.state = "approved"
+        self.study.max_responses = 3
+        self.study.save()
+        self._create_eligible_responses(3)
+
+        response = self.client.post(
+            self.change_status_url, {"trigger": "activate"}, follow=True
+        )
+
+        self.study.refresh_from_db()
+        self.assertNotEqual(self.study.state, "active")
+        errors = self._get_error_messages(response)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("TRANSITION ERROR", str(errors[0]))
+        self.assertIn("maximum number of responses", str(errors[0]))
+
+    def test_activate_blocked_from_paused_when_at_max_responses(self, mock_send_mail):
+        """Reactivating a paused study fails when max_responses has been reached."""
+        self.study.state = "paused"
+        self.study.max_responses = 2
+        self.study.save()
+        self._create_eligible_responses(3)
+
+        response = self.client.post(
+            self.change_status_url, {"trigger": "activate"}, follow=True
+        )
+
+        self.study.refresh_from_db()
+        self.assertNotEqual(self.study.state, "active")
+        errors = self._get_error_messages(response)
+        self.assertEqual(len(errors), 1)
+        self.assertIn("TRANSITION ERROR", str(errors[0]))
+        self.assertIn("maximum number of responses", str(errors[0]))
+
+    def test_activate_succeeds_when_below_max_responses(self, mock_send_mail):
+        """Activating an approved study succeeds when below the max_responses limit."""
+        self.study.state = "approved"
+        self.study.max_responses = 10
+        self.study.save()
+        self._create_eligible_responses(3)
+
+        response = self.client.post(
+            self.change_status_url, {"trigger": "activate"}, follow=True
+        )
+
+        self.study.refresh_from_db()
+        self.assertEqual(self.study.state, "active")
+        errors = self._get_error_messages(response)
+        self.assertEqual(len(errors), 0)
+
+    def test_activate_succeeds_when_no_max_responses_set(self, mock_send_mail):
+        """Activating an approved study succeeds when max_responses is not set."""
+        self.study.state = "approved"
+        self.study.max_responses = None
+        self.study.save()
+        self._create_eligible_responses(5)
+
+        response = self.client.post(
+            self.change_status_url, {"trigger": "activate"}, follow=True
+        )
+
+        self.study.refresh_from_db()
+        self.assertEqual(self.study.state, "active")
+        errors = self._get_error_messages(response)
+        self.assertEqual(len(errors), 0)
+
+    def test_activate_succeeds_when_exactly_at_limit_minus_one(self, mock_send_mail):
+        """Activating succeeds when response count is one below max_responses."""
+        self.study.state = "approved"
+        self.study.max_responses = 4
+        self.study.save()
+        self._create_eligible_responses(3)
+
+        response = self.client.post(
+            self.change_status_url, {"trigger": "activate"}, follow=True
+        )
+
+        self.study.refresh_from_db()
+        self.assertEqual(self.study.state, "active")
+        errors = self._get_error_messages(response)
+        self.assertEqual(len(errors), 0)
+
+
 class ManageResearcherPermissionsViewTestCase(TestCase):
     def test_model(self) -> None:
         manage_researcher_permissions_view = ManageResearcherPermissionsView()
@@ -1334,3 +1500,196 @@ def test_must_not_have_participated(self):
 # TODO: StudyPreviewProxyView
 # - add checks analogous to preview detail view
 # - check for correct redirect
+
+
+@override_settings(CELERY_TASK_ALWAYS_EAGER=True)
+@override_settings(CELERY_TASK_EAGER_PROPAGATES=True)
+@patch("studies.helpers.send_mail")
+class StudyUpdateMaxResponsesTestCase(TestCase):
+    """Tests for banner messages when max_responses is edited via StudyUpdateView."""
+
+    def setUp(self):
+        self.client = Force2FAClient()
+        self.user = G(User, is_active=True, is_researcher=True)
+        self.lab = G(Lab, name="Max Resp Lab", approved_to_test=True)
+        self.lab.researchers.add(self.user)
+
+        self.study = G(
+            Study,
+            image=SimpleUploadedFile(
+                name="small.gif",
+                content=(
+                    b"\x47\x49\x46\x38\x39\x61\x01\x00\x01\x00\x00\x00\x00\x21\xf9\x04"
+                    b"\x01\x0a\x00\x01\x00\x2c\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02"
+                    b"\x02\x4c\x01\x00\x3b"
+                ),
+                content_type="image/gif",
+            ),
+            study_type=StudyType.get_ember_frame_player(),
+            creator=self.user,
+            lab=self.lab,
+            name="Max Resp Study",
+            short_description="test",
+            preview_summary="test",
+            purpose="test",
+            criteria="test",
+            duration="test",
+            contact_info="test",
+            exit_url="https://mit.edu",
+        )
+        self.study.admin_group.user_set.add(self.user)
+        assign_perm(
+            StudyPermission.WRITE_STUDY_DETAILS.prefixed_codename,
+            self.user,
+            self.study,
+        )
+        self.client.force_login(self.user)
+
+    def _form_data(self, include_image=True, **overrides):
+        """Build minimal valid form data for the StudyEditForm.
+
+        Set include_image=False to avoid triggering the pre_save signal that
+        rejects approved/active studies when monitored fields change.
+        """
+        data = {
+            "name": self.study.name,
+            "lab": self.study.lab_id,
+            "study_type": self.study.study_type_id,
+            "min_age_years": 0,
+            "min_age_months": 0,
+            "min_age_days": 0,
+            "max_age_years": 1,
+            "max_age_months": 0,
+            "max_age_days": 0,
+            "priority": 1,
+            "preview_summary": self.study.preview_summary,
+            "short_description": self.study.short_description,
+            "purpose": self.study.purpose,
+            "compensation_description": self.study.compensation_description,
+            "exit_url": self.study.exit_url,
+            "criteria": self.study.criteria,
+            "duration": self.study.duration,
+            "contact_info": self.study.contact_info,
+        }
+        if include_image:
+            data["image"] = SimpleUploadedFile(
+                name="test_image.jpg",
+                content=open("exp/tests/static/study_image.png", "rb").read(),
+                content_type="image/jpeg",
+            )
+        data.update(overrides)
+        return data
+
+    def _create_eligible_responses(self, count):
+        """Create eligible, completed, non-preview responses for the study."""
+        participant = G(User, is_active=True)
+        child = G(
+            Child,
+            user=participant,
+            given_name="Test child",
+            birthday=datetime.date.today() - datetime.timedelta(days=30),
+        )
+        for _ in range(count):
+            r = Response.objects.create(
+                study=self.study,
+                child=child,
+                study_type=self.study.study_type,
+                demographic_snapshot=participant.latest_demographics,
+                completed_consent_frame=True,
+                completed=True,
+                is_preview=False,
+            )
+            Response.objects.filter(pk=r.pk).update(
+                eligibility=[ResponseEligibility.ELIGIBLE]
+            )
+
+    def _get_warning_messages(self, response):
+        """Extract warning-level messages from a followed response."""
+        from django.contrib.messages import constants
+
+        return [m for m in response.context["messages"] if m.level == constants.WARNING]
+
+    def test_banner_when_max_responses_reached_non_active_study(self, mock_send_mail):
+        """Warning banner shown when max_responses is set at/below response count on non-active study."""
+        self.assertEqual(self.study.state, "created")
+        self._create_eligible_responses(3)
+        data = self._form_data(set_response_limit=True, max_responses=3)
+        response = self.client.post(
+            reverse("exp:study-edit", kwargs={"pk": self.study.id}),
+            data,
+            follow=True,
+        )
+        warnings = self._get_warning_messages(response)
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("reached the response limit", str(warnings[0]))
+
+        # Study should NOT be paused (was not active)
+        self.study.refresh_from_db()
+        self.assertNotEqual(self.study.state, "paused")
+
+    def test_study_paused_when_max_responses_reached_active_study(self, mock_send_mail):
+        """Active study is paused and warning shown when max_responses is set at response count."""
+        self.assertEqual(self.study.state, "created")
+        self.study.state = "active"
+        self.study.save()
+        self._create_eligible_responses(3)
+        # include_image=False to avoid triggering the pre_save signal that
+        # rejects active studies when monitored fields (like image) change.
+        data = self._form_data(
+            include_image=False, set_response_limit=True, max_responses=3
+        )
+        response = self.client.post(
+            reverse("exp:study-edit", kwargs={"pk": self.study.id}),
+            data,
+            follow=True,
+        )
+        warnings = self._get_warning_messages(response)
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("automatically paused", str(warnings[0]))
+
+        self.study.refresh_from_db()
+        self.assertEqual(self.study.state, "paused")
+
+    def test_no_banner_when_max_responses_not_reached(self, mock_send_mail):
+        """No warning when max_responses is set above the current response count."""
+        self._create_eligible_responses(2)
+        data = self._form_data(set_response_limit=True, max_responses=10)
+        response = self.client.post(
+            reverse("exp:study-edit", kwargs={"pk": self.study.id}),
+            data,
+            follow=True,
+        )
+        warnings = self._get_warning_messages(response)
+        self.assertEqual(len(warnings), 0)
+        self.assertNotEqual(self.study.state, "paused")
+
+    def test_no_banner_when_max_responses_unchanged(self, mock_send_mail):
+        """No warning when max_responses is submitted but hasn't changed."""
+        self.study.max_responses = 5
+        self.study.save()
+        self._create_eligible_responses(5)
+        data = self._form_data(set_response_limit=True, max_responses=5)
+        response = self.client.post(
+            reverse("exp:study-edit", kwargs={"pk": self.study.id}),
+            data,
+            follow=True,
+        )
+        warnings = self._get_warning_messages(response)
+        self.assertEqual(len(warnings), 0)
+
+    def test_banner_when_max_responses_lowered_below_count(self, mock_send_mail):
+        """Warning shown when max_responses is lowered below existing response count."""
+        self.assertEqual(self.study.state, "created")
+        self.study.max_responses = 10
+        self.study.save()
+        self._create_eligible_responses(5)
+        data = self._form_data(set_response_limit=True, max_responses=3)
+        response = self.client.post(
+            reverse("exp:study-edit", kwargs={"pk": self.study.id}),
+            data,
+            follow=True,
+        )
+        warnings = self._get_warning_messages(response)
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("reached the response limit", str(warnings[0]))
+        self.assertEqual(self.study.state, "created")

exp/views/study.py

@@ -226,9 +226,18 @@ def form_valid(self, form: StudyEditForm):
         )
         study.must_have_participated.set(form.cleaned_data["must_have_participated"])
 
+        changed_fields = form.changed_data
+
         messages.success(self.request, f"{study.name} study details saved.")
 
-        return super().form_valid(form)
+        # Save form first so the new max_responses value is persisted before
+        # check_and_pause_if_at_max_responses (which calls refresh_from_db).
+        response = super().form_valid(form)
+        # Now check to see if the study has reached max responses with the new value
+        if "max_responses" in changed_fields:
+            study.check_and_pause_if_at_max_responses(request=self.request)
+
+        return response
 
     def form_invalid(self, form: StudyEditForm):
         messages.error(self.request, form.errors)