Learning Objectives
By the end of this lesson you will be able to:
- Name business states using domain vocabulary instead of technical vocabulary
- Recognize when a step is too vague to be testable
- Collaborate with a BA or PO to find the right shared vocabulary for a domain
Two Wrong Directions
You already know a Given should describe state, not action. But there's a second trap waiting once you've cleared the first one: which words you use to describe that state.
Consider three ways to write the same precondition:
# Too technical
Given the session cookie is unset and the /login route has rendered its default view
# Too vague
Given the user is ready to log in
# Just right
Given a guest is on the login page
The first line reads like a debugger session. It's precise, but it excludes anyone who isn't a developer — a BA reading it learns about cookies, not about the business. The second line swings too far the other way: "ready to log in" could mean anything, and a step that could mean anything can't be reliably automated or verified. The third line hits the target: it uses a business concept — "a guest," "the login page" — that both a BA and an automation engineer can agree on and act on.
Domain Vocabulary, Not Database Vocabulary
Technical vocabulary leaks in most often when the person writing the scenario is also the person who implemented the feature. It's natural to describe the world in terms of what you just built — a session cookie, a database flag, a feature toggle — but none of that is what the business actually cares about.
# Technical vocabulary
Given the "is_premium" column for this user is set to true
# Domain vocabulary
Given a premium subscriber
"A premium subscriber" is a concept the business already has a name for — it appears in pricing pages, support tickets, and sales conversations. is_premium = true is an implementation detail of how that concept happens to be stored today. If the column gets renamed or the subscription model changes to tiers, "a premium subscriber" still means exactly the same thing; the technical version would need to be rewritten.
Finding the Right Altitude
Business-state language isn't just "avoid technical words" — it's also avoiding both extremes at once, and that's a judgment call:
- Too technical excludes non-engineers and breaks when implementation details change.
- Too vague can't be pinned down to a concrete, testable condition.
- Just right names a concept the business already recognizes, specific enough that everyone reading it agrees on exactly what's true.
A useful check: could you say this sentence out loud in a meeting with a Business Analyst, and would they nod because it matches a concept they already use — not because it's technically correct, and not because it's so soft they can't disagree with it?
Collaborating on Vocabulary
The fastest way to find the right words for a domain is to ask the people who talk about it every day. When you're unsure whether "premium subscriber," "VIP customer," or "paid tier user" is the term your product actually uses, don't guess — bring the draft scenario to the BA or Product Owner and ask which phrase matches how the business already talks about it. This isn't a detour from writing good Gherkin; it is writing good Gherkin. A shared glossary that comes out of these conversations tends to make every future scenario faster to write and easier to review, because nobody has to relitigate what a term means.
Pro Tip: If a step name would need a footnote to explain to a BA, it's too technical. If a BA would ask "okay, but what does that actually mean?", it's too vague.
Key Takeaways
- Business-state language sits between two failure modes: too technical (excludes non-engineers, breaks on implementation change) and too vague (untestable)
- Prefer domain concepts the business already has names for ("a premium subscriber") over how those concepts happen to be implemented ("is_premium = true")
- When unsure which term a domain uses, ask the BA or PO rather than guessing — a shared vocabulary speeds up every future scenario