Add progress to ZHA migration steps #155764

puddly · 2025-11-04T02:00:52Z

Proposed change

More than a few ZHA migration steps take 10-15s to complete. This PR reorganizes some of the steps for better translations and turns long-running tasks into progress steps, ensuring all stages have responsive feedback.

Demo:

zha.progress.mp4

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Deprecation (breaking change to happen in the future)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request:
Link to developer documentation pull request:
Link to frontend pull request:

Checklist

I understand the code I am submitting and can explain how it works.
The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
I have followed the perfect PR recommendations
The code has been formatted using Ruff (ruff format homeassistant tests)
Tests have been added to verify that the new code works.
Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

home-assistant · 2025-11-04T02:01:01Z

Hey there @dmulcahey, @Adminiuga, @TheJulianJES, mind taking a look at this pull request as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of zha can trigger bot actions by commenting:

@home-assistant close Closes the pull request.
@home-assistant rename Awesome new title Renames the pull request.
@home-assistant reopen Reopen the pull request.
@home-assistant unassign zha Removes the current integration label and assignees on the pull request, add the integration domain after the command.
@home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
@home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

Copilot

Pull Request Overview

This pull request refactors the ZHA config flow to use the new @progress_step() decorator for long-running operations, providing better user feedback during network formation and backup restoration. The changes convert manual progress tracking to the standardized decorator pattern introduced in Home Assistant's data entry flow system.

Key Changes

Implements @progress_step() decorator on async_step_form_new_network() and async_step_maybe_reset_old_radio()
Refactors async_step_maybe_confirm_ezsp_restore() to async_step_restore_backup() with proper progress tracking
Renames maybe_confirm_ezsp_restore step to confirm_ezsp_ieee_overwrite for clarity
Adds consume_progress_flow() helper function in tests to handle progress steps
Updates all affected tests to use the new progress flow helper

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
homeassistant/components/zha/config_flow.py	Implements progress tracking decorators and refactors restore backup flow with task-based progress handling
homeassistant/components/zha/strings.json	Adds progress messages, renames step from `maybe_confirm_ezsp_restore` to `confirm_ezsp_ieee_overwrite`, removes description from `maybe_reset_old_radio`
tests/components/zha/test_config_flow.py	Adds `consume_progress_flow()` helper and updates all tests to consume progress steps before checking results

homeassistant/components/zha/strings.json

homeassistant/components/zha/config_flow.py

Copilot · 2025-11-04T03:53:16Z

tests/components/zha/test_config_flow.py

+        if result["type"] != FlowResultType.SHOW_PROGRESS:
+            break
+
+        assert result["type"] is FlowResultType.SHOW_PROGRESS


Line 194 contains a redundant assertion that will always pass because of the break condition at line 191-192. The assertion on line 194 (assert result["type"] is FlowResultType.SHOW_PROGRESS) is unreachable if the condition at line 191 is false. Consider removing the redundant assertion at line 194.

Suggested change

assert result["type"] is FlowResultType.SHOW_PROGRESS

This is very similar to the tests in the Home Assistant hardware integrations:

core/tests/components/homeassistant_hardware/test_config_flow.py

Lines 353 to 371 in 485f7f4

async def consume_progress_flow(

hass: HomeAssistant,

flow_id: str,

valid_step_ids: tuple[str, ...],

) -> ConfigFlowResult:

"""Consume a progress flow until it is done."""

while True:

result = await hass.config_entries.flow.async_configure(flow_id)

flow_id = result["flow_id"]

if result["type"] != FlowResultType.SHOW_PROGRESS:

break

assert result["type"] is FlowResultType.SHOW_PROGRESS

assert result["step_id"] in valid_step_ids

await asyncio.sleep(0.1)

return result

I do agree that it is redundant though, but maybe this was added for clarity.. 😄

homeassistant/components/zha/strings.json

TheJulianJES

Had an initial look at this and it generally looks good to me.

Since we want to merge #155537 first, I’ll do some testing after the rebase (and a more in-depth review), so we can hopefully get it ready for the release tomorrow.

homeassistant/components/zha/strings.json

TheJulianJES · 2025-11-05T02:55:09Z

I've added the missing strings for the options flow and tested that extensively: Everything works as expected. 🎉
Also added a title to the "Forming new network" progress dialog, since the other two progress dialogs had proper titles (instead of the default "Zigbee Home Automation" title) as well.

But I do wonder if we want to remove the step from the progress "description", since it's already in the title.
For resetting the old adapter, "Your old adapter has been backed up and is being factory reset." is completely enough IMO, since that conveys that it's being reset, so no need to duplicate "Resetting old adapter" from the title again.

CLICK TO OPEN for pictures of dialogs and more text

See:

