Documents maintenance banner setting and toggle and adds necessary unit tests

lms/envs/common.py

@@ -1049,6 +1049,11 @@ LOG_DIR = '/edx/var/log/edx'
 
 DATA_DIR = '/edx/var/edxapp/data'
 
+# .. setting_name: MAINTENANCE_BANNER_TEXT
+# .. setting_default: 'Sample banner message'
+# .. setting_description: Specifies the text that is rendered on the maintenance banner.
+# .. setting_warning: Depends on the `open_edx_util.display_maintenance_warning` waffle switch.
+#   The banner is only rendered when the switch is activated.
 MAINTENANCE_BANNER_TEXT = 'Sample banner message'
 
 GIT_REPO_DIR = '/edx/var/edxapp/course_repos'

openedx/core/djangoapps/util/maintenance_banner.py

@@ -8,7 +8,7 @@ from functools import wraps
 from django.conf import settings
 
 from openedx.core.djangoapps.util.user_messages import PageLevelMessages
-from openedx.core.djangoapps.util.waffle import DISPLAY_MAINTENANCE_WARNING, waffle
+from openedx.core.djangoapps.util.waffle import DISPLAY_MAINTENANCE_WARNING
 
 
 def add_maintenance_banner(func):
@@ -34,7 +34,7 @@ def add_maintenance_banner(func):
     """
     @wraps(func)
     def _decorated(request, *args, **kwargs):  # pylint: disable=missing-docstring
-        if waffle().is_enabled(DISPLAY_MAINTENANCE_WARNING):
+        if DISPLAY_MAINTENANCE_WARNING.is_enabled():
             if hasattr(settings, 'MAINTENANCE_BANNER_TEXT') and settings.MAINTENANCE_BANNER_TEXT:
                 # The waffle switch is enabled and the banner text is defined
                 # and non-empty.  We can now register the message:

openedx/core/djangoapps/util/tests/test_maintenance_banner.py

@@ -0,0 +1,81 @@
+"""
+Tests for the view decorator which adds the maintenace banner.
+"""
+
+
+from unittest import mock
+
+import ddt
+from django.test import TestCase, override_settings
+from edx_toggles.toggles.testutils import override_waffle_switch
+
+from openedx.core.djangoapps.util.maintenance_banner import add_maintenance_banner as _add_maintenance_banner
+from openedx.core.djangoapps.util.waffle import DISPLAY_MAINTENANCE_WARNING
+
+
+@ddt.ddt
+class TestMaintenanceBannerViewDecorator(TestCase):
+    """
+    Tests for view decorator which adds the maintenance banner.
+    """
+
+    def add_maintenance_banner(self):
+        """
+        Mock `add_maintenance_banner` that should be used for testing
+
+        Returns tuple:
+        (
+            boolean to indicate if banner was added,
+            string containing maintenance warning text,
+        )
+        """
+
+        @_add_maintenance_banner
+        def func(request):
+            return request
+
+        register_warning_message_path = (
+            'openedx.core.djangoapps.util.maintenance_banner'
+            '.PageLevelMessages.register_warning_message'
+        )
+        with mock.patch(register_warning_message_path) as mock_register_warning_message:
+            func(request=mock.Mock())
+
+            displayed_banner = mock_register_warning_message.called
+            banner_text = None
+
+            if displayed_banner:
+                banner_text = mock_register_warning_message.call_args.args[1]
+
+            return (displayed_banner, banner_text)
+
+    @ddt.data(
+        True,
+        False,
+    )
+    def test_display_maintenance_warning_switch(self, display_warning):
+        """
+        Tests the `DISPLAY_MAINTENANCE_WARNING` switch is working as expected.
+
+        Checks if the decorated request from `get_decorated_request` has a warning or not.
+        """
+        with override_waffle_switch(DISPLAY_MAINTENANCE_WARNING, active=display_warning):
+            banner_added, _ = self.add_maintenance_banner()
+
+            self.assertEqual(display_warning, banner_added)
+
+    @ddt.data(
+        "If there's somethin' strange in your neighborhood, who ya gonna call?!"
+    )
+    @override_waffle_switch(DISPLAY_MAINTENANCE_WARNING, active=True)
+    def test_maintenance_warning_text(self, warning_message):
+        """
+        Tests the `MAINTENANCE_BANNER_TEXT` is being set, as expected.
+
+        Checks if the decorated request from `get_decorated_request` returns the specified warning message.
+        """
+        with override_settings(MAINTENANCE_BANNER_TEXT=warning_message):
+            banner_added, banner_message = self.add_maintenance_banner()
+
+            self.assertTrue(banner_added)
+            self.assertEqual(warning_message, banner_message)

openedx/core/djangoapps/util/waffle.py

@@ -3,16 +3,15 @@ Waffle flags and switches
 """
 
 
-from edx_toggles.toggles import LegacyWaffleSwitchNamespace
+from edx_toggles.toggles import WaffleSwitch
 
-WAFFLE_NAMESPACE = u'open_edx_util'
-
-# Switches
-DISPLAY_MAINTENANCE_WARNING = u'display_maintenance_warning'
-
-
-def waffle():
-    """
-    Returns the namespaced, cached, audited Waffle class for open_edx_util.
-    """
-    return LegacyWaffleSwitchNamespace(name=WAFFLE_NAMESPACE, log_prefix=u'OpenEdX Util: ')
+# .. toggle_name: open_edx_util.display_maintenance_warning
+# .. toggle_implementation: WaffleSwitch
+# .. toggle_default: False
+# .. toggle_description: Displays the maintenance warning, when active.
+# .. toggle_use_cases: opt_in
+# .. toggle_creation_date: 2018-03-20
+# .. toggle_tickets: https://github.com/edx/edx-platform/pull/17735
+DISPLAY_MAINTENANCE_WARNING = WaffleSwitch(
+    'open_edx_util.display_maintenance_warning', __name__
+)