Skip to content

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

Practice Behavior-Driven Development

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors