Behavior-Driven Development
Express tests in plain-language Given-When-Then scenarios with Cucumber and Vitest.
What you'll learn
- How BDD extends TDD with shared, readable scenarios
- The Given-When-Then structure for describing behavior
- Using Cucumber and Vitest to run BDD specs
- Bridging business requirements and executable tests
Concept
From TDD to BDD
Behavior-Driven Development (BDD) builds on TDD by expressing tests in a shared, plain-language format that product owners can read. Where TDD says "write a test," BDD says "write a scenario describing the behavior, then make it executable." The goal is the same — test-first, small steps — but the vocabulary bridges the gap between business people and developers.
Given-When-Then
A BDD scenario follows the Given-When-Then structure. Given some initial context (a user with an empty cart), When an action occurs (they add a product), Then an outcome is expected (the cart total equals the product price). This maps directly to Arrange-Act-Assert but reads as a specification. Scenarios are grouped into features, each describing one capability of the system.
Tools
Cucumber runs Gherkin .feature files, matching each Given/When/Then line to a step-definition function in your code. Vitest and Jest can express the same structure with describe and it names written in plain English, often with helper functions named given, when, then for readability. For teams that need non-technical stakeholders to read and edit specs, Cucumber's Gherkin is worth the overhead; for developer-only teams, plain Vitest names often suffice.
Bridging Requirements
BDD's real value is creating a shared artifact: the feature files are both the requirements and the executable tests. When a product owner changes a scenario, the test changes too, and the team immediately sees what code must shift. This keeps documentation and tests from drifting apart — the running suite is the living spec.
In Practice
If you adopt Cucumber, keep step definitions thin — put the real logic in helper modules so the steps read like a script that a non-programmer can follow. Avoid regex-heavy step matching that obscures the connection between the Gherkin line and the code; prefer simpler matchers and parameterized steps. For teams that do not need stakeholder-facing specs, plain Vitest with descriptive describe and it names written in Given-When-Then prose gives most of BDD's readability with none of the tooling overhead. The key habit, regardless of tool, is naming tests as sentences that describe behavior and expected outcomes. When a product owner can read your test names and nod, you have achieved BDD's communication goal even without a single .feature file.
Example
// Feature: Shopping cart
// Scenario: Adding a product increases the total
// Given a cart with no items
// When the customer adds a $10 product
// Then the cart total is $10
import { describe, it, expect } from "vitest";
import { Cart } from "./Cart";
describe("Shopping cart", () => {
it("adding a product increases the total", () => {
// Given
const cart = new Cart();
// When
cart.add({ name: "Book", price: 10 });
// Then
expect(cart.total()).toBe(10);
});
});
The test name is the scenario, and the body follows Given-When-Then. This reads as a spec while remaining a fast, executable Vitest test.
Try it
- Code Diff
Review scenario diffs when business rules change.
- JSON Formatter
Format the structured data your Given contexts set up.
Common mistakes
The mistake
Writing Gherkin steps that hide all logic in regex glue
The fix
Keep step definitions thin and put the real logic in helper modules. Steps should read like a script, not an implementation.
The mistake
Treating BDD as a documentation exercise without real assertions
The fix
Every Then step must assert something meaningful. A scenario with no assertion is a spec that cannot fail, which is worthless.
Practice Behavior-Driven Development
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.