[Shipping labels] Improve address validation errors #14468

irfano · 2025-08-13T21:07:51Z

Description

This PR adds support for displaying address field errors on the Edit Address screen, using the validation errors returned from the endpoint. For example, when the house number is missing, the API response looks like this:

 "errors": {
      "address": "House number is missing",
      "general": "Address not found"
    },

Steps to reproduce

Go to Orders.
Select an order that is eligible for creating shipping labels.
Tap the Create shipping label button.
Tap the Shipment details button to open the bottom sheet.
Tap the Edit button next to "Ship to".
Modify the address and enter an invalid one (e.g., omit the house number).
Tap "Validate & Save".

Testing information

Repeat the steps for the origin address as well, but ensure that unverified addresses can't be saved as origin addresses.

The tests that have been performed

Steps above

Images/gif

Before	After

I have considered if this change warrants release notes and have added them to RELEASE-NOTES.txt if necessary. Use the "[Internal]" label for non-user-facing changes.

This commit updates the `AddressNormalizationModel` to include a new `errors` field. The `WooShippingNetworkingMapper` is also updated to map the errors from the DTO to the model.

The `NormalizeAddressException` class is updated to accept a map of errors instead of a single error string. This allows for more granular error reporting, specifically differentiating between general errors and address-specific errors.

The error handling in `NormalizeAddress.kt` is updated to provide more specific error messages. - If the response model is null, an "Empty response" message is used. - `NormalizeAddressException` is now used when there are specific address errors. - A general `Exception` is used for other errors, incorporating the error message from the response if available.

The `AddressStatus` enum has been converted to a sealed class. This change allows for more detailed state representation, particularly for the `VerifyFailed` status, which can now optionally include a `NormalizeAddressException`.

dangermattic · 2025-08-13T21:09:01Z

	2 Warnings
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.
⚠️	This PR is assigned to the milestone 23.1. This milestone is due in less than 2 days. Please make sure to get it merged by then or assign it to a milestone with a later deadline.

Generated by 🚫 Danger

irfano · 2025-08-13T21:23:52Z

...n/kotlin/com/woocommerce/android/ui/orders/wooshippinglabels/address/EditAddressViewState.kt

I created this class to address the LargeClass Detekt error in the WooShippingEditAddressViewModel class.

irfano · 2025-08-13T21:24:57Z

.../main/kotlin/com/woocommerce/android/ui/orders/wooshippinglabels/address/NormalizeAddress.kt

@@ -12,22 +12,30 @@ class NormalizeAddress @Inject constructor(
    private val site: SelectedSite,
 ) {
    suspend operator fun invoke(address: Address): Result<AddressNormalizationModel> {
-        return site.getOrNull()?.let {


I changed site.getOrNull() to site.get() to align with the approach we use for our domain classes in the shipping label screens.

wpmobilebot · 2025-08-13T21:30:22Z

📲 You can test the changes from this Pull Request in WooCommerce-Wear Android by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce-Wear Android
	Platform	⌚️ Wear OS
	Flavor	Jalapeno
	Build Type	Debug
	Commit	`105114e`
	Direct Download	`woocommerce-wear-prototype-build-pr14468-105114e.apk`

wpmobilebot · 2025-08-13T21:51:25Z

📲 You can test the changes from this Pull Request in WooCommerce Android by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce Android
	Platform	📱 Mobile
	Flavor	Jalapeno
	Build Type	Debug
	Commit	`105114e`
	Direct Download	`woocommerce-prototype-build-pr14468-105114e.apk`

codecov-commenter · 2025-08-14T03:55:40Z

Codecov Report

❌ Patch coverage is 60.79295% with 89 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.90%. Comparing base (204ac0a) to head (105114e).
⚠️ Report is 32 commits behind head on trunk.

Files with missing lines	Patch %	Lines
...glabels/address/WooShippingEditAddressViewModel.kt	48.38%	25 Missing and 23 partials ⚠️
...orders/wooshippinglabels/address/AddressSection.kt	0.00%	14 Missing ⚠️
...ders/wooshippinglabels/address/NormalizeAddress.kt	33.33%	9 Missing and 3 partials ⚠️
...nglabels/networking/WooShippingNetworkingMapper.kt	0.00%	5 Missing ⚠️
.../wooshippinglabels/address/EditAddressViewState.kt	94.36%	1 Missing and 3 partials ⚠️
...oid/ui/orders/wooshippinglabels/ShipmentDetails.kt	0.00%	2 Missing ⚠️
...oid/ui/orders/wooshippinglabels/networking/DTOs.kt	0.00%	2 Missing ⚠️
...inglabels/networking/WooShippingLabelRepository.kt	0.00%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk   #14468      +/-   ##
============================================
- Coverage     37.91%   37.90%   -0.02%     
- Complexity     9329     9333       +4     
============================================
  Files          2017     2018       +1     
  Lines        113250   113293      +43     
  Branches      14985    15005      +20     
============================================
+ Hits          42942    42944       +2     
- Misses        66392    66413      +21     
- Partials       3916     3936      +20

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…-errors

hichamboushaba

Nice work @irfano, works well.
I just left a question, but I'm pre-approving.

hichamboushaba · 2025-08-15T19:02:47Z

.../main/kotlin/com/woocommerce/android/ui/orders/wooshippinglabels/address/NormalizeAddress.kt

+    val generalError: String?
+        get() = errors[ERROR_GENERAL]
+    val addressError: String?
+        get() = errors[ERROR_ADDRESS]


Just a remark here, the iOS app exposes an error for the name field (here), and the plugin takes this a step further by accepting an error for all fields (Check lines 43 to 49 of the file address-step/fields.jsx).

I'm not sure how to trigger any of the other errors, so I'm not sure if we need to support this or not, WDYT?

I didn't add errors for the other fields because I couldn't reproduce them. I reviewed address-step/fields.jsx but still couldn't determine the mapping. In this PR, I mapped address key to the "Address" field, but I couldn't find the keys for the other fields.
@itsmeichigo, since you used name for the "Name" field errors, have you found a way to reproduce the name error?

I reviewed address-step/fields.jsx but still couldn't determine the mapping

You can find all the keys by looking for getProps on the file: name, company, email, phone, country, address, city, state and postcode. The mapping with of the error with the key is done on line 43.

I didn't add errors for the other fields because I couldn't reproduce them

IMO we can add them without being able to reproduce them, in case the errors happen for some specific countries, but that's now a blocker for merging this PR.

Thanks for your input, @hichamboushaba! I’ve added errors for name, company, email, phone, city, and postcode. I think it’s worth testing again, could you test it once more?

I couldn’t test the errors with API Faker, so I used the Network Inspector’s Rules tab with the following mocked response:

{ "data": { "success": false, "errors": { "name": "Testing name error", "company": "Testing company error", "address": "House number is missing", "city": "Testing city error", "state": "Testing state error", "postcode": "Testing postcode error", "email": "Testing email error", "phone": "Testing phone error", "general": "Address not found" }, "isTrivialNormalization": false, "address": { "address_1": "60 29TH STREET #343", "address_2": "", "city": "SAN FRANCISCO", "company": "", "country": "US", "default_address": false, "email": "[email protected]", "is_verified": false, "name": "IRFAN OMUR", "phone": "", "postcode": "94110-4929", "state": "CA" } } }

I didn't add test for country and state. Country field is always dropdown, so it's not necessary to add error for it. state can be editable for some cases but I decided not to add error for it as well since it's rarely not a dropdown, effort to add error for state field was larger and I didn't want to increase the scope of this PR. Plus we aren't even sure server send errors for states. Let me know if you think we should add it.

Thanks @irfano, I tested the changes using ApiFaker, and it works as expected.

I didn't add test for country and state. Country field is always dropdown, so it's not necessary to add error for it. state can be editable for some cases but I decided not to add error for it as well since it's rarely not a dropdown, effort to add error for state field was larger and I didn't want to increase the scope of this PR. Plus we aren't even sure server send errors for states. Let me know if you think we should add it.

Sounds good to me.

…-errors

Previously, only a general address error was shown. Now, errors for name, company, address, city, postcode, email, and phone are surfaced individually.

…-errors

irfano added 11 commits August 13, 2025 22:32

Make NormalizationResponseDTO parameters nullable

cb4ff85

Add errors to address normalization model

2959c0b

This commit updates the `AddressNormalizationModel` to include a new `errors` field. The `WooShippingNetworkingMapper` is also updated to map the errors from the DTO to the model.

Handle errors parameter for normalizeAddress in the repository

d198fe5

Refactor NormalizeAddress error constants

4f63487

Refactor AddressStatus to be a sealed class

68ee7b9

The `AddressStatus` enum has been converted to a sealed class. This change allows for more detailed state representation, particularly for the `VerifyFailed` status, which can now optionally include a `NormalizeAddressException`.

Improve address normalization error handling and analytics

0103472

Update address with normalize exception

cab0e5d

Update address status according to normalize exception

3ac3773

Update getErrorState() logic to handle new normalize exception

61893fb

irfano added this to the 23.1 milestone Aug 13, 2025

irfano added feature: shipping labels Related to creating, ordering, or printing shipping labels. Task (new) labels Aug 13, 2025

irfano force-pushed the issue/WOOMOB-904-improve-address-validation-errors branch 2 times, most recently from edd4641 to 70a6a58 Compare August 13, 2025 21:23

irfano commented Aug 13, 2025

View reviewed changes

irfano requested review from JorgeMucientes and hichamboushaba August 13, 2025 21:26

irfano added 2 commits August 14, 2025 00:34

Shorten WooShippingEditAddressViewModel.kt class

b62508d

Update RELEASE-NOTES.txt

4b1fc71

irfano force-pushed the issue/WOOMOB-904-improve-address-validation-errors branch from 70a6a58 to 4b1fc71 Compare August 13, 2025 21:35

Merge branch 'trunk' into issue/WOOMOB-904-improve-address-validation…

0a60b8b

…-errors

hichamboushaba self-assigned this Aug 15, 2025

hichamboushaba approved these changes Aug 15, 2025

View reviewed changes

irfano added 5 commits August 18, 2025 13:23

Merge branch 'trunk' into issue/WOOMOB-904-improve-address-validation…

3feefd5

…-errors

Display individual field errors for address normalization API

debbc11

Previously, only a general address error was shown. Now, errors for name, company, address, city, postcode, email, and phone are surfaced individually.

Merge branch 'trunk' into issue/WOOMOB-904-improve-address-validation…

f42c834

…-errors

Merge branch 'trunk' into issue/WOOMOB-904-improve-address-validation…

8577a2b

…-errors

Merge branch 'trunk' into issue/WOOMOB-904-improve-address-validation…

105114e

…-errors

irfano enabled auto-merge August 20, 2025 10:00

irfano merged commit 278279d into trunk Aug 20, 2025
17 checks passed

irfano deleted the issue/WOOMOB-904-improve-address-validation-errors branch August 20, 2025 10:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Shipping labels] Improve address validation errors #14468

[Shipping labels] Improve address validation errors #14468

Uh oh!

irfano commented Aug 13, 2025

Uh oh!

dangermattic commented Aug 13, 2025 •

edited

Loading

Uh oh!

irfano Aug 13, 2025

Uh oh!

irfano Aug 13, 2025

Uh oh!

wpmobilebot commented Aug 13, 2025 •

edited

Loading

Uh oh!

wpmobilebot commented Aug 13, 2025 •

edited

Loading

Uh oh!

codecov-commenter commented Aug 14, 2025 •

edited

Loading

Uh oh!

hichamboushaba left a comment

Uh oh!

hichamboushaba Aug 15, 2025

Uh oh!

irfano Aug 18, 2025

Uh oh!

hichamboushaba Aug 18, 2025

Uh oh!

irfano Aug 19, 2025 •

edited

Loading

Uh oh!

hichamboushaba Aug 20, 2025

Uh oh!

Uh oh!

Uh oh!

[Shipping labels] Improve address validation errors #14468

[Shipping labels] Improve address validation errors #14468

Uh oh!

Conversation

irfano commented Aug 13, 2025

Description

Steps to reproduce

Testing information

The tests that have been performed

Images/gif

Uh oh!

dangermattic commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

irfano Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

irfano Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

wpmobilebot commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wpmobilebot commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

hichamboushaba left a comment

Choose a reason for hiding this comment

Uh oh!

hichamboushaba Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

irfano Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

hichamboushaba Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

irfano Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hichamboushaba Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dangermattic commented Aug 13, 2025 •

edited

Loading

wpmobilebot commented Aug 13, 2025 •

edited

Loading

wpmobilebot commented Aug 13, 2025 •

edited

Loading

codecov-commenter commented Aug 14, 2025 •

edited

Loading

irfano Aug 19, 2025 •

edited

Loading