Red‑Green‑Refactor TDD: Practical Guide

Summary: Master the Red‑Green‑Refactor TDD cycle with practical workflow, examples, and business benefits to build cleaner, maintainable code.

Introduction

The Red‑Green‑Refactor Test‑Driven Development (TDD) cycle turns large changes into small, safe steps. Start by writing a failing test (Red), add the minimum code to pass it (Green), then clean and improve the implementation (Refactor). This fast, repeatable loop helps teams reduce risk, clarify intent, and deliver reliable features. Learnable and repeatable patterns make TDD a practical design tool for teams adopting disciplined development practices; see our TDD guide for more details: /guides/tdd.¹

The rhythm of Test‑Driven Development

TDD is often mistaken for only a testing practice, but it’s primarily a design technique. Writing tests first makes you think about how code will be used before implementing it, which reduces guesswork and keeps iterations small and verifiable. The Red‑Green‑Refactor loop becomes a dependable cadence for delivering well‑tested behaviour.²

Understanding the three stages

Each stage has a clear purpose and keeps work small and testable.

• Red phase (failing test): Write one automated test for the smallest useful behaviour. The test fails because the implementation doesn’t exist yet. The failure validates the test.
• Green phase (make it pass): Implement the minimum code required to satisfy the test. Choose simplicity over elegance to avoid over‑engineering.
• Refactor phase (improve the code): With tests passing, clean up names, remove duplication, and improve structure without changing behaviour.

Refactoring is non‑negotiable: skipping it accumulates technical debt and makes future changes harder.

Red‑Green‑Refactor at a glance

Adopting this cadence helps teams move predictably and confidently. Adoption patterns vary across organizations and markets, and measurable improvements usually follow consistent practice.¹

Walking through the TDD cycle in action

We’ll build a simple UI component to demonstrate the loop: a LikeButton using TypeScript, React, and Jest. The example shows how TDD guides design while keeping behaviour predictable.

Red phase: define the first requirement

The simplest requirement is: the component renders without crashing and displays “Like.” Write the test before the component.

// LikeButton.test.tsx
import React from 'react';
import { render, screen } from '@testing-library/react';
import LikeButton from './LikeButton';

describe('LikeButton', () => {
  it('renders a button with the initial text "Like"', () => {
    render(<LikeButton />);
    const likeButton = screen.getByRole('button', { name: /like/i });
    expect(likeButton).toBeInTheDocument();
  });
});

Running the test fails because the component doesn’t exist yet. This is the Red phase—exactly as intended.

Green phase: just enough to pass

Create the minimal component to satisfy the test.

// LikeButton.tsx
import React from 'react';

const LikeButton = () => {
  return <button>Like</button>;
};

export default LikeButton;

Run the tests again; they pass. That completes this cycle.

Refactor phase: polish the implementation

Now improve the code by adding types and a clear pattern for future changes.

// LikeButton.tsx (refactored)
import React, { FC } from 'react';

type LikeButtonProps = {};

const LikeButton: FC<LikeButtonProps> = () => {
  return <button>Like</button>;
};

export default LikeButton;

Tests still pass. The test suite gives a safety net that lets you refactor with confidence.

Iteration example: clicking the button

New requirement: clicking the button changes its text to “Liked” and disables it to prevent multiple clicks. Start with a failing test.

// LikeButton.test.tsx
it('changes text to "Liked" and becomes disabled when clicked', () => {
  render(<LikeButton />);
  const likeButton = screen.getByRole('button', { name: /like/i });
  fireEvent.click(likeButton);
  expect(likeButton).toHaveTextContent('Liked');
  expect(likeButton).toBeDisabled();
});

Implement the minimal behaviour to pass the test.

// LikeButton.tsx
import React, { FC, useState } from 'react';

type LikeButtonProps = {};

const LikeButton: FC<LikeButtonProps> = () => {
  const [liked, setLiked] = useState(false);
  const handleClick = () => setLiked(true);
  return (
    <button onClick={handleClick} disabled={liked}>
      {liked ? 'Liked' : 'Like'}
    </button>
  );
};

export default LikeButton;

Run the suite again; all tests are green. Repeat: one small requirement at a time, protected by tests.

The business case for code quality

TDD’s engineering benefits translate into business value: fewer defects in production, lower support costs, and a better customer experience. When defects are caught early they are cheaper to fix, and a disciplined TDD practice correlates with measurable reductions in debugging and rework.²

Reducing post‑release defects and maintenance costs

By writing tests before code, you add only production code that satisfies a test, producing a robust safety net and fewer regressions over time. Empirical studies and industry reports document lower defect rates and reduced maintenance effort for teams that apply TDD and automated testing consistently.²

A focus on quality upfront lowers total cost of ownership because it prevents the compounding cost of technical debt.

Accelerating onboarding and improving predictability

A comprehensive test suite acts as executable documentation. New developers can run tests to learn expected behaviour instead of relying on outdated wikis, which shortens ramp time and reduces pressure on senior engineers. Consistent TDD practice also improves predictability: many small, tested cycles make estimates and progress tracking more reliable for planning and stakeholder communication.³

Common TDD pitfalls and how to avoid them

TDD is simple to describe but subtle to master. The following anti‑patterns commonly undermine its benefits.

Integration tests in unit test clothing

Problem: A test exercises many moving parts—the component, services, API clients, and a database—making it slow and brittle.

Fix: Test a single unit in isolation. Use mocks, stubs, and fakes for external dependencies. If you need integration coverage, write dedicated integration tests that run separately.

A true unit test shouldn’t touch the network, filesystem, or a real database. Its speed and reliability let you refactor fearlessly.⁴

Testing implementation instead of behaviour

Problem: Tests assert internal details instead of public behaviour. Tests break when you refactor internals, even though behaviour is unchanged.

Fix: Test the public API and observable effects. Ask, given this input, what is the expected output? Behavioural tests resist unrelated refactors and serve as living documentation.

Skipping the refactor step

Problem: Developers rush to the next feature after tests pass, leaving messy implementations behind.

Fix: Treat refactor as required. With tests passing, small cleanups are safe and compound into a codebase that’s easier to change.

Integrating TDD into your team and legacy code

Adopting TDD is a cultural change as much as a technical one. Encourage hands‑on learning, make tests part of the team’s Definition of Done, and celebrate test‑driven wins.

Championing TDD within the team

Practical ways to build momentum:

• Pair programming, where an experienced developer guides a teammate through the Red‑Green‑Refactor cycle.
• Mob programming for tougher problems, rotating who drives to spread knowledge.
• Lunch‑and‑learn sessions that demonstrate real examples of TDD in your codebase.

Start small, and let early test catches become proof points for the team.

Taming legacy code with characterization tests

When code is untested and risky to change, write characterization tests to document current behaviour. These tests let you refactor or add features with confidence by first asserting how the system behaves today.

Automating quality with CI/CD pipelines

Run the test suite on every commit in CI. This provides immediate feedback, enforces quality gates, and makes passing tests a mandatory step before merging. Automation keeps the test feedback loop fast and dependable; for pipeline practices see our CI/CD guide: /guides/ci-cd.³

Your top TDD questions, answered

Does TDD replace other kinds of testing?

No. TDD focuses on unit tests as a design tool, but you still need integration tests and end‑to‑end tests to validate component interactions and full user flows.

How do I use TDD with databases or external APIs?

Isolate code from external dependencies with mocks, stubs, or fakes. Test business logic in isolation and reserve real integration tests for separate suites.

Is it worth testing simple UI components?

Yes, when you test behaviour, not implementation. Verify what users see and do, such as whether a button renders the correct label or triggers the expected action when clicked.

Quick Q&A: Getting started

Q: What’s the smallest first step to adopt TDD?

A: Start with a single new feature or a noncritical bug. Require a failing test before implementation and include the refactor step as part of the cycle.

Q: How long before my team sees value from TDD?

A: Small wins—fewer regression bugs and faster debugging—often appear within a few sprints, depending on team size and discipline.²

Quick Q&A: Team adoption and process

Q: How do we convince stakeholders to invest time in tests?

A: Show long‑term savings: fewer incidents, lower maintenance costs, and faster feature delivery. Use concrete incidents your team has faced and link TDD effort to measurable outcomes.³

Q: How do we keep tests fast and reliable?

A: Keep unit tests isolated from external systems, use mocks for slow dependencies, and run slower integration tests in a separate pipeline.⁴

Quick Q&A: Legacy code and CI

Q: How do I introduce TDD into legacy code?

A: Add characterization tests to capture current behaviour, then refactor incrementally with tests as your safety net.

Q: What role does CI play in TDD?

A: CI enforces quality gates by running tests on every commit, providing fast feedback and preventing regressions from reaching production.³