atdd 0.2.1__py3-none-any.whl

atdd/tester/validators/test_dual_ac_reference.py

@@ -0,0 +1,225 @@
+"""
+Test that Python test files have AC URN in BOTH header comment and docstring.
+
+Per RED convention v1.0+, tests MUST have AC URN in:
+1. Header comment: # URN: acc:...
+2. Module docstring: RED Test for acc:...
+
+This ensures:
+- Machine parseability (header comment)
+- Human readability (docstring)
+- Redundancy for validation
+"""
+
+import pytest
+import re
+from pathlib import Path
+
+
+# Path constants
+REPO_ROOT = Path(__file__).resolve().parents[4]
+PYTHON_DIR = REPO_ROOT / "python"
+
+
+def find_test_files() -> list:
+    """Find all Python test files."""
+    if not PYTHON_DIR.exists():
+        return []
+
+    test_files = []
+    for py_file in PYTHON_DIR.rglob("test_*.py"):
+        # Skip __pycache__ and conftest
+        if '__pycache__' in str(py_file) or 'conftest' in py_file.name:
+            continue
+        test_files.append(py_file)
+
+    return test_files
+
+
+def extract_ac_from_header(content: str) -> str | None:
+    """Extract AC URN from header comment."""
+    match = re.search(
+        r'^#\s*URN:\s*(acc:[a-z\-]+:[A-Z0-9]+-[A-Z0-9]+-\d{3}(?:-[a-z\-]+)?)',
+        content,
+        re.MULTILINE
+    )
+    return match.group(1) if match else None
+
+
+def extract_ac_from_docstring(content: str) -> str | None:
+    """Extract AC URN from module docstring."""
+    match = re.search(
+        r'^\s*""".*?(acc:[a-z\-]+:[A-Z0-9]+-[A-Z0-9]+-\d{3}(?:-[a-z\-]+)?)',
+        content,
+        re.DOTALL | re.MULTILINE
+    )
+    return match.group(1) if match else None
+
+
+@pytest.mark.platform
+def test_all_tests_have_dual_ac_references():
+    """
+    SPEC-TESTER-CONVENTION-0001: Test files MUST have AC URN in both header and docstring
+
+    Given: All Python test files
+    When: Checking for AC URN references
+    Then: Files MUST have AC URN in BOTH header comment AND module docstring
+          AND both references MUST match exactly
+    """
+    test_files = find_test_files()
+
+    if not test_files:
+        pytest.skip("No test files found")
+
+    errors = []
+    warnings = []
+
+    for test_file in test_files:
+        try:
+            with open(test_file, 'r', encoding='utf-8') as f:
+                content = f.read()
+        except Exception as e:
+            warnings.append(f"Could not read {test_file.relative_to(REPO_ROOT)}: {e}")
+            continue
+
+        ac_from_header = extract_ac_from_header(content)
+        ac_from_docstring = extract_ac_from_docstring(content)
+
+        rel_path = test_file.relative_to(REPO_ROOT)
+
+        # Check for presence
+        if not ac_from_header and not ac_from_docstring:
+            # Legacy test without AC URN - skip for now (will be migrated)
+            continue
+
+        if ac_from_header and not ac_from_docstring:
+            errors.append(
+                f"{rel_path}\n"
+                f"  ❌ MISSING: Module docstring with AC URN\n"
+                f"  Current state:\n"
+                f"    ✅ Header comment: {ac_from_header}\n"
+                f"    ❌ Module docstring: MISSING\n"
+                f"\n"
+                f"  ACTION REQUIRED: Add this module docstring after header comments:\n"
+                f'  """\n'
+                f'  RED Test for {ac_from_header}\n'
+                f'  wagon: {{wagon}} | feature: {{feature}} | phase: {{RED|GREEN|REFACTOR}}\n'
+                f'  WMBT: {{wmbt URN}}\n'
+                f'  Purpose: {{acceptance criteria purpose}}\n'
+                f'  """\n'
+            )
+
+        if ac_from_docstring and not ac_from_header:
+            errors.append(
+                f"{rel_path}\n"
+                f"  ❌ MISSING: Header comment with AC URN\n"
+                f"  Current state:\n"
+                f"    ❌ Header comment: MISSING\n"
+                f"    ✅ Module docstring: {ac_from_docstring}\n"
+                f"\n"
+                f"  ACTION REQUIRED: Add these lines at the top of the file:\n"
+                f"  # Runtime: {{python|supabase|dart}}\n"
+                f"  # Rationale: {{brief explanation}}\n"
+                f"  # URN: {ac_from_docstring}\n"
+                f"  # Phase: {{RED|GREEN|REFACTOR}}\n"
+                f"  # Purpose: {{acceptance criteria purpose}}\n"
+            )
+
+        # Check for match (allowing slugless to match slugged)
+        # Pattern: acc:wagon:WMBT-HARNESS-NNN[-optional-slug]
+        if ac_from_header and ac_from_docstring:
+            # Extract base URN (without slug) for comparison
+            # Pattern: acc:wagon:WMBT-HARNESS-NNN
+            base_pattern = r'(acc:[a-z\-]+:[A-Z0-9]+-[A-Z0-9]+-\d{3})'
+            header_base = re.match(base_pattern, ac_from_header)
+            docstring_base = re.match(base_pattern, ac_from_docstring)
+
+            if header_base and docstring_base:
+                # Compare base URNs (both URNs should have same wagon:WMBT-HARNESS-NNN)
+                if header_base.group(1) != docstring_base.group(1):
+                    errors.append(
+                        f"{rel_path}\n"
+                        f"  ❌ MISMATCH: Header and docstring reference different AC URNs\n"
+                        f"  Current state:\n"
+                        f"    Header comment: {ac_from_header}\n"
+                        f"    Module docstring: {ac_from_docstring}\n"
+                        f"\n"
+                        f"  ACTION REQUIRED: Both MUST reference the same AC URN\n"
+                        f"  Either:\n"
+                        f"    1. Update header to: # URN: {ac_from_docstring}\n"
+                        f"    OR\n"
+                        f"    2. Update docstring to: RED Test for {ac_from_header}\n"
+                        f"  (Choose the correct AC URN from plan/ acceptance criteria)"
+                    )
+
+    if warnings:
+        print("\n⚠️  WARNINGS:")
+        for warning in warnings:
+            print(f"  {warning}")
+
+    if errors:
+        # Categorize errors
+        missing_docstring = sum(1 for e in errors if "MISSING: Module docstring" in e)
+        missing_header = sum(1 for e in errors if "MISSING: Header comment" in e)
+        mismatched = sum(1 for e in errors if "MISMATCH:" in e)
+
+        error_report = "\n\n".join(errors)
+        pytest.fail(
+            f"\n\n"
+            f"══════════════════════════════════════════════════════════════════════\n"
+            f"❌ AC URN VALIDATION FAILED: {len(errors)} test files need updates\n"
+            f"══════════════════════════════════════════════════════════════════════\n"
+            f"\n"
+            f"BREAKDOWN:\n"
+            f"  • Missing docstring: {missing_docstring} files\n"
+            f"  • Missing header: {missing_header} files\n"
+            f"  • Mismatched URNs: {mismatched} files\n"
+            f"\n"
+            f"PER RED CONVENTION v1.0+, test files MUST have AC URN in BOTH:\n"
+            f"  1. Header comment: # URN: acc:...\n"
+            f"  2. Module docstring: RED Test for acc:...\n"
+            f"  AND both references MUST match exactly.\n"
+            f"\n"
+            f"══════════════════════════════════════════════════════════════════════\n"
+            f"DETAILED ERRORS:\n"
+            f"══════════════════════════════════════════════════════════════════════\n"
+            f"\n{error_report}\n"
+        )
+
+
+@pytest.mark.platform
+def test_dual_ac_reference_format_examples():
+    """
+    SPEC-TESTER-CONVENTION-0002: Document correct dual AC reference format
+
+    This test documents the expected format for dual AC references.
+    """
+    # This test always passes - it's documentation
+    correct_format = '''
+# Runtime: python
+# Rationale: Game mechanics - stateful timebank depletion algorithm
+# URN: acc:burn-timebank:E001-UNIT-001
+# Phase: GREEN
+# Purpose: Verify timebank decrements during active decision
+"""
+RED Test for acc:burn-timebank:E001-UNIT-001
+wagon: burn-timebank | feature: burn-time | phase: GREEN
+WMBT: wmbt:burn-timebank:E001
+Purpose: Verify timebank decrements during active decision
+"""
+
+import pytest
+
+
+def test_e001_unit_001_timebank_decrements_during_decision():
+    """Test implementation..."""
+    pass
+'''
+
+    # Validate the format
+    ac_from_header = extract_ac_from_header(correct_format)
+    ac_from_docstring = extract_ac_from_docstring(correct_format)
+
+    assert ac_from_header == "acc:burn-timebank:E001-UNIT-001"
+    assert ac_from_docstring == "acc:burn-timebank:E001-UNIT-001"
+    assert ac_from_header == ac_from_docstring

