TDD Revisited: The Reboot Protocol

The Pivot of Error

The industry shifted the definition of a "Unit," leading to the collapse of TDD's primary value proposition.

The Symptoms of Corruption

• The Velocity Gap: Non-TDD "procedural" developers moving faster than TDD teams because they don't pay the "Maintenance Tax" of brittle tests.
• The Mocking Trap: Using mocks to isolate classes from each other, effectively "freezing" the internal design and preventing refactoring.
• The Isolation Fallacy: Misunderstanding "Unit of Isolation." It is the Test that must be isolated from other tests, not the Class that must be isolated from its collaborators.

The Thesis: Test Behaviors, Not Implementations

To restore the value of TDD, we must decouple our test suites from our design choices.

Success State: You can completely rewrite the internal design of a module (renaming classes, moving logic, changing patterns) and 100% of your tests remain Green, because the behavior has not changed.

The Redefinition of "The Unit"

The primary failure of modern TDD is the Class-as-Unit fallacy. When the "Unit" is defined as a single class, developers are forced to mock every collaborator. This results in "Implementation-Bound" tests that break whenever the internal design changes.

Isolation Logic & The "Shared Fixture"

A "Unit Test" is not defined by the absence of File IO or Databases. It is defined by Isolation from other tests.

• The Shared Fixture Problem: If Test A writes to a DB and Test B reads from it, the tests are coupled. This is the only hard reason to avoid the DB in unit tests.
• Sociable Testing: Prefer using real internal collaborators. If Class A needs Class B to function, let it use Class B. Do not mock Class B unless it is an "Out-of-Process" dependency.
• The Speed Threshold: Developer tests must provide fast feedback. If real collaborators make the suite exceed a 2-3 minute runtime, swap the "Port" for a fast in-memory double.

Implementation Strategy: Information Hiding

To achieve this, your test suite must only interact with the Public Facade of your module.

// BAD: Testing internals (Brittle)
[Test] public void InternalCalculator_ShouldAddCorrectly() { ... }

// GOOD: Testing Behavioral Boundary (Stable)
[Test] public void OrderSystem_ShouldApplyDiscountToTotal() { ... }
            

By keeping internal classes internal or private and hiding them from the test project, you enforce a "Stable API." This ensures the tests are bound to the What, while the developer remains owner of the How.

The Protocol: Strict Red-Green-Refactor

TDD is a cognitive tool for separating Requirement Validation from Software Design. You cannot do both simultaneously without compromising quality or speed.

Shifting Gears: Pragmatic Speed Control

TDD is not a fixed-speed process. You must shift gears based on implementation complexity:

• 5th Gear (Obvious): Skip the "Sinful" Green. Write clean code immediately. If coverage remains 100%, you are safe.
• 1st Gear (Complex): If you are stuck, write "Implementation/Probe Tests" to help you find the solution.
• The Cleanup: Delete 1st Gear Tests once the behavioral Port test is Green. They are scaffolding, not the building. They will only serve to block future refactorings.

The Architectural Boundary: Ports & Adapters

To achieve TDD success, you must physically separate your Domain Logic from Infrastructure. This is the "Hexagonal" model: the center is stable, the edges are volatile.

1. The Test Boundary (The Port)

A Port is the stable public entry point of your module (e.g., a MembershipService or AddOrderCommandHandler). Tests must only talk to the Port.

• If the Port provides the correct result, the test is Green.
• How the Domain achieves that result (using 5 classes or 50) is an implementation detail.
• Benefit: You can delete, rename, or merge internal classes without touching a single test.

2. The Visibility Constraint

Enforce the boundary using your language's access modifiers:

3. The Adapter Rule (Mocking Strategy)

Separate Internal Collaborators from Secondary Adapters.

• Internal Collaborators: (e.g., a PriceCalculator class). DO NOT MOCK. Use the real class. Tests should be "Sociable."
• Secondary Adapters: (e.g., DB, SMTP, External API). MOCK ONLY IF NECESSARY. Mocking is a tool to solve the Shared Fixture problem (test interference) or Latency (slow tests).

4. The UI Fragility Warning

Drive behavioral tests through the Port, not the UI Adapter. Web-driver tests (Selenium/Cypress) are expensive and brittle. If you change a CSS class and your business logic tests break, your testing pyramid is upside down.

The Mocking & DI Policy: Fighting "Crystal Architecture"

Tests are a maintenance liability. Every mock you write is a recording of an implementation detail. If you mock internal classes, your test suite becomes a "Crystal Architecture"—it looks solid, but shatters the moment you try to refactor.

1. The Mocking Decision Matrix

Use the "Isolated & Fast" rule to decide when to use a Test Double:

2. Forbid Interaction Testing on Internals

Avoid Verify(x => x.SomeMethod()). Verifying that a method was called is not testing behavior; it is testing the call graph.

• State Assertions: Check the return value of the Port or the state of the result. (Stable).
• Interaction Verifications: Check how many times an internal method was called. (Brittle).
• The Exception: Interaction testing is only valid for Outgoing Ports where the side-effect is the behavior (e.g., "Prove an email was sent via the SMTP Port").

3. Pure DI: The "Honest Setup"

Mandate: Do not use IoC/DI Containers (Autofac, Unity, etc.) in your test suite.

• Diagnostic Value: Instantiating your Port manually using new Port(new Collaborator()) forces you to see the complexity of your design.
• The "Pain" Signal: If a constructor requires 10 dependencies, that class is a "God Object." Manual instantiation makes this pain impossible to ignore. An IoC container hides this architectural rot.
• Transparency: Any developer can follow the object graph in a test without needing to look up container registration files.

4. Don't Mock What You Don't Own

Never mock types from the .NET/Java/Third-party libraries (e.g., System.IO.File).

1. Create your own Port (Interface) that represents the specific action you need.
2. Implement an Adapter that calls the third-party library.
3. Mock your Port in the behavioral tests.

This ensures your tests are coupled to your business requirements, not a third-party vendor's API.

Pragmatic Speed: The "Gears" Framework

TDD is not a mechanical ritual; it is a cognitive strategy. You must shift your testing granularity (gears) based on the uncertainty of the task. Permanent tests stay at the Port; temporary tests probe the internals.

The Post-Mortem: ATDD & External BDD Tools

The industry's attempt to fix TDD via "Natural Language" tools (Gherkin, SpecFlow, Cucumber, Fitness) has failed. While the Behavioral Intent was correct, the Implementation Mechanism (The Translation Layer) became a velocity sinkhole.

The Solution: Native-Code Behavioral Testing

Do not abandon the "Given/When/Then" structure. Abandon the external tools. Bring the behavioral requirements directly into your developer tests hitting the Port.

FEATURE: Add to Cart
  GIVEN I have an empty cart
  WHEN I add a "Book"
  THEN the total should be $10

// PLUS: RegEx Step Definition
// PLUS: Mapping Code
// PLUS: Context Injection
                    

[Test]
public void Should_Add_Item_To_Empty_Cart() 
{
    // GIVEN
    var port = new OrderPort();

    // WHEN
    port.AddItem("Book");

    // THEN
    Assert.Equal(10, port.GetTotal());
}
                    

Section 8: Operational Smells & Social Indicators

TDD failure is not always visible in the code; it manifests in the Social Dynamics and Economic Velocity of the team. If your TDD practice is "corrupted," it will produce the following three signals.