Mastery of TDD

Ubiquitous Language in Tests

When the language of the business, the code, and the tests converge, specifications stop drifting. A practical guide to making domain vocabulary flow end to end.

A test is a message. The author sends it forward to future readers — a new hire, a reviewer, an agent picking up the next task — who need to understand what the system is supposed to do. Every word in that message is part of the contract.

When the vocabulary in tests matches the vocabulary the business uses, the message lands. When they drift, the reader has to translate — and translation is where bugs slip in.

Ubiquitous language is the Domain-Driven Design idea that a single shared vocabulary should run through conversations, requirements, code, and tests. Applied to tests specifically, it’s the difference between a suite that specifies behavior and a suite that merely exercises code.

What the Drift Looks Like

Here is a test written in code-speak:

[Test]
public void ProcessOrder_WhenSubtotalOver50_SetsShippingFlagTrue()
{
    var req = new OrderRequest { Items = new[] { new Item { Price = 30m } }, CustomerId = 1 };
    var result = _handler.Handle(req);
    Assert.IsTrue(result.FreeShipping);
}

And the same behavior in domain language:

[Test]
public void Orders_over_fifty_dollars_ship_free()
{
    var order = anOrder().containing(aBook().pricedAt(Money.Dollars(60)));

    var receipt = checkout.Process(order);

    receipt.Shipping.Should().Be(Free);
}

Both tests pass. Only one explains what the system does. The first will need a comment. The second is the comment.

Three Places the Vocabulary Must Align

Drift shows up in three specific places.

1. Test Names

A test name is a claim about the system in the language of the business. ProcessOrder_Test_1 makes no claim. Orders_over_fifty_dollars_ship_free is a specification.

Write test names the way product talks about the feature. If product says “VIP customers skip the waitlist,” the test is named VIP_customers_skip_the_waitlist — not TestPriorityQueueBypass_VIP_True.

See: Test Naming Guide, Stages of Naming.

2. Test Setup (Builder APIs)

Setup is where language density is highest. A builder that reads aCustomer().withLoyaltyTier("gold").withAddress(new Address{City="SF"}) is leaking implementation into the scenario. The business doesn’t say “tier gold.” It says “a loyalty member in San Francisco.”

// Leaking implementation
var c = aCustomer().withLoyaltyTier("gold").withAddressState("CA");

// Speaking domain
var c = aLoyaltyMember().in(california());

Named instances (Object Mothers), fluent setters in business verbs, and domain types instead of primitives are how the test setup earns the right to be called a specification.

See: Test Data Builders.

3. Assertions

An assertion is the punchline of a test. It should state the expected behavior in domain terms.

// Implementation leak
Assert.AreEqual(0m, receipt.ShippingCost);

// Domain terms
receipt.Shipping.Should().Be(Free);

Domain types (Money, ShippingCost, Free, StandardRate) make the assertion readable without a mental translation step. The test reads more like a sentence and less like a comparison between numbers that happen to mean something.

Where the Vocabulary Comes From

The language of tests should not be invented by developers. It should be pulled from the business.

  • Sit in the next product refinement session and write down the nouns and verbs used. Those are your test names, your builder methods, and your domain types.
  • When the business introduces a new term (“rewards member” replacing “loyalty member”), the next PR should rename the domain type, the builder method, and every test that referenced the old term. One commit. No drift.
  • If the business uses two words for the same concept, push back before writing the code. Force a decision. Ambiguity in vocabulary becomes ambiguity in the code.

Signs the Language Has Drifted

  • Tests and product specs use different words for the same concept.
  • Builders expose parameters that the business never talks about.
  • Test names reference class names, method names, or technical implementation (“handler”, “processor”, “service”).
  • New team members ask “what is a FlagType of 3?” and the answer isn’t in the code.
  • Agents generate code with subtly wrong vocabulary that humans have to translate back.

Each of these is drift in a specific place. Each is fixable in the next PR.

Why This Matters for Agents

Agents trained on your codebase learn the vocabulary they find in your tests. If the tests speak the domain, the agent speaks the domain. If the tests speak implementation-ese, the agent generates implementation-ese — and every PR arrives with slightly wrong terminology that humans have to correct.

A test suite written in ubiquitous language is the cheapest possible way to keep agent output consistent with how the business actually talks. The test suite trains the model every time a new version of it runs the code.

Rules of Thumb

  • If product wouldn’t say it, the test shouldn’t say it. Rename.
  • If the test needs a comment to explain it, the language is wrong. Comments are a smell.
  • When business terms change, change the code in the same PR. Never leave a rename for later.
  • Prefer domain types over primitives at test boundaries. Money, not decimal. EmailAddress, not string.
  • Review test naming in code review. “Can you rename this test to match how we talk about it” is a legitimate review comment.