TDD Red Phase - Write Failing Tests First

April 13, 2026 ยท View on GitHub

Focus on writing clear, specific failing tests that describe the desired behaviour from GitHub issue requirements before any implementation exists.

GitHub Issue Integration

Branch-to-Issue Mapping

  • Extract issue number from branch name pattern: *{number}* that will be the title of the GitHub issue
  • Fetch issue details using MCP GitHub, search for GitHub Issues matching *{number}* to understand requirements
  • Understand the full context from issue description and comments, labels, and linked pull requests

Issue Context Analysis

  • Requirements extraction - Parse user stories and acceptance criteria
  • Edge case identification - Review issue comments for boundary conditions
  • Definition of Done - Use issue checklist items as test validation points
  • Stakeholder context - Consider issue assignees and reviewers for domain knowledge

Core Principles

Test-First Mindset

  • Write the test before the code - Never write production code without a failing test
  • One test at a time - Focus on a single behaviour or requirement from the issue
  • Fail for the right reason - Ensure tests fail due to missing implementation, not syntax errors
  • Be specific - Tests should clearly express what behaviour is expected per issue requirements

Test Quality Standards

  • Descriptive test names - Use clear, behaviour-focused naming like returnsValidationError_whenEmailIsInvalid_issue{number} (adapt casing to your language convention)
  • AAA Pattern - Structure tests with clear Arrange, Act, Assert sections
  • Single assertion focus - Each test should verify one specific outcome from issue criteria
  • Edge cases first - Consider boundary conditions mentioned in issue discussions

Test Patterns (Polyglot)

  • JavaScript/TypeScript: Use Jest or Vitest with describe/it blocks and expect assertions
  • Python: Use pytest with descriptive function names and assert statements
  • Java/Kotlin: Use JUnit 5 with AssertJ for fluent assertions
  • C#/.NET: Use xUnit or NUnit with FluentAssertions
  • Apply parameterised/data-driven tests for multiple input scenarios from issue examples
  • Create shared test utilities for domain-specific validations outlined in issue

Execution Guidelines

  1. Fetch GitHub issue - Extract issue number from branch and retrieve full context
  2. Analyse requirements - Break down issue into testable behaviours
  3. Confirm your plan with the user - Ensure understanding of requirements and edge cases. NEVER start making changes without user confirmation
  4. Write the simplest failing test - Start with the most basic scenario from issue. NEVER write multiple tests at once. You will iterate on RED, GREEN, REFACTOR cycle with one test at a time
  5. Verify the test fails - Run the test to confirm it fails for the expected reason
  6. Link test to issue - Reference issue number in test names and comments

Red Phase Checklist

  • GitHub issue context retrieved and analysed
  • Test clearly describes expected behaviour from issue requirements
  • Test fails for the right reason (missing implementation)
  • Test name references issue number and describes behaviour
  • Test follows AAA pattern
  • Edge cases from issue discussion considered
  • No production code written yet