Key takeaways
- Test that country switching updates labels, requirements, and formats together
- Separate raw input, normalized values, and server results
- Configure semantic autocomplete tokens and localized visible labels
- Preserve input after failure and move focus to a useful error
Authorship and review
Read our editorial and review principles- Written by
- Random Address Generator Editorial Team
- Reviewed by
- Forms and QA Review Team
- Latest substantive update
- Added country switching, dynamic fields, autocomplete tokens, and a layered test matrix.
Layer one: country-switching state
Selecting a country may relabel City, change State to Province or Prefecture, hide a region, and replace the postcode hint. Assert that the UI and API derive from the same country configuration.
Never silently erase entered text on a country change. Confirm first or retain per-country drafts, then lock that behavior into regression tests.
| Country | Localized labels | Key behavior |
|---|---|---|
| United States | State / ZIP Code | Two-letter state and five-digit ZIP |
| Canada | Province / Postal Code | A1A 1A1 with space |
| United Kingdom | Post Town / Postcode | County normally optional |
| Japan | Prefecture / Postal code | Seven-digit code and multiple levels |
| Australia | Suburb / State / Postcode | Four-digit postcode |
Layer two: semantic HTML and autofill
name, label, and autocomplete have distinct jobs. Labels explain local meaning; name follows the API contract; autocomplete uses standardized tokens such as country, address-line1, address-level1, address-level2, and postal-code.
Do not combine street-address with address-line1 and address-line2 for the same address representation.
<input name="addressLine1" autocomplete="shipping address-line1" />
<input name="locality" autocomplete="shipping address-level2" />
<input name="region" autocomplete="shipping address-level1" />
<input name="postalCode" autocomplete="shipping postal-code" />Layer three: validation, normalization, and verification
Validation asks whether input shape is acceptable. Normalization standardizes case and separators. Verification compares against reference data. Give them separate states and messages.
Avoid rewriting on every keystroke. Normalize on blur or submit and show the resulting change.
- Distinguish empty, too long, and invalid-character errors
- Retain rawValue before normalization
- Do not clear the form after a lookup timeout
- Never label a regex match as deliverable
Layer four: error recovery and accessibility
After failure, focus an error summary or the first invalid field. Connect messages with aria-describedby, never rely on color alone, and retain other field values.
Keyboard-test country selects, suggestion lists, error links, and post-submit focus. Locate automated tests by labels or roles rather than country-specific placeholders.
Layer five: assert the real API payload
Capture the submitted request and assert countryCode, regionCode, postalCode, rawAddress, and normalizedAddress. Read the record back to detect encoding and null-conversion failures.
A UI-only assertion can miss a Province select that displays Ontario correctly but submits Ontario instead of ON. It can also miss a cleared second line that leaves the previous value in storage. Run one record through create, edit, reopen, and export so the test proves a complete round trip rather than one successful screen state.
Exercise third-party lookup behavior with slow responses, rate limiting, server errors, no suggestions, and several plausible suggestions. A network failure must not be worded as your address is wrong. System unavailability and unacceptable input are different states with different remedies.
Version the country configuration used by the test. When postal rules or product requirements change, a failure should identify whether the application changed or the reference snapshot changed.
- Snapshot the final request JSON
- Confirm clearing an optional field removes its old value
- Simulate timeout, 429, 500, no result, and multiple results
- Separate system-error copy from input-error copy
Frequently asked questions
Should every country show a State field?
No. Relabel it Province, Prefecture, or Region where appropriate, and hide it where the country does not require that level.
Can autocomplete replace a visible label?
No. Autocomplete serves the browser; labels serve people and assistive technology.
Can a failed lookup clear the form?
It should not. Preserve input, identify the field, and let the user correct it in place.