What a random phone number can prove
A random phone number generator can give a parser a wider set of inputs than a short hand-written list. It can help find edge cases in country context, separators, lengths and normalization. It cannot prove that a value belongs to a subscriber, is currently reachable or can receive SMS.
Keep those claims separate: parsing is a software behavior; allocation and reachability are network facts. Google's libphonenumber FAQ explains that numbering metadata cannot tell whether a number is currently assigned to a specific user or reachable. Treat generated values as test inputs, not contact targets.
Capture enough context to replay the failure
A seed alone may not describe the complete test that failed. Store the generator and property-test library versions, the failing path, the default region, the phone-number metadata version, the property name and the runner configuration. Keep these values together in the CI artifact so another developer can reproduce the same case.
| Record | Why it matters |
|---|---|
| Seed and counterexample path | Recreates the generated case and the route through the generator. |
| Default region and input mode | The same digits can be interpreted differently when country context changes. |
| Parser, property-test library and metadata versions | A library or numbering-plan update can change accepted and rejected cases. |
| Property ID, run ID and command | Identifies the assertion and environment that produced the failure. |
| Sanitized input artifact, if needed | Lets an authorized reviewer inspect the minimized case without copying raw values into general logs or analytics. |
In fast-check, the documented seed and path parameters can replay a failing property. The path is used with the seed. Preserve the versions and region around that pair because they are part of your own parser's test setup.
Test useful boundaries, not arbitrary digit noise
Generate structured input variations that map to a rule your product actually supports. Keep the expected behavior beside each property; don't assume every plausible-looking string should pass.
| Input dimension | Example test question | Keep fixed |
|---|---|---|
| Country context | Does explicit international input override the form's default region as designed? | Region-selection policy |
| Presentation | Do supported spaces, parentheses or hyphens normalize to the same canonical result? | Documented accepted separators |
| Length boundary | Does the validator distinguish a parseable value from a possible-length result? | Numbering-metadata version |
| Trunk prefix and calling code | Does the parser preserve or remove a domestic prefix only under the right country context? | Country and input mode |
| Extensions and extra characters | Does the application keep an extension separate and reject characters outside its stated policy? | Product input contract |
For every generated input, assert one meaningful invariant. For example, if the parser accepts an input and returns a canonical international value, parsing that canonical value again under the same region and metadata should return the same canonical value. If your product has different rules, encode those rules explicitly instead of turning a convenient assumption into an oracle.
Replay a failing property
The exact integration depends on your test runner, but the replay parameters should come from the failing run rather than a newly chosen seed:
import fc from 'fast-check';
const replay = {
seed: Number(process.env.FC_SEED),
path: process.env.FC_PATH
};
fc.assert(phoneParserProperty, replay);Replace phoneParserProperty with your property and pass the seed and path reported by the failed run. Pin the phone-number metadata package and default region too. A replay that silently uses newer metadata may exercise a different rule.
- Save the seed, path, versions, region, property ID and command in the restricted CI failure artifact.
- Run that single property with the saved values and confirm it reproduces before changing code.
- Keep the minimized counterexample as a named regression case after fixing the defect.
- Review the regression case when updating parser or numbering metadata versions.
Keep test generation away from live delivery
Randomized parsing belongs in a local or isolated test environment. Disable outbound SMS and voice at the application boundary, not only in the test data factory. If a separate delivery check is necessary, use a provider sandbox or an allowlisted line the team controls and is authorized to test.
A public developer discussion has described an integration script sending unintended messages to real phones. That is an anecdotal report, not a measure of how often it happens, but it illustrates why input generation and message delivery should be independently controlled. Never send a generated number a text just to see whether it works.
In general logs, record the property ID and run ID instead of a complete phone value. Keep raw or minimized inputs in a restricted test artifact only when a reviewer needs them; do not forward them to analytics, screenshots or public issue reports.
Frequently asked questions
How do I repeat a failing random phone-number test?
Save the property-test seed and counterexample path, then rerun with the same parser version, phone metadata, region and test command. In fast-check, replay uses the seed together with the path.
Can a random phone number generator create a number that reaches a real person?
It can produce a string that resembles a real number. Format alone does not establish assignment, and a random value must never be contacted as a test. Keep outbound delivery disabled or use an authorized provider sandbox.
Should parser tests send SMS?
No. Parser tests should stay offline. Use a separate, explicitly authorized delivery test with a sandbox or controlled destination when message delivery is the behavior under test.
Sources and related guides
- fast-check parameters: seed and path
- Google libphonenumber FAQ: limits of numbering metadata
- Public developer discussion about unintended test messages
- Safe phone number test data
- Choose the right phone number generator
This page covers replayable parser exploration. For source-reviewed fixtures and intentionally chosen regression data, continue with the fixture methodology.