Here, it's not as clear, but I think we can just keep "This can take a minute" in the description. What is done is shown in the title and I think that's enough and easily visible, as there's not much other text:

Similar situation would apply to this (this was the only progress dialog using the default ZHA title before):

Opinions? Both options are fine with me, no real preference.
Other than that, I think this is ready to go and a nice improvement for the migration, especially when using coming from the hardware flow!

TheJulianJES

This is good to go from my side. This is a major improvement when migrating (to ZBT) and something that should really go into the next beta/release.

I've tested this extensively and noticed no issues, other than the few missing strings for the options flow that I added.

Do keep the above comment in mind, regarding possibly removing redundant information from the progress dialog descriptions. Keeping it as is now should be good as well. Maybe some users could miss the title, soo..?

We can iterate on those details in the future (if there's another beta or maybe in patch releases as well), since those would just be minor updates to the strings. Either way, that's nothing critical and this PR is fine in the current state IMO.

Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>

home-assistant bot added cla-signed has-tests integration: zha new-feature labels Nov 4, 2025

home-assistant bot assigned dmulcahey, Adminiuga and TheJulianJES Nov 4, 2025

home-assistant bot added by-code-owner Quality Scale: No score labels Nov 4, 2025

puddly marked this pull request as ready for review November 4, 2025 03:42

Copilot AI review requested due to automatic review settings November 4, 2025 03:42

puddly requested review from Adminiuga, TheJulianJES and dmulcahey as code owners November 4, 2025 03:42

puddly added this to the 2025.11.0 milestone Nov 4, 2025

Copilot AI reviewed Nov 4, 2025

View reviewed changes

TheJulianJES reviewed Nov 4, 2025

View reviewed changes

puddly added 10 commits November 4, 2025 14:35

Migrate ZHA to use progress in flows

ea303b2

Consolidate steps a little

66511f7

WIP: Update unit tests to account for new progress flow

3af6dcc

WIP: pass 2

45096b3

WIP: pass 3

fb50173

Add a synthetic step to prevent progress flow user_input from leaking

f173035

Add more space between progress lines

7948b24

Add title to restoration step

8b90842

Clean up

5653e10

Fix up after rebase

6157629

puddly force-pushed the puddly/more-zha-progress branch from 6e7191f to 6157629 Compare November 4, 2025 19:44

Clean up translations

3e27d2e

TheJulianJES reviewed Nov 5, 2025

View reviewed changes

homeassistant/components/zha/strings.json Show resolved Hide resolved

TheJulianJES added 4 commits November 5, 2025 02:45

Also add new progress strings for options flow

65e153a

Add missing progress titles for options flow

a5a9b20

Add name to ZHA backup restore task

5743bd4

Also add title to form_new_network progress dialog

add2377

TheJulianJES approved these changes Nov 5, 2025

View reviewed changes

frenck merged commit ec6d40a into home-assistant:dev Nov 5, 2025
36 checks passed

frenck added the cherry-picked label Nov 5, 2025

frenck pushed a commit that referenced this pull request Nov 5, 2025

Add progress to ZHA migration steps (#155764)

f9e06ac

Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add progress to ZHA migration steps #155764

Add progress to ZHA migration steps #155764

puddly commented Nov 4, 2025 •

edited

Loading

Uh oh!

home-assistant bot commented Nov 4, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 4, 2025

Uh oh!

TheJulianJES Nov 5, 2025

Uh oh!

Uh oh!

TheJulianJES left a comment

Uh oh!

Uh oh!

TheJulianJES commented Nov 5, 2025 •

edited

Loading

Uh oh!

TheJulianJES left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	async def consume_progress_flow(
	hass: HomeAssistant,
	flow_id: str,
	valid_step_ids: tuple[str, ...],
	) -> ConfigFlowResult:
	"""Consume a progress flow until it is done."""
	while True:
	result = await hass.config_entries.flow.async_configure(flow_id)
	flow_id = result["flow_id"]

	if result["type"] != FlowResultType.SHOW_PROGRESS:
	break

	assert result["type"] is FlowResultType.SHOW_PROGRESS
	assert result["step_id"] in valid_step_ids

	await asyncio.sleep(0.1)

	return result

Uh oh!

Add progress to ZHA migration steps #155764

Add progress to ZHA migration steps #155764

Conversation

puddly commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Type of change

Additional information

Checklist

Uh oh!

home-assistant bot commented Nov 4, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Key Changes

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 4, 2025

Choose a reason for hiding this comment

Uh oh!

TheJulianJES Nov 5, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheJulianJES left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheJulianJES commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TheJulianJES left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

puddly commented Nov 4, 2025 •

edited

Loading

TheJulianJES commented Nov 5, 2025 •

edited

Loading