The Red-Green-Refactor Cycle and the Mental Model of TDD

Architectural Foundations#

In traditional software development workflows, tests are authored post-factum—written only after production business logic has already been implemented. This introduces a fundamental architectural defect: engineers inadvertently couple tests to the internal mechanics of pre-existing classes, closures, and state structures (High Coupling to Implementation Details). Consequently, public interfaces (APIs) end up designed from the inward perspective of the service provider rather than the ergonomic perspective of its consumer.

Test-Driven Development (TDD) inverts this dynamic. Writing a failing test first forces the developer to confront interface boundary questions immediately:

• What should the signature of the public method look like?
• What minimal set of arguments satisfies the consumer contract?
• What response structure is most intuitive and type-safe for consuming callers?
• How should side effects be isolated to render dependencies clean and injectable?

TDD functions as an architectural decomposition discipline: complex business requirements are systematically partitioned into discrete, deterministic specifications. This eliminates speculative bloat (YAGNI — You Aren't Gonna Need It) and constrains cognitive overhead throughout implementation.

Robert C. Martin's Three Laws of TDD#

The formal mechanics of TDD are codified in three foundational laws:

1. First Law: You are not allowed to write any production code unless it is to make a failing unit test pass. Compilation or linter errors count as failures.
2. Second Law: You are not allowed to write any more of a unit test than is sufficient to fail.
3. Third Law: You are not allowed to write any more production code than is strictly sufficient to pass the current failing unit test.

Adhering to these constraints generates a rhythmic micro-cycle: a test authoring step lasting from a few seconds to one or two minutes, followed immediately by minimal source edits and runner verification.

Mental Model#

The internal engine of TDD operates as a closed continuous pipeline: the Red-Green-Refactor workflow.

Each phase maintains strict boundaries of responsibility:

+-----------------------------------------------------------------------+
|                              TDD CYCLE                                |
+-----------------------------------------------------------------------+
|                                                                       |
|   +-------------------+       +--------------------+                  |
|   | 1. RED            | ----> | 2. GREEN           |                  |
|   | Write failing     |       | Minimal code to    |                  |
|   | test specification|       | satisfy assertion  |                  |
|   +-------------------+       +--------------------+                  |
|             ^                           |                             |
|             |                           v                             |
|      New    |                 +--------------------+                  |
|      require|                 | 3. REFACTOR        |                  |
|      ment   +---------------- | Eliminate smells   |                  |
|                               | (tests stay green) |                  |
|                               +--------------------+                  |
|                                                                       |
+-----------------------------------------------------------------------+

Phase RED: Interface Contract Design#

During the Red phase, you write an executable specification for non-existent functionality. The cardinal rule: the test must fail for the exact expected reason.

• If the test fails with ReferenceError: calculateDiscount is not defined or a TypeScript compilation error, the requirement boundary is confirmed.
• If the test fails with an assertion mismatch (AssertionError: expected undefined to be 42), the absence of target functionality is established.
• If the test unexpectedly passes green before editing production code, the test is tautological, or the functionality already exists. Such a test must be rewritten.

Phase GREEN: The Path of Least Resistance#

The objective of the Green phase is to exit the red failure state as rapidly as possible. Permissible implementation tactics include:

1. Fake It: Returning hardcoded constants that directly satisfy current assertions.
2. Triangulation: Adding a second test with varying arguments to force parameterization of constants into generic algorithms.
3. Obvious Implementation: Authoring the full algorithm directly when the solution is trivial and obvious.

Phase REFACTOR: Architectural Cleanliness#

Only when all test suites are completely green does the engineer earn the right to modify production code without fear of regression. The Refactor phase addresses:

• Removing structural duplication (DRY).
• Extracting private helper routines and pure functional transformations.
• Optimizing algorithmic time and space complexity without altering observable behavior.
• Refining variable naming, domain encapsulation, and strict type constraints.

Practical Applications#

1. Authentication and Authorization Engines: Implementing token decoders, digital signature verifiers, and role-based access controllers (RBAC/ABAC) with guaranteed handling of malformed inputs and expired credentials.
2. Financial and Invoicing Calculators: Computing progressive taxation brackets, currency conversions, and compounding amortization where rounding discrepancies are unacceptable.
3. Domain Parsers and AST Compilers: Building mathematical expression evaluators, Markdown tokenizers, and binary protocol encoders incrementally from base tokens to nested trees.
4. Finite State Machines (FSM): Iteratively constructing state transitions for distributed checkout pipelines and multi-step wizards.

How It Works#

We will construct a production-ready token permission evaluator (ScopeEvaluator) using strict TDD discipline in Vitest.

Step 1: RED Phase — First Contract Specification#

We specify the initial requirement: the validator must reject empty strings and malformed tokens with an explicit custom error.

import { describe, it, expect } from 'vitest';
import { ScopeEvaluator, SecurityTokenError } from './scope-evaluator';

describe('ScopeEvaluator', () => {
  it('throws SecurityTokenError when provided with an empty string', () => {
    const evaluator = new ScopeEvaluator();

    expect(() => evaluator.evaluateToken('', ['read:users'])).toThrow(
      SecurityTokenError
    );
  });
});

Running Vitest fails immediately with a TypeScript compilation error: module ./scope-evaluator cannot be resolved. The RED phase succeeds with an expected failure.

Step 2: GREEN Phase — Minimal Code to Pass#

We author the minimum code required to turn the suite green.

export class SecurityTokenError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'SecurityTokenError';
  }
}

