pmat 3.16.0

PMAT - Zero-config AI context generation and code quality toolkit (CLI, MCP, HTTP)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111

# Property-Based Testing Guide

*Reference: SPECIFICATION.md Section 28*

## Overview

PMAT employs comprehensive property-based testing using the `proptest` framework to ensure correctness across a wide range of inputs. This guide documents our property testing approach and standards.

## Core Properties

### 1. Complexity Analysis Properties

Tests verify that complexity metrics are:
- **Deterministic**: Same input always produces same complexity score
- **Monotonic**: Adding complexity increases scores
- **Bounded**: Scores stay within expected ranges (0-100 for most metrics)

Reference implementation: `src/tests/property_tests.rs`

### 2. SATD Detection Properties

Properties ensure SATD detection:
- **Completeness**: All known patterns are detected
- **Accuracy**: No false positives for clean code
- **Stability**: Detection is consistent across runs

### 3. Refactoring Properties

Critical properties for refactoring:
- **Semantic Preservation**: Refactored code maintains behavior
- **Quality Improvement**: Complexity decreases or stays same
- **Syntactic Validity**: Output is valid Rust code

## Test Strategy

### Input Generation

```rust
proptest! {
    #[test]
    fn test_complexity_bounds(
        code in any::<String>().prop_filter("valid rust", |s| s.len() < 10000)
    ) {
        let complexity = analyze_complexity(&code);
        prop_assert!(complexity.cyclomatic >= 0);
        prop_assert!(complexity.cyclomatic <= 1000);
    }
}
```

### Shrinking

When a property fails, proptest automatically shrinks the input to find minimal failing case:
- Start with complex input that fails
- Systematically reduce complexity
- Find simplest input that still fails

### Coverage

Property tests cover:
- **64+ core properties** across all major components
- **10,000+ test cases** per property by default
- **Edge cases** through targeted generators

## Running Property Tests

```bash
# Run all property tests
make test-property

# Run with more iterations (slower but more thorough)
PROPTEST_CASES=100000 cargo test --test property

# Run specific property test
cargo test --test property test_complexity_bounds
```

## Writing New Properties

Follow these patterns when adding property tests:

1. **Define the property clearly**
   - What invariant should hold?
   - What are the bounds?

2. **Generate appropriate inputs**
   - Use custom generators for domain types
   - Apply filters for valid inputs

3. **Assert the property**
   - Check invariants hold
   - Verify postconditions

4. **Document the property**
   - Explain what it tests
   - Reference specification section

## Integration with CI

Property tests run in CI with:
- Standard iteration count for PR checks
- Extended iteration count for nightly builds
- Seed fixation for reproducibility

See `.github/workflows/test.yml` for configuration.

## Related Documentation

- [Integration Testing](./integration.md)
- [Performance Testing](./performance.md)
- [SPECIFICATION.md Section 28](../SPECIFICATION.md#28-property-based-testing)