From 0faaf12ed5f1834026b3562b5c23fa1709fa15c1 Mon Sep 17 00:00:00 2001
From: epenet <6771947+epenet@users.noreply.github.com>
Date: Tue, 8 Oct 2024 22:26:47 +0200
Subject: [PATCH] Adjust reauth/reconfigure documentation to highlight expected
 result (#2352)

* Adjust reauth/reconfigure documentation to highlight expected result

* Update config_entries_config_flow_handler.md

* Update config_entries_config_flow_handler.md
---
 docs/config_entries_config_flow_handler.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md
index e8dc1bd1..fdeddb65 100644
--- a/docs/config_entries_config_flow_handler.md
+++ b/docs/config_entries_config_flow_handler.md
@@ -283,7 +283,11 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
 
     async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None):
         if user_input is not None:
-            pass  # TODO: process user input
+            # TODO: process user input
+            return self.async_update_reload_and_abort(
+                self._get_reauth_entry(),
+                data=data,
+            )
 
         return self.async_show_form(
             step_id="reconfigure",
@@ -291,6 +295,10 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
         )
 ```
 
+On success, reconfiguration flows are expected to update the current entry and abort; they should not create a new entry.
+This is usually done with the `return self.async_update_reload_and_abort` helper.
+Automated tests should verify that the reconfigure flow updates the existing config entry and does not create additional entries.
+
 Checking whether you are in a reconfigure flow can be done using `if self.source == SOURCE_RECONFIGURE`.
 It is also possible to access the corresponding config entry using `self._get_reconfigure_entry()`.
 Ensuring that the `unique_id` is unchanged should be done using `await self.async_set_unique_id` followed by `self._abort_if_unique_id_mismatch()`.
@@ -386,6 +394,8 @@ See [Translations](#translations) local development instructions.
 
 Authentication failures (such as a revoked oauth token) can be a little tricky to manually test. One suggestion is to make a copy of `config/.storage/core.config_entries` and manually change the values of `access_token`, `refresh_token`, and `expires_at` depending on the scenario you want to test. You can then walk advance through the reauth flow and confirm that the values get replaced with new valid tokens.
 
+On success, reauth flows are expected to update the current entry and abort; they should not create a new entry.
+This is usually done with the `return self.async_update_reload_and_abort` helper.
 Automated tests should verify that the reauth flow updates the existing config entry and does not create additional entries.
 
 Checking whether you are in a reauth flow can be done using `if self.source == SOURCE_REAUTH`.