Address test data is usually the last fixture set anyone organises, and the first one to become useless. It starts as a handful of strings pasted into a seed script, grows by one line every time a bug is fixed, and ends up as forty near-identical samples that nobody understands and everybody is afraid to delete.
This article describes a way to arrange the data so it stays legible: grouped by country and by scenario, reproducible from a documented origin, and clearly marked as synthetic so that no future reader mistakes it for a customer record.
Start from scenarios, not from countries
The instinct is to organise fixtures by geography — one sample per country served. It produces a long list with very little coverage, because what breaks an address pipeline is rarely the country itself. It is a specific shape of data: a missing postal code, an overlong street line, a unit detail, a non-Latin script, a region that disagrees with its postal code.
Organise by scenario first and note the country inside each scenario. A workable starting set looks like this.
| Scenario | What it exercises | Example shape |
|---|---|---|
| Minimal address | Required fields only, no unit, no district | Street, city, division, postal code |
| Full address | Every optional field present | Adds unit, building, district, second line |
| Missing postal code | Field optional in some countries | A country whose addresses carry no code |
| Digit-only postal code | Text storage, leading zeros | A code whose first character is zero |
| Letter-and-digit postal code | Character classes and separators | A code with letters interleaved |
| Overlong street line | Length limits and truncation | A long name plus a unit detail |
| Non-Latin script | Character set and rendering | A name in a non-Latin writing system |
| Inconsistent region | Relational checks | A region that cannot host that postal code |
That set is small, and it covers more failure modes than a sample from all eighty-odd countries would. The country that tests nothing is the one everybody already supports.
Why must address fixtures be reproducible?
An address fixture that cannot be regenerated is a fixture nobody trusts. If the data was copied from somewhere once and the source is gone, then when a test fails you cannot tell whether the failure is a regression in your code or a change in a value that happened to be sitting there.
Reproducibility means the same input produces the same output, on any machine, at any time. Two ways to get there. Either the values are derived deterministically from an identifier — the same seed, the same address, every run — or the values are checked in as files and never edited by hand. What does not work is a generator that returns a different sample every invocation and writes it into the fixture, because then two engineers running the same test compare against different data.
Deterministic generation has a second benefit in staging environments. A record loaded twice carries the same address, so a re-run does not create duplicates that only differ in their address fields, and a screenshot from last week still matches the record you are looking at today.
Why real customer addresses never belong here
Copying production addresses into a test or staging environment is the single most common data-protection mistake in this area, and it is easy to understand why people do it: the data is realistic, it is already there, and nobody has to think about coverage.
An address is personal data. It identifies a person, or a very small group of people, and in combination with a name, an order history or an account identifier it is enough to make someone findable. A staging database built by copying production inherits all of that, usually with weaker access controls, more copies on more laptops, and a longer retention period than anyone intended. The rules differ by jurisdiction and by contract, and this article is not legal advice, but the technical practice is not in doubt: do not move real address data into a non-production environment. The wider picture, including retention and masking, is covered in address data privacy.
Synthetic data removes the dilemma. It is realistic in shape, it is not anyone’s address, and it can be published, shared, committed and regenerated freely.
How do you keep synthetic data honest?
Synthetic data decays. Someone adds a field, someone else hand-edits a value to reproduce a bug, and within a few months the fixture set no longer matches the schema it is supposed to test.
Three habits slow that decay. Mark the data as synthetic in the dataset itself, not only in a comment, so a row carries its own status wherever it travels. Keep a documented origin for the whole set — one generator invocation or one checked-in file — rather than per-record provenance that nobody updates. And re-derive the fixtures when the schema changes rather than patching individual rows, so the set stays internally consistent.
It also helps to make the synthetic nature visible where it matters. A recipient name or a marker in the address block that clearly is not a real one prevents a screenshot of staging from being mistaken for a real record, and prevents a test address from being used for an actual shipment by someone who found it in a log. The set as a whole is synthetic: built for software testing, tied to no real delivery route, and silent about anyone’s residence.
For developers: shape, isolation and review
Keep fixtures in the repository as data, not as code that constructs data inline. Values in a file are diffable, reviewable and greppable; values built by a chain of calls inside a test helper are none of those, and when a fixture changes nobody sees it in review.
Give each field the type the production schema uses, including the text type on postal codes. A fixture that stores a postal code as a number will hide the leading-zero bug it was supposed to catch, and the test will pass for the wrong reason. Fixtures should be as strict as production, never more forgiving.
Isolate the data by environment and be explicit about which set runs where. Unit tests want tiny deterministic samples; integration tests want the scenario matrix above; staging seed data wants volume, generated rather than copied. The three sets have different lifespans, and merging them is what makes a seed script impossible to change safely.
Finally, review fixture changes like code. A one-line change to a fixture can silently convert a failing test into a passing one, and it is exactly the kind of change that arrives in a large diff with no explanation.
Next steps
Write the scenario matrix for your own product before you add another country sample, and delete the fixtures that test nothing. Then generate the synthetic set in one pass through the address generator, commit the values, and record the parameters that produced them. If your fixtures also carry phone numbers, the consistency rules in phone prefixes and locality matching are worth applying at the same time. For the difference between reformatting and real checking, see address validation and normalization.