1. Parsing and normalization
- National input with an explicit default country.
- International input beginning with
+. - Spaces, hyphens, parentheses and copied non-breaking spaces.
- Domestic trunk prefixes and countries where a leading zero is significant.
- Shared calling-code plans such as
+1. - Unknown country codes and missing country context.
Assert the exact canonical E.164 result, not only a true or false outcome.
2. Validation boundaries
For each supported region, include a recognized example, one digit too short, one digit too long, an impossible prefix and a syntactically valid value your product does not support. Keep possible length, numbering-plan validity, reachability and ownership as separate assertions.
Use the structural validator to explore inputs, then confirm production behavior with maintained numbering metadata.
3. Form and accessibility behavior
- Typing, pasting, deleting and changing country after entry.
- Cursor position during as-you-type formatting.
- Visible labels, associated errors and keyboard access.
- Mobile keyboard and small-screen layout.
- Server errors that preserve the user's original input.
4. Storage and API contracts
Round-trip the canonical value through the database and every API boundary. Confirm that extensions, selected region, verification status and consent timestamps use separate fields. Test deduplication with two display strings that normalize to the same destination, and decide explicitly whether shared family or office numbers are allowed.
5. Delivery safety
Disable outbound SMS and voice in routine automated tests. Use provider sandbox credentials, explicit internal allowlists and reserved fictional ranges where available. Verify that a formatting failure cannot turn a fixture into an unintended live destination.
Download deterministic positive fixtures from the country format dataset and author each negative case for one known failure reason.
6. Metadata upgrades
Numbering plans change. Run the complete country matrix whenever the parsing library or metadata changes, review altered classifications and record the metadata version used in a release. A passing regression suite is stronger than assuming an update is backward-compatible.