{
  "id": "page:library-atdd-tdd",
  "_kind": "Page",
  "_file": "wiki/library/atdd-tdd.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "ATDD/TDD Methodology (Library)",
    "displayName": "ATDD/TDD Methodology (Library)",
    "slug": "library/atdd-tdd",
    "articlePath": "wiki/library/atdd-tdd.md",
    "article": "\n# ATDD/TDD Methodology\n\n**Test-Driven Development with Acceptance Test-Driven Development**\n\nA combined approach that uses acceptance tests (ATDD) at the feature level to drive unit-level test-driven development (TDD), ensuring both external quality (building the right thing) and internal quality (building it right).\n\n## Overview\n\nThis methodology implements a dual-layer testing approach:\n\n### ATDD (Acceptance Test-Driven Development)\n- **Outside-in**: Start with customer/stakeholder perspective\n- **Acceptance criteria**: Define what \"done\" means\n- **Executable specifications**: Tests become living documentation\n- **Business validation**: Ensures we're building the right thing\n\n### TDD (Test-Driven Development)\n- **Red-Green-Refactor**: Classic TDD cycle\n- **Unit-level**: Focus on implementation details\n- **Design emergence**: Tests drive better code design\n- **Continuous feedback**: Ensures we're building it right\n\n## Process Flow\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    ATDD LAYER (Outside-in)                   │\n├─────────────────────────────────────────────────────────────┤\n│ 1. Define Acceptance Criteria                               │\n│    └─ Collaborate with stakeholders                         │\n│    └─ Define \"done\" criteria (Given-When-Then)              │\n│                                                              │\n│ 2. Create Acceptance Tests                                  │\n│    └─ Write executable acceptance tests                     │\n│    └─ Tests should FAIL initially (feature not built yet)   │\n│                                                              │\n├─────────────────────────────────────────────────────────────┤\n│                    TDD LAYER (Inside-out)                    │\n├─────────────────────────────────────────────────────────────┤\n│ Repeat until acceptance tests pass:                         │\n│                                                              │\n│   3. RED: Write Unit Test                                   │\n│      └─ Minimal test for next piece of functionality        │\n│      └─ Test should FAIL                                    │\n│                                                              │\n│   4. GREEN: Implement Code                                  │\n│      └─ Write simplest code to make test pass              │\n│      └─ All tests should PASS                               │\n│                                                              │\n│   5. REFACTOR: Improve Design                               │\n│      └─ Clean up code (remove duplication, improve clarity) │\n│      └─ All tests should still PASS                         │\n│                                                              │\n│   6. Check Acceptance Tests                                 │\n│      └─ Do acceptance tests pass yet?                       │\n│      └─ If not, repeat TDD cycle                            │\n│                                                              │\n├─────────────────────────────────────────────────────────────┤\n│ 7. Verify Acceptance (Final)                                │\n│    └─ All acceptance criteria met                           │\n│    └─ Feature complete                                      │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Key Principles\n\n### ATDD Principles\n1. **Customer collaboration**: Acceptance criteria defined with stakeholders\n2. **Executable specifications**: Tests are specifications\n3. **Black-box testing**: Test from user perspective\n4. **Clear definition of done**: Acceptance criteria define completion\n\n### TDD Principles\n1. **Test first**: Always write test before code\n2. **Small steps**: Minimal tests, minimal code\n3. **Red-Green-Refactor**: Strict cycle discipline\n4. **Design emerges**: Let tests guide design\n5. **No premature optimization**: Simplest code that works\n6. **YAGNI**: You Aren't Gonna Need It\n\n## When to Use\n\n### Ideal For\n- **New features**: Well-defined requirements that need thorough testing\n- **API development**: Clear contracts that can be tested\n- **Business logic**: Complex rules that need validation\n- **Quality-critical code**: Systems where correctness is paramount\n- **Legacy refactoring**: Adding tests before modifying code\n\n### Works Well With\n- **BDD/Specification by Example**: ATDD scenarios come from BDD specifications\n- **Spec-Driven Development**: Acceptance criteria from specifications\n- **Continuous Integration**: Automated test execution\n- **Pair Programming**: Collaborative test writing and implementation\n\n### Less Suitable For\n- **Exploratory development**: Requirements unclear or rapidly changing\n- **Prototyping**: Quick experiments without long-term quality needs\n- **UI-heavy work**: Visual design exploration\n- **Performance optimization**: Focus on metrics rather than behavior\n\n## Usage\n\n### Basic Example\n\n```javascript\nimport { runProcess } from '@a5c-ai/babysitter-sdk';\n\nconst result = await runProcess('methodologies/atdd-tdd', {\n  feature: 'User authentication with JWT tokens',\n  acceptanceCriteria: [\n    'Users can register with email and password',\n    'Users can login and receive a JWT token',\n    'Invalid credentials are rejected',\n    'JWT tokens expire after 1 hour'\n  ],\n  testFramework: 'jest',\n  iterationCount: 15\n});\n```\n\n### Advanced Example with Integration Tests\n\n```javascript\nconst result = await runProcess('methodologies/atdd-tdd', {\n  feature: 'Shopping cart checkout process',\n  acceptanceCriteria: [\n    'Given a cart with items, when user checks out, then order is created',\n    'Given payment fails, when user checks out, then error is shown and cart preserved',\n    'Given inventory insufficient, when user checks out, then items are marked unavailable'\n  ],\n  testFramework: 'jest',\n  iterationCount: 20,\n  includeIntegrationTests: true,\n  existingCode: {\n    cartService: './src/services/cart.js',\n    paymentGateway: './src/gateways/payment.js',\n    inventoryService: './src/services/inventory.js'\n  }\n});\n\nconsole.log(`Feature: ${result.feature}`);\nconsole.log(`Success: ${result.success}`);\nconsole.log(`TDD Cycles: ${result.tddCycles.totalCycles}`);\nconsole.log(`Unit Tests: ${result.unitTests.totalTests}`);\nconsole.log(`Coverage: ${result.coverage.coverage}%`);\n```\n\n## Inputs\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `feature` | string | Yes | - | Feature or user story to implement |\n| `acceptanceCriteria` | array | No | `[]` | Pre-defined acceptance criteria (Given-When-Then format) |\n| `testFramework` | string | No | `'jest'` | Test framework to use (jest, mocha, vitest, etc.) |\n| `iterationCount` | number | No | `10` | Maximum TDD iterations before stopping |\n| `includeIntegrationTests` | boolean | No | `true` | Create integration tests after unit tests pass |\n| `existingCode` | object | No | `null` | Existing codebase context for integration |\n\n## Outputs\n\nThe process returns a comprehensive result object:\n\n```javascript\n{\n  success: boolean,                    // All acceptance tests passing\n  feature: string,                     // Feature name\n  testFramework: string,               // Test framework used\n\n  acceptanceCriteria: {\n    criteria: [],                      // Acceptance criteria definitions\n    scenarios: [],                     // Test scenarios\n    priorities: {}                     // Must-have, should-have, nice-to-have\n  },\n\n  acceptanceTests: {\n    tests: [],                         // Acceptance test cases\n    initialRun: {},                    // Initial test run (should fail)\n    finalRun: {},                      // Final test run (should pass)\n    allPassed: boolean                 // All acceptance tests passed\n  },\n\n  tddCycles: {\n    totalCycles: number,               // Number of Red-Green-Refactor cycles\n    cycles: [],                        // Detailed cycle information\n    completedSuccessfully: boolean     // Reached acceptance test success\n  },\n\n  unitTests: {\n    tests: [],                         // All unit tests created\n    totalTests: number                 // Count of unit tests\n  },\n\n  integrationTests: {                  // Optional\n    tests: [],                         // Integration test cases\n    results: {}                        // Integration test results\n  },\n\n  implementation: {\n    files: [],                         // Implementation files\n    totalFiles: number                 // Count of implementation files\n  },\n\n  coverage: {\n    coverage: number,                  // Overall coverage percentage\n    lineCoverage: number,              // Line coverage\n    branchCoverage: number,            // Branch coverage\n    filesCoverage: [],                 // Per-file coverage\n    gaps: [],                          // Coverage gaps\n    recommendations: []                // Coverage improvement recommendations\n  },\n\n  artifacts: {\n    acceptanceCriteria: string,        // Path to criteria document\n    acceptanceTests: string,           // Path to acceptance tests\n    unitTests: string,                 // Path to unit tests\n    integrationTests: string,          // Path to integration tests\n    implementation: string,            // Path to implementation\n    summary: string,                   // Path to summary\n    coverage: string                   // Path to coverage report\n  }\n}\n```\n\n## Tasks\n\nThe methodology uses these agent tasks:\n\n1. **defineAcceptanceCriteriaTask** - Define customer-facing acceptance criteria\n2. **createAcceptanceTestsTask** - Convert criteria to executable tests\n3. **runAcceptanceTestsTask** - Execute acceptance test suite\n4. **createUnitTestTask** - Write minimal failing unit test (Red)\n5. **implementCodeTask** - Write simplest code to pass test (Green)\n6. **refactorCodeTask** - Improve design while maintaining tests (Refactor)\n7. **runUnitTestsTask** - Execute unit test suite\n8. **createIntegrationTestsTask** - Create integration tests\n9. **runIntegrationTestsTask** - Execute integration tests\n10. **calculateCoverageTask** - Analyze test coverage metrics\n\n## Examples\n\nSee the `examples/` directory for sample inputs:\n\n- **examples/user-authentication.json** - JWT authentication feature\n- **examples/shopping-cart.json** - E-commerce cart checkout\n- **examples/file-upload.json** - File upload with validation\n- **examples/api-endpoint.json** - RESTful API endpoint\n\n## Test Frameworks Supported\n\n- **Jest** - JavaScript testing framework (default)\n- **Mocha** - Flexible JavaScript test framework\n- **Vitest** - Vite-native testing framework\n- **JUnit** - Java testing framework\n- **pytest** - Python testing framework\n- **RSpec** - Ruby testing framework\n\n## Benefits\n\n### ATDD Benefits\n- ✅ **Shared understanding** - Stakeholders, developers, testers align on requirements\n- ✅ **Living documentation** - Tests document expected behavior\n- ✅ **Early defect detection** - Issues found before implementation\n- ✅ **Customer confidence** - Tests validate from customer perspective\n\n### TDD Benefits\n- ✅ **Better design** - Tests drive modular, testable code\n- ✅ **Comprehensive tests** - High code coverage naturally\n- ✅ **Confidence to refactor** - Tests catch regressions\n- ✅ **Faster debugging** - Failing tests pinpoint issues\n- ✅ **Documentation** - Tests show how code should be used\n\n### Combined Benefits\n- ✅ **Two-layer quality** - External (right thing) + Internal (built right)\n- ✅ **Continuous validation** - Feedback at every level\n- ✅ **Traceability** - Unit tests trace to acceptance criteria\n- ✅ **Regression safety** - Comprehensive test suite\n\n## Best Practices\n\n### ATDD Best Practices\n1. **Collaborate early** - Involve stakeholders in criteria definition\n2. **Use Given-When-Then** - Clear scenario structure\n3. **Make criteria testable** - Specific, measurable outcomes\n4. **One criterion per test** - Independent, focused tests\n5. **Test from user perspective** - Black-box, behavior-focused\n\n### TDD Best Practices\n1. **Write minimal tests** - One assertion per test\n2. **Simplest code first** - No premature optimization\n3. **Refactor frequently** - Keep code clean continuously\n4. **Fast test execution** - Tests should run quickly\n5. **Independent tests** - No test interdependencies\n6. **Descriptive names** - Clear test intent from name\n\n### Red-Green-Refactor Discipline\n1. **Red**: Write test that fails (and fails for the right reason)\n2. **Green**: Make it pass with minimal code\n3. **Refactor**: Clean up while tests remain green\n4. **Never skip**: Follow cycle strictly\n\n## Integration Points\n\n- **BDD workflows** - Acceptance criteria from Gherkin scenarios\n- **Spec-Kit** - Constitution principles guide test quality\n- **CI/CD pipelines** - Automated test execution\n- **Code review** - Tests reviewed alongside implementation\n- **Documentation** - Tests serve as executable docs\n\n## Troubleshooting\n\n### Tests Pass Too Easily\n- **Symptom**: Tests pass without implementation\n- **Cause**: Tests not correctly written or feature already exists\n- **Solution**: Review test assertions, ensure testing actual behavior\n\n### Stuck in TDD Loop\n- **Symptom**: Many iterations without acceptance tests passing\n- **Cause**: Missing functionality or incorrect approach\n- **Solution**: Review acceptance criteria, consider different implementation strategy\n\n### Low Code Coverage\n- **Symptom**: Coverage below expected threshold\n- **Cause**: Edge cases not tested, error paths missed\n- **Solution**: Add tests for uncovered branches, boundary conditions\n\n### Refactoring Breaks Tests\n- **Symptom**: Tests fail after refactoring\n- **Cause**: Tests coupled to implementation details\n- **Solution**: Test behavior, not implementation; make tests more resilient\n\n## References\n\n### TDD\n- **Book**: \"Test Driven Development: By Example\" by Kent Beck\n- **Article**: [Wikipedia - Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development)\n- **Resource**: [TDD Best Practices](https://martinfowler.com/bliki/TestDrivenDevelopment.html)\n\n### ATDD\n- **Article**: [Wikipedia - Acceptance Test-Driven Development](https://en.wikipedia.org/wiki/Acceptance_test-driven_development)\n- **Resource**: [Agile Alliance - ATDD](https://agilealliance.org/glossary/atdd/)\n- **Article**: [TDD vs BDD vs ATDD](https://www.browserstack.com/guide/tdd-vs-bdd-vs-atdd)\n\n### Combined Resources\n- **Book**: \"Growing Object-Oriented Software, Guided by Tests\" by Steve Freeman & Nat Pryce\n- **Book**: \"ATDD by Example: A Practical Guide to Acceptance Test-Driven Development\" by Markus Gärtner\n- **Article**: [Outside-In TDD](https://www.thoughtworks.com/insights/blog/acceptance-test-driven-development-atdd-overview)\n\n## License\n\nPart of the Babysitter SDK Orchestration Framework.\n\n---\n\n**Created**: 2026-01-23\n**Version**: 1.0.0\n**Process ID**: `methodologies/atdd-tdd`\n",
    "documents": [
      "specialization:atdd-tdd"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-atdd-tdd",
      "to": "specialization:atdd-tdd",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-atdd-tdd",
      "kind": "contains_page"
    }
  ]
}