Add more guide message in the HTML generated by the default failure handler (#477)

* Add more guide message in the HTML generated by the default failure handler
* Add more tests
* Apply suggestions from code review

Co-authored-by: Fil Maj <[email protected]>
Co-authored-by: Alissa Renz <[email protected]>

Author: 3 people

slack_bolt/oauth/internals.py

@@ -60,7 +60,10 @@ def _build_callback_failure_response(  # type: ignore
         )
         self._logger.debug(debug_message)
 
-        html = self._redirect_uri_page_renderer.render_failure_page(reason)
+        # Adding a bit more details to the error code to help installers understand what's happening.
+        # This modification in the HTML page works only when developers use this built-in failure handler.
+        detailed_error = build_detailed_error(reason)
+        html = self._redirect_uri_page_renderer.render_failure_page(detailed_error)
         return BoltResponse(
             status=status,
             headers={
@@ -126,3 +129,20 @@ def select_consistent_installation_store(
     else:
         # only oauth_flow_store is available
         return oauth_flow_store
+
+
+def build_detailed_error(reason: str) -> str:
+    if reason == "invalid_browser":
+        return (
+            f"{reason}: This can occur due to page reload, "
+            "not beginning the OAuth flow from the valid starting URL, or "
+            "the /slack/install URL not using https://"
+        )
+    elif reason == "invalid_state":
+        return f"{reason}: The state parameter is no longer valid."
+    elif reason == "missing_code":
+        return f"{reason}: The code parameter is missing in this redirection."
+    elif reason == "storage_error":
+        return f"{reason}: The app's server encountered an issue. Contact the app developer."
+    else:
+        return f"{reason}: This error code is returned from Slack. Refer to the documents for details."

tests/slack_bolt/oauth/test_internals.py

@@ -0,0 +1,31 @@
+from slack_bolt.oauth.internals import build_detailed_error
+
+
+class TestOAuthInternals:
+    def test_build_detailed_error_invalid_browser(self):
+        result = build_detailed_error("invalid_browser")
+        assert result.startswith("invalid_browser: This can occur due to page reload, ")
+
+    def test_build_detailed_error_invalid_state(self):
+        result = build_detailed_error("invalid_state")
+        assert result.startswith(
+            "invalid_state: The state parameter is no longer valid."
+        )
+
+    def test_build_detailed_error_missing_code(self):
+        result = build_detailed_error("missing_code")
+        assert result.startswith(
+            "missing_code: The code parameter is missing in this redirection."
+        )
+
+    def test_build_detailed_error_storage_error(self):
+        result = build_detailed_error("storage_error")
+        assert result.startswith(
+            "storage_error: The app's server encountered an issue. Contact the app developer."
+        )
+
+    def test_build_detailed_error_others(self):
+        result = build_detailed_error("access_denied")
+        assert result.startswith(
+            "access_denied: This error code is returned from Slack. Refer to the documents for details."
+        )