@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/tdd-guide/README.md

@@ -0,0 +1,680 @@
+# TDD Guide - Test Driven Development Skill
+
+**Version**: 1.0.0
+**Last Updated**: November 5, 2025
+**Author**: Claude Skills Factory
+
+A comprehensive Test Driven Development skill for Claude Code that provides intelligent test generation, coverage analysis, framework integration, and TDD workflow guidance across multiple languages and testing frameworks.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Python Modules](#python-modules)
+- [Usage Examples](#usage-examples)
+- [Configuration](#configuration)
+- [Supported Frameworks](#supported-frameworks)
+- [Output Formats](#output-formats)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Overview
+
+The TDD Guide skill transforms how engineering teams implement Test Driven Development by providing:
+
+- **Intelligent Test Generation**: Convert requirements into executable test cases
+- **Coverage Analysis**: Parse LCOV, JSON, XML reports and identify gaps
+- **Multi-Framework Support**: Jest, Pytest, JUnit, Vitest, and more
+- **TDD Workflow Guidance**: Step-by-step red-green-refactor guidance
+- **Quality Metrics**: Comprehensive test and code quality analysis
+- **Context-Aware Output**: Optimized for Desktop, CLI, or API usage
+
+## Features
+
+### Test Generation (3 capabilities)
+1. **Generate Test Cases from Requirements** - User stories → Test cases
+2. **Create Test Stubs** - Proper scaffolding with framework patterns
+3. **Generate Test Fixtures** - Realistic test data and boundary values
+
+### TDD Workflow (3 capabilities)
+1. **Red-Green-Refactor Guidance** - Phase-by-phase validation
+2. **Suggest Missing Scenarios** - Identify untested edge cases
+3. **Review Test Quality** - Isolation, assertions, naming analysis
+
+### Coverage & Metrics (6 categories)
+1. **Test Coverage** - Line/branch/function with gap analysis
+2. **Code Complexity** - Cyclomatic/cognitive complexity
+3. **Test Quality** - Assertions, isolation, naming scoring
+4. **Test Data** - Boundary values, edge cases
+5. **Test Execution** - Timing, slow tests, flakiness
+6. **Missing Tests** - Uncovered paths and error handlers
+
+### Framework Integration (4 capabilities)
+1. **Multi-Framework Adapters** - Jest, Pytest, JUnit, Vitest, Mocha
+2. **Generate Boilerplate** - Proper imports and test structure
+3. **Configure Runners** - Setup and coverage configuration
+4. **Framework Detection** - Automatic framework identification
+
+## Installation
+
+### Claude Code (Desktop)
+
+1. **Download the skill folder**:
+   ```bash
+   # Option A: Clone from repository
+   git clone https://github.com/your-org/tdd-guide-skill.git
+
+   # Option B: Download ZIP and extract
+   ```
+
+2. **Install to Claude skills directory**:
+   ```bash
+   # Project-level (recommended for team projects)
+   cp -r tdd-guide /path/to/your/project/.claude/skills/
+
+   # User-level (available for all projects)
+   cp -r tdd-guide ~/.claude/skills/
+   ```
+
+3. **Verify installation**:
+   ```bash
+   ls ~/.claude/skills/tdd-guide/
+   # Should show: SKILL.md, *.py files, samples
+   ```
+
+### Claude Apps (Browser)
+
+1. Use the `skill-creator` skill to import the ZIP file
+2. Or manually upload files through the skills interface
+
+### Claude API
+
+```python
+# Upload skill via API
+import anthropic
+
+client = anthropic.Anthropic(api_key="your-api-key")
+
+# Create skill with files
+skill = client.skills.create(
+    name="tdd-guide",
+    files=["tdd-guide/SKILL.md", "tdd-guide/*.py"]
+)
+```
+
+## Quick Start
+
+### 1. Generate Tests from Requirements
+
+```
+@tdd-guide
+
+Generate tests for password validation function:
+- Min 8 characters
+- At least 1 uppercase, 1 lowercase, 1 number, 1 special char
+
+Language: TypeScript
+Framework: Jest
+```
+
+### 2. Analyze Coverage
+
+```
+@tdd-guide
+
+Analyze coverage from: coverage/lcov.info
+Target: 80% coverage
+Prioritize recommendations
+```
+
+### 3. TDD Workflow
+
+```
+@tdd-guide
+
+Guide me through TDD for implementing user authentication.
+
+Requirements: Email/password login, session management
+Framework: Pytest
+```
+
+## Python Modules
+
+The skill includes **8 Python modules** organized by functionality:
+
+### Core Modules (7 files)
+
+1. **test_generator.py** (450 lines)
+   - Generate test cases from requirements
+   - Create test stubs with proper structure
+   - Suggest missing scenarios based on code analysis
+   - Support for multiple test types (unit, integration, e2e)
+
+2. **coverage_analyzer.py** (380 lines)
+   - Parse LCOV, JSON, XML coverage reports
+   - Calculate line/branch/function coverage
+   - Identify coverage gaps with prioritization
+   - Generate actionable recommendations
+
+3. **metrics_calculator.py** (420 lines)
+   - Cyclomatic and cognitive complexity analysis
+   - Test quality scoring (isolation, assertions, naming)
+   - Test smell detection
+   - Execution metrics analysis
+
+4. **framework_adapter.py** (480 lines)
+   - Multi-framework adapters (Jest, Pytest, JUnit, Vitest, Mocha)
+   - Generate framework-specific imports and structure
+   - Assertion syntax translation
+   - Setup/teardown hook generation
+
+5. **tdd_workflow.py** (380 lines)
+   - Red-Green-Refactor phase guidance
+   - Phase validation and progression
+   - Refactoring suggestions
+   - Workflow state management
+
+6. **fixture_generator.py** (340 lines)
+   - Boundary value generation
+   - Edge case scenario creation
+   - Mock data generation from schemas
+   - Fixture file export (JSON, YAML, Python)
+
+7. **format_detector.py** (280 lines)
+   - Automatic language detection
+   - Testing framework identification
+   - Coverage format detection
+   - Project structure analysis
+
+### Utility Modules (1 file)
+
+8. **output_formatter.py** (260 lines)
+   - Context-aware formatting (Desktop, CLI, API)
+   - Progressive disclosure
+   - Token-efficient reporting
+   - Summary and detailed views
+
+### Total Lines of Code
+- **Python**: ~3,400 lines
+- **Documentation**: ~1,200 lines
+- **Samples**: ~200 lines
+- **Total**: ~4,400 lines
+
+## Usage Examples
+
+### Example 1: Generate Tests from User Story
+
+**Input**:
+```
+@tdd-guide
+
+User Story: As a user, I want to add items to my shopping cart
+
+Acceptance Criteria:
+- Add single item with quantity
+- Update quantity if item already exists
+- Validate quantity is positive
+- Return updated cart total
+
+Language: Python
+Framework: Pytest
+```
+
+**Output**:
+```python
+import pytest
+from shopping_cart import ShoppingCart
+
+class TestShoppingCart:
+    """Test suite for shopping cart functionality."""
+
+    def test_add_single_item_successfully(self):
+        """Should add single item with quantity."""
+        cart = ShoppingCart()
+        cart.add_item('apple', quantity=3, price=1.50)
+
+        assert len(cart.items) == 1
+        assert cart.items['apple']['quantity'] == 3
+        assert cart.get_total() == 4.50
+
+    def test_update_quantity_for_existing_item(self):
+        """Should update quantity if item already exists."""
+        cart = ShoppingCart()
+        cart.add_item('apple', quantity=3, price=1.50)
+        cart.add_item('apple', quantity=2, price=1.50)
+
+        assert cart.items['apple']['quantity'] == 5
+        assert cart.get_total() == 7.50
+
+    def test_reject_negative_quantity(self):
+        """Should validate quantity is positive."""
+        cart = ShoppingCart()
+
+        with pytest.raises(ValueError, match="Quantity must be positive"):
+            cart.add_item('apple', quantity=-1, price=1.50)
+```
+
+### Example 2: Coverage Analysis with Recommendations
+
+**Input**:
+```
+@tdd-guide
+
+Analyze coverage:
+
+[Coverage report data]
+SF:src/auth/login.ts
+DA:1,5
+DA:2,5
+DA:3,3
+DA:4,0
+DA:5,0
+...
+
+Target: 80% coverage
+```
+
+**Output**:
+```markdown
+## Coverage Summary
+
+- Line Coverage: 65.0%
+- Branch Coverage: 58.3%
+- Function Coverage: 75.0%
+
+⚠️ **65.0%** coverage (yellow) - Below 80% threshold
+
+## Recommendations
+
+### 🔴 Critical (P0)
+
+1. **Error handling paths not covered**
+   - Action: Add tests for authentication failure scenarios
+   - File: `src/auth/login.ts`
+   - Lines: 45-52, 67-70
+
+2. **Branch coverage gap in validation**
+   - Action: Test all conditional branches in input validation
+   - File: `src/auth/login.ts`
+   - Lines: 23-28
+
+### 🟡 Important (P1)
+
+1. **Edge cases missing**
+   - Action: Add boundary tests for password length (7, 8, 9 chars)
+   - Impact: Medium
+```
+
+### Example 3: TDD Red-Green-Refactor Guidance
+
+**Input**:
+```
+@tdd-guide
+
+Guide TDD for email validation.
+
+Requirement: Email must contain @ and valid domain
+
+Phase: RED (write failing test)
+```
+
+**Output**:
+```markdown
+## TDD Phase: RED
+
+### Goal
+Write a failing test that describes desired email validation behavior
+
+### Steps
+1. ✅ Read requirement: Email must contain @ and valid domain
+2. ✅ Think about expected behavior
+3. ⏳ Write test that verifies this behavior
+4. ⏳ Run test and ensure it fails
+5. ⏳ Verify failure reason is correct (not syntax error)
+
+### Test Template (Jest)
+
+```typescript
+describe('EmailValidator', () => {
+  it('should accept valid email format', () => {
+    // Arrange
+    const validator = new EmailValidator();
+
+    // Act
+    const result = validator.validate('user@example.com');
+
+    // Assert
+    expect(result).toBe(true);
+  });
+
+  it('should reject email without @ symbol', () => {
+    const validator = new EmailValidator();
+    const result = validator.validate('userexample.com');
+    expect(result).toBe(false);
+  });
+});
+```
+
+### Next Steps
+1. Run the test (it should fail)
+2. Verify failure: "EmailValidator is not defined" or similar
+3. Share test result to proceed to GREEN phase
+```
+
+### Example 4: Test Quality Review
+
+**Input**:
+```
+@tdd-guide
+
+Review test quality:
+
+def test_user_login():
+    result = login("admin", "password123")
+    assert result
+    assert result["status"] == "success"
+    assert result["token"]
+    assert result["user"]["id"] > 0
+    assert result["user"]["role"] == "admin"
+```
+
+**Output**:
+```markdown
+## Test Quality Analysis
+
+**Overall Score**: 62/100
+
+### Issues Detected
+
+1. **Assertion Roulette** (High Severity)
+   - 5 assertions in single test
+   - **Fix**: Split into multiple focused tests
+
+2. **Poor Test Isolation** (Medium Severity)
+   - Test depends on database state ("admin" user existing)
+   - **Fix**: Use fixtures or mocks for user data
+
+3. **Weak Assertions** (Medium Severity)
+   - `assert result["token"]` just checks truthy (could be any string)
+   - **Fix**: `assert len(result["token"]) > 20` or use regex
+
+4. **Missing Naming Context** (Low Severity)
+   - Test name doesn't describe what's being tested
+   - **Fix**: `test_successful_login_returns_valid_token_and_user_data`
+
+### Recommended Refactoring
+
+```python
+@pytest.fixture
+def admin_user():
+    return {"username": "admin", "password": "password123"}
+
+def test_successful_login_returns_success_status(admin_user):
+    """Test that valid credentials return success status."""
+    result = login(admin_user["username"], admin_user["password"])
+    assert result["status"] == "success"
+
+def test_successful_login_returns_valid_jwt_token(admin_user):
+    """Test that successful login returns a JWT token."""
+    result = login(admin_user["username"], admin_user["password"])
+    assert len(result["token"]) > 20
+    assert result["token"].count('.') == 2  # JWT format
+
+def test_successful_login_returns_user_data(admin_user):
+    """Test that successful login includes user information."""
+    result = login(admin_user["username"], admin_user["password"])
+    assert result["user"]["id"] > 0
+    assert result["user"]["role"] == "admin"
+```
+
+### Quality Improvements
+- Isolation Score: 55 → 90 (with fixtures)
+- Naming Quality: 40 → 85 (descriptive names)
+- Test Focus: 30 → 95 (one assertion per test)
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Set preferred testing framework
+export TDD_DEFAULT_FRAMEWORK="jest"
+
+# Set coverage threshold
+export TDD_COVERAGE_THRESHOLD=80
+
+# Set output verbosity
+export TDD_VERBOSE=true
+
+# Set output format
+export TDD_OUTPUT_FORMAT="markdown"  # or "json", "terminal"
+```
+
+### Skill Configuration (Optional)
+
+Create `.tdd-guide.json` in project root:
+
+```json
+{
+  "framework": "jest",
+  "language": "typescript",
+  "coverage_threshold": 80,
+  "test_directory": "tests/",
+  "quality_rules": {
+    "max_assertions_per_test": 3,
+    "require_descriptive_names": true,
+    "enforce_isolation": true
+  },
+  "output": {
+    "format": "markdown",
+    "verbose": false,
+    "max_recommendations": 10
+  }
+}
+```
+
+## Supported Frameworks
+
+### JavaScript/TypeScript
+- **Jest** 29+ (recommended for React, Node.js)
+- **Vitest** 0.34+ (recommended for Vite projects)
+- **Mocha** 10+ with Chai
+- **Jasmine** 4+
+
+### Python
+- **Pytest** 7+ (recommended)
+- **unittest** (Python standard library)
+- **nose2** 0.12+
+
+### Java
+- **JUnit 5** 5.9+ (recommended)
+- **TestNG** 7+
+- **Mockito** 5+ (mocking support)
+
+### Coverage Tools
+- **Istanbul/nyc** (JavaScript)
+- **c8** (JavaScript, V8 native)
+- **coverage.py** (Python)
+- **pytest-cov** (Python)
+- **JaCoCo** (Java)
+- **Cobertura** (multi-language)
+
+## Output Formats
+
+### Markdown (Claude Desktop)
+- Rich formatting with headers, tables, code blocks
+- Visual indicators (✅, ⚠️, ❌)
+- Progressive disclosure (summary first, details on demand)
+- Syntax highlighting for code examples
+
+### Terminal (Claude Code CLI)
+- Concise, text-based output
+- Clear section separators
+- Minimal formatting for readability
+- Quick scanning for key information
+
+### JSON (API/CI Integration)
+- Structured data for automated processing
+- Machine-readable metrics
+- Suitable for CI/CD pipelines
+- Easy integration with other tools
+
+## Best Practices
+
+### Test Generation
+1. **Start with requirements** - Clear specs lead to better tests
+2. **Cover the happy path first** - Then add error and edge cases
+3. **One behavior per test** - Focused tests are easier to maintain
+4. **Use descriptive names** - Tests are documentation
+
+### Coverage Analysis
+1. **Aim for 80%+ coverage** - Balance between safety and effort
+2. **Prioritize critical paths** - Not all code needs 100% coverage
+3. **Branch coverage matters** - Line coverage alone is insufficient
+4. **Track trends** - Coverage should improve over time
+
+### TDD Workflow
+1. **Small iterations** - Write one test, make it pass, refactor
+2. **Run tests frequently** - Fast feedback loop is essential
+3. **Commit often** - Each green phase is a safe checkpoint
+4. **Refactor with confidence** - Tests are your safety net
+
+### Test Quality
+1. **Isolate tests** - No shared state between tests
+2. **Fast execution** - Unit tests should be <100ms each
+3. **Deterministic** - Same input always produces same output
+4. **Clear failures** - Good error messages save debugging time
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Generated tests have wrong syntax for my framework
+```
+Solution: Explicitly specify framework
+Example: "Generate tests using Pytest" or "Framework: Jest"
+```
+
+**Issue**: Coverage report not recognized
+```
+Solution: Verify format (LCOV, JSON, XML)
+Try: Paste raw coverage data instead of file path
+Check: File exists and is readable
+```
+
+**Issue**: Too many recommendations, overwhelmed
+```
+Solution: Ask for prioritized output
+Example: "Show only P0 (critical) recommendations"
+Limit: "Top 5 recommendations only"
+```
+
+**Issue**: Test quality score seems wrong
+```
+Check: Ensure complete test context (setup/teardown included)
+Verify: Test file contains actual test code, not just stubs
+Context: Quality depends on isolation, assertions, naming
+```
+
+**Issue**: Framework detection incorrect
+```
+Solution: Specify framework explicitly
+Example: "Using JUnit 5" or "Framework: Vitest"
+Check: Ensure imports are present in code
+```
+
+## File Structure
+
+```
+tdd-guide/
+├── SKILL.md                          # Skill definition (YAML + documentation)
+├── README.md                         # This file
+├── HOW_TO_USE.md                     # Usage examples
+│
+├── test_generator.py                 # Test generation core
+├── coverage_analyzer.py              # Coverage parsing and analysis
+├── metrics_calculator.py             # Quality metrics calculation
+├── framework_adapter.py              # Multi-framework support
+├── tdd_workflow.py                   # Red-green-refactor guidance
+├── fixture_generator.py              # Test data and fixtures
+├── format_detector.py                # Automatic format detection
+├── output_formatter.py               # Context-aware output
+│
+├── sample_input_typescript.json      # TypeScript example
+├── sample_input_python.json          # Python example
+├── sample_coverage_report.lcov       # LCOV coverage example
+└── expected_output.json              # Expected output structure
+```
+
+## Contributing
+
+We welcome contributions! To contribute:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/improvement`)
+3. Make your changes
+4. Add tests for new functionality
+5. Run validation: `python -m pytest tests/`
+6. Commit changes (`git commit -m "Add: feature description"`)
+7. Push to branch (`git push origin feature/improvement`)
+8. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Clone repository
+git clone https://github.com/your-org/tdd-guide-skill.git
+cd tdd-guide-skill
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest tests/ -v
+
+# Run linter
+pylint *.py
+
+# Run type checker
+mypy *.py
+```
+
+## Version History
+
+### v1.0.0 (November 5, 2025)
+- Initial release
+- Support for TypeScript, JavaScript, Python, Java
+- Jest, Pytest, JUnit, Vitest framework adapters
+- LCOV, JSON, XML coverage parsing
+- TDD workflow guidance (red-green-refactor)
+- Test quality metrics and analysis
+- Context-aware output formatting
+- Comprehensive documentation
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Support
+
+- **Documentation**: See HOW_TO_USE.md for detailed examples
+- **Issues**: Report bugs via GitHub issues
+- **Questions**: Ask in Claude Code community forum
+- **Updates**: Check repository for latest version
+
+## Acknowledgments
+
+Built with Claude Skills Factory toolkit, following Test Driven Development best practices and informed by:
+- Kent Beck's "Test Driven Development: By Example"
+- Martin Fowler's refactoring catalog
+- xUnit Test Patterns by Gerard Meszaros
+- Growing Object-Oriented Software, Guided by Tests
+
+---
+
+**Ready to improve your testing workflow?** Install the TDD Guide skill and start generating high-quality tests today!