atdd/tester/validators/test_fixture_validity.py

@@ -0,0 +1,372 @@
+"""
+Test fixtures match contract schemas and are valid.
+
+Validates:
+- Test fixtures conform to contract schemas
+- Fixture data is realistic and valid
+- Fixtures cover edge cases
+- Fixtures are not hardcoded production data
+
+Inspired by: .claude/utils/tester/ (fixture utilities)
+But: Self-contained, no utility dependencies
+"""
+
+import pytest
+import json
+import yaml
+from pathlib import Path
+from typing import Dict, List, Any
+
+
+# Path constants
+REPO_ROOT = Path(__file__).resolve().parents[4]
+PYTHON_DIR = REPO_ROOT / "python"
+CONTRACTS_DIR = REPO_ROOT / "contracts"
+
+
+def find_contract_schemas() -> Dict[str, Dict]:
+    """
+    Find all contract schemas.
+
+    Returns:
+        Dict mapping contract ID to schema data
+    """
+    if not CONTRACTS_DIR.exists():
+        return {}
+
+    schemas = {}
+
+    for schema_file in CONTRACTS_DIR.rglob("*.schema.json"):
+        try:
+            with open(schema_file, 'r', encoding='utf-8') as f:
+                schema = json.load(f)
+
+            schema_id = schema.get('$id', str(schema_file.stem))
+            schemas[schema_id] = {
+                'schema': schema,
+                'file': str(schema_file.relative_to(REPO_ROOT))
+            }
+        except Exception:
+            continue
+
+    return schemas
+
+
+def find_test_fixtures() -> Dict[str, List[Any]]:
+    """
+    Find test fixtures in Python test files.
+
+    Returns:
+        Dict mapping fixture file to list of fixture data
+    """
+    if not PYTHON_DIR.exists():
+        return {}
+
+    fixtures = {}
+
+    # Look for fixture files (conftest.py, fixtures.py, etc.)
+    for test_dir in PYTHON_DIR.rglob("test"):
+        if not test_dir.is_dir():
+            continue
+
+        # Check conftest.py
+        conftest = test_dir / "conftest.py"
+        if conftest.exists():
+            fixture_data = extract_fixtures_from_file(conftest)
+            if fixture_data:
+                fixtures[str(conftest.relative_to(REPO_ROOT))] = fixture_data
+
+        # Check fixtures.py
+        fixtures_file = test_dir / "fixtures.py"
+        if fixtures_file.exists():
+            fixture_data = extract_fixtures_from_file(fixtures_file)
+            if fixture_data:
+                fixtures[str(fixtures_file.relative_to(REPO_ROOT))] = fixture_data
+
+        # Check fixtures/ directory
+        fixtures_dir = test_dir / "fixtures"
+        if fixtures_dir.exists() and fixtures_dir.is_dir():
+            for fixture_file in fixtures_dir.glob("*.json"):
+                try:
+                    with open(fixture_file, 'r', encoding='utf-8') as f:
+                        data = json.load(f)
+                    fixtures[str(fixture_file.relative_to(REPO_ROOT))] = [data]
+                except Exception:
+                    continue
+
+            for fixture_file in fixtures_dir.glob("*.yaml"):
+                try:
+                    with open(fixture_file, 'r', encoding='utf-8') as f:
+                        data = yaml.safe_load(f)
+                    fixtures[str(fixture_file.relative_to(REPO_ROOT))] = [data]
+                except Exception:
+                    continue
+
+    return fixtures
+
+
+def extract_fixtures_from_file(file_path: Path) -> List[Dict]:
+    """
+    Extract fixture data from Python file.
+
+    Returns:
+        List of fixture dictionaries found in file
+    """
+    # Simplified extraction - looks for dict literals
+    # In reality, would need AST parsing for complete extraction
+    fixtures = []
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except Exception:
+        return []
+
+    # Look for pytest fixtures that return dictionaries
+    # This is a simplified heuristic
+    import re
+
+    # Find @pytest.fixture decorated functions
+    fixture_pattern = r'@pytest\.fixture[^\n]*\ndef\s+(\w+)\([^)]*\):'
+    fixture_matches = re.finditer(fixture_pattern, content)
+
+    for match in fixture_matches:
+        fixture_name = match.group(1)
+        # Very simplified - just noting that fixtures exist
+        # Real implementation would extract actual data
+        fixtures.append({'fixture_name': fixture_name, 'type': 'pytest_fixture'})
+
+    return fixtures
+
+
+def validate_against_schema(data: Dict, schema: Dict) -> List[str]:
+    """
+    Validate data against JSON schema.
+
+    Returns:
+        List of validation errors (empty if valid)
+    """
+    errors = []
+
+    # Check required fields
+    required = schema.get('required', [])
+    for field in required:
+        if field not in data:
+            errors.append(f"Missing required field: {field}")
+
+    # Check property types
+    properties = schema.get('properties', {})
+    for field, value in data.items():
+        if field in properties:
+            expected_type = properties[field].get('type')
+            actual_type = type(value).__name__
+
+            # Map Python types to JSON schema types
+            type_map = {
+                'str': 'string',
+                'int': 'integer',
+                'float': 'number',
+                'bool': 'boolean',
+                'list': 'array',
+                'dict': 'object',
+                'NoneType': 'null'
+            }
+
+            json_type = type_map.get(actual_type, actual_type)
+
+            if expected_type and json_type != expected_type:
+                errors.append(
+                    f"Field '{field}' has type '{json_type}', expected '{expected_type}'"
+                )
+
+    return errors
+
+
+def check_for_suspicious_data(data: Any) -> List[str]:
+    """
+    Check fixture data for suspicious patterns.
+
+    Returns:
+        List of warnings about suspicious data
+    """
+    warnings = []
+
+    if isinstance(data, dict):
+        for key, value in data.items():
+            # Check for potential production data patterns
+            if isinstance(value, str):
+                # Email addresses (might be real)
+                if '@' in value and '.' in value and 'example.com' not in value and 'test.com' not in value:
+                    warnings.append(f"Field '{key}' contains real-looking email: {value}")
+
+                # Phone numbers (might be real)
+                if len(value.replace('-', '').replace(' ', '').replace('(', '').replace(')', '')) == 10 and value.replace('-', '').replace(' ', '').replace('(', '').replace(')', '').isdigit():
+                    warnings.append(f"Field '{key}' contains real-looking phone number")
+
+                # Hardcoded IDs (should be generated)
+                if key.endswith('_id') and value == value and not value.startswith('test-') and not value.startswith('fixture-'):
+                    warnings.append(f"Field '{key}' has hardcoded ID (should be generated)")
+
+            # Recursive check for nested dicts
+            if isinstance(value, dict):
+                warnings.extend(check_for_suspicious_data(value))
+
+            if isinstance(value, list):
+                for item in value:
+                    if isinstance(item, dict):
+                        warnings.extend(check_for_suspicious_data(item))
+
+    return warnings
+
+
+@pytest.mark.tester
+def test_fixtures_match_contract_schemas():
+    """
+    SPEC-TESTER-FIXTURE-0001: Test fixtures conform to contract schemas.
+
+    Fixtures should match the structure defined in contracts.
+    This ensures tests use realistic, valid data.
+
+    Given: Test fixtures and contract schemas
+    When: Validating fixture data against schemas
+    Then: All fixtures conform to their schemas
+    """
+    schemas = find_contract_schemas()
+    fixtures = find_test_fixtures()
+
+    if not schemas:
+        pytest.skip("No contract schemas found")
+
+    if not fixtures:
+        pytest.skip("No test fixtures found")
+
+    violations = []
+
+    # For each fixture, try to find matching schema
+    for fixture_file, fixture_data_list in fixtures.items():
+        for fixture_data in fixture_data_list:
+            if not isinstance(fixture_data, dict):
+                continue
+
+            # Skip pytest fixture metadata entries - they're not actual data
+            if fixture_data.get('type') == 'pytest_fixture':
+                continue
+
+            # Only validate fixtures that have an explicit schema reference
+            # via $schema or schema_ref field
+            schema_ref = fixture_data.get('$schema') or fixture_data.get('schema_ref')
+            if not schema_ref:
+                continue
+
+            # Find matching schema
+            if schema_ref in schemas:
+                errors = validate_against_schema(fixture_data, schemas[schema_ref]['schema'])
+
+                if errors:
+                    violations.append(
+                        f"{fixture_file}\\n"
+                        f"  Schema: {schema_ref}\\n"
+                        f"  Errors: {', '.join(errors[:3])}"
+                    )
+
+    if violations:
+        pytest.fail(
+            f"\\n\\nFound {len(violations)} fixture validation errors:\\n\\n" +
+            "\\n\\n".join(violations[:10]) +
+            (f"\\n\\n... and {len(violations) - 10} more" if len(violations) > 10 else "")
+        )
+
+
+@pytest.mark.tester
+def test_fixtures_do_not_contain_production_data():
+    """
+    SPEC-TESTER-FIXTURE-0002: Fixtures don't contain production data.
+
+    Test fixtures should use fake/generated data, not real production data.
+
+    Patterns to avoid:
+    - Real email addresses
+    - Real phone numbers
+    - Production API keys
+    - Actual user names
+
+    Given: Test fixtures
+    When: Scanning for production data patterns
+    Then: No production data found
+    """
+    fixtures = find_test_fixtures()
+
+    if not fixtures:
+        pytest.skip("No test fixtures found")
+
+    violations = []
+
+    for fixture_file, fixture_data_list in fixtures.items():
+        for fixture_data in fixture_data_list:
+            warnings = check_for_suspicious_data(fixture_data)
+
+            if warnings:
+                violations.append(
+                    f"{fixture_file}\\n" +
+                    "\\n".join(f"  - {w}" for w in warnings[:5])
+                )
+
+    if violations:
+        pytest.fail(
+            f"\\n\\nFound {len(violations)} fixtures with suspicious data:\\n\\n" +
+            "\\n\\n".join(violations[:10]) +
+            (f"\\n\\n... and {len(violations) - 10} more" if len(violations) > 10 else "") +
+            "\\n\\nFixtures should use clearly fake/test data (example.com, test-, etc.)"
+        )
+
+
+@pytest.mark.tester
+def test_fixtures_use_descriptive_names():
+    """
+    SPEC-TESTER-FIXTURE-0003: Fixtures have descriptive names.
+
+    Fixture names should clearly indicate what they provide.
+
+    Good: valid_user_fixture, invalid_email_fixture
+    Bad: data, test_data, fixture1
+
+    Given: Test fixtures
+    When: Checking fixture names
+    Then: Names are descriptive and follow conventions
+    """
+    fixtures = find_test_fixtures()
+
+    if not fixtures:
+        pytest.skip("No test fixtures found")
+
+    violations = []
+
+    for fixture_file, fixture_data_list in fixtures.items():
+        for fixture_data in fixture_data_list:
+            if isinstance(fixture_data, dict) and 'fixture_name' in fixture_data:
+                name = fixture_data['fixture_name']
+
+                # Check for bad names
+                bad_patterns = ['data', 'test', 'fixture1', 'fixture2', 'tmp', 'temp']
+
+                if name.lower() in bad_patterns:
+                    violations.append(
+                        f"{fixture_file}\\n"
+                        f"  Fixture: {name}\\n"
+                        f"  Issue: Name too generic, should be descriptive"
+                    )
+
+                # Check if name is too short
+                if len(name) < 5:
+                    violations.append(
+                        f"{fixture_file}\\n"
+                        f"  Fixture: {name}\\n"
+                        f"  Issue: Name too short (should be descriptive)"
+                    )
+
+    if violations:
+        pytest.fail(
+            f"\\n\\nFound {len(violations)} fixture naming violations:\\n\\n" +
+            "\\n\\n".join(violations[:10]) +
+            (f"\\n\\n... and {len(violations) - 10} more" if len(violations) > 10 else "")
+        )