export class ScopeEvaluator {
  evaluateToken(token: string, requiredScopes: readonly string[]): boolean {
    if (!token) {
      throw new SecurityTokenError('Token cannot be empty');
    }
    return false;
  }
}

The test executes and passes green (PASS).

Step 3: RED Phase — Specifying Scopes and Token Formatting#

We expand the specification: valid authorization tokens must carry a Bearer prefix and a base64url payload containing granting scopes.

it('returns true when token contains all required scopes', () => {
  const evaluator = new ScopeEvaluator();
  // Encoded payload: {"sub":"usr_123","scopes":["read:users","write:orders"]}
  const payload = Buffer.from(
    JSON.stringify({
      sub: 'usr_123',
      scopes: ['read:users', 'write:orders'],
    })
  ).toString('base64url');

  const rawToken = `Bearer ${payload}`;

  const hasAccess = evaluator.evaluateToken(rawToken, ['read:users']);
  expect(hasAccess).toBe(true);
});

it('returns false when token is missing one or more required scopes', () => {
  const evaluator = new ScopeEvaluator();
  const payload = Buffer.from(
    JSON.stringify({
      sub: 'usr_123',
      scopes: ['read:users'],
    })
  ).toString('base64url');

  const rawToken = `Bearer ${payload}`;

  const hasAccess = evaluator.evaluateToken(rawToken, ['read:users', 'admin:all']);
  expect(hasAccess).toBe(false);
});

The test suite fails (FAIL) because evaluateToken unconditionally returns false.

Step 4: GREEN Phase — Expanding Implementation#

We implement base64url deserialization and set intersection logic.

interface TokenPayload {
  readonly sub: string;
  readonly scopes: readonly string[];
}

export class ScopeEvaluator {
  evaluateToken(token: string, requiredScopes: readonly string[]): boolean {
    if (!token || !token.trim()) {
      throw new SecurityTokenError('Token cannot be empty');
    }

    if (!token.startsWith('Bearer ')) {
      throw new SecurityTokenError('Invalid authorization scheme');
    }

    const base64Payload = token.slice(7);
    let parsed: TokenPayload;

    try {
      const decodedJson = Buffer.from(base64Payload, 'base64url').toString('utf-8');
      parsed = JSON.parse(decodedJson) as TokenPayload;
    } catch {
      throw new SecurityTokenError('Malformed token payload');
    }

    if (!Array.isArray(parsed.scopes)) {
      return false;
    }

    const tokenScopeSet = new Set(parsed.scopes);
    return requiredScopes.every((scope) => tokenScopeSet.has(scope));
  }
}

All 3 tests turn green (PASS). We now advance to the Refactor phase.

Step 5: REFACTOR Phase — Decomposition and Single Responsibility#

ScopeEvaluator currently violates the Single Responsibility Principle (SRP): it validates headers, decodes base64 strings, handles JSON deserialization, and validates scope authorization. We extract parsing into a dedicated TokenParser without altering observable behavior or breaking a single test.

export class SecurityTokenError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'SecurityTokenError';
  }
}

export interface DecodedToken {
  readonly subject: string;
  readonly scopes: ReadonlySet<string>;
}

export class TokenParser {
  private static readonly BEARER_PREFIX = 'Bearer ';

  public static parse(rawToken: string): DecodedToken {
    if (!rawToken || !rawToken.trim()) {
      throw new SecurityTokenError('Token cannot be empty');
    }

    if (!rawToken.startsWith(this.BEARER_PREFIX)) {
      throw new SecurityTokenError('Invalid authorization scheme');
    }

    const base64Payload = rawToken.slice(this.BEARER_PREFIX.length);
    
    try {
      const json = Buffer.from(base64Payload, 'base64url').toString('utf-8');
      const payload = JSON.parse(json) as { sub?: unknown; scopes?: unknown };

      if (typeof payload.sub !== 'string' || !Array.isArray(payload.scopes)) {
        throw new Error('Invalid token structure');
      }

      return {
        subject: payload.sub,
        scopes: new Set(payload.scopes.filter((s): s is string => typeof s === 'string')),
      };
    } catch (error) {
      if (error instanceof SecurityTokenError) throw error;
      throw new SecurityTokenError('Malformed token payload');
    }
  }
}

export class ScopeEvaluator {
  public evaluateToken(token: string, requiredScopes: readonly string[]): boolean {
    const decoded = TokenParser.parse(token);
    return this.hasRequiredScopes(decoded.scopes, requiredScopes);
  }

  private hasRequiredScopes(
    grantedScopes: ReadonlySet<string>,
    requiredScopes: readonly string[]
  ): boolean {
    return requiredScopes.every((scope) => grantedScopes.has(scope));
  }
}

Running Vitest confirms: 100% of tests remain green, while the architecture is decoupled, encapsulated, and extensible.

Common Pitfalls#

Step-by-Step TDD Iteration Protocol#

Interview Questions#

Related Topics#