[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

	1 Warning
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

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	`3feefd5`
	Direct Download	`woocommerce-wear-prototype-build-pr14468-3feefd5.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	`3feefd5`
	Direct Download	`woocommerce-prototype-build-pr14468-3feefd5.apk`

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

Codecov Report

❌ Patch coverage is 67.17172% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.92%. Comparing base (c797d6b) to head (3feefd5).

Files with missing lines	Patch %	Lines
...glabels/address/WooShippingEditAddressViewModel.kt	57.14%	16 Missing and 14 partials ⚠️
...orders/wooshippinglabels/address/AddressSection.kt	0.00%	14 Missing ⚠️
...ders/wooshippinglabels/address/NormalizeAddress.kt	50.00%	3 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.92%   37.92%   -0.01%     
- Complexity     9262     9266       +4     
============================================
  Files          2009     2010       +1     
  Lines        112908   112929      +21     
  Branches      14916    14932      +16     
============================================
+ Hits          42823    42826       +3     
- Misses        66186    66192       +6     
- Partials       3899     3911      +12

☔ 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.

…-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

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

3feefd5

…-errors

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

irfano commented Aug 13, 2025

Uh oh!

dangermattic commented Aug 13, 2025

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!

Uh oh!

[Shipping labels] Improve address validation errors #14468

Are you sure you want to change the base?

[Shipping labels] Improve address validation errors #14468

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

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!

Uh oh!

wpmobilebot commented Aug 13, 2025 •

edited

Loading

wpmobilebot commented Aug 13, 2025 •

edited

Loading

codecov-commenter commented Aug 14, 2025 •

edited

Loading