|
| 1 | +# PHPStan Development Utilities |
| 2 | + |
| 3 | +Development utilities for PHPStan rules testing, extracted from [shipmonk/phpstan-rules](https://github.com/shipmonk-rnd/phpstan-rules). |
| 4 | + |
| 5 | +This package provides the `RuleTestCase` class - an enhanced testing framework specifically designed for testing PHPStan rules with additional validation and convenience features. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +```bash |
| 10 | +composer require --dev shipmonk/phpstan-dev |
| 11 | +``` |
| 12 | + |
| 13 | +## Quick Start |
| 14 | + |
| 15 | +### 1. Create Your Rule Test Class |
| 16 | + |
| 17 | +```php |
| 18 | +<?php declare(strict_types = 1); |
| 19 | + |
| 20 | +namespace YourNamespace; |
| 21 | + |
| 22 | +use ShipMonk\PHPStanDev\RuleTestCase; |
| 23 | +use PHPStan\Rules\Rule; |
| 24 | + |
| 25 | +/** |
| 26 | + * @extends RuleTestCase<YourRule> |
| 27 | + */ |
| 28 | +class YourRuleTest extends RuleTestCase |
| 29 | +{ |
| 30 | + protected function getRule(): Rule |
| 31 | + { |
| 32 | + return new YourRule(); |
| 33 | + } |
| 34 | + |
| 35 | + public function testRule(): void |
| 36 | + { |
| 37 | + $this->analyzeFiles([__DIR__ . '/Data/YourRule/code.php']); |
| 38 | + } |
| 39 | +} |
| 40 | +``` |
| 41 | + |
| 42 | +### 2. Create Test Data File |
| 43 | + |
| 44 | +Create `tests/Rule/Data/YourRule/code.php`: |
| 45 | + |
| 46 | +```php |
| 47 | +<?php declare(strict_types = 1); |
| 48 | + |
| 49 | +namespace YourRule; |
| 50 | + |
| 51 | +function test() { |
| 52 | + $valid = 'This is valid code'; |
| 53 | + $invalid = something(); // error: Your custom error message here |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +### 3. Run Your Test |
| 58 | + |
| 59 | +```bash |
| 60 | +vendor/bin/phpunit tests/Rule/YourRuleTest.php |
| 61 | +``` |
| 62 | + |
| 63 | +## Key Features |
| 64 | + |
| 65 | +### 🎯 Error Comment System |
| 66 | + |
| 67 | +Use `// error: <message>` comments in test files to specify expected errors: |
| 68 | + |
| 69 | +```php |
| 70 | +<?php |
| 71 | + |
| 72 | +$validCode = 'No error expected here'; |
| 73 | +$invalidCode = forbidden(); // error: This is forbidden |
| 74 | +$alsoInvalid = another(); // error: Another error message |
| 75 | +``` |
| 76 | + |
| 77 | +### 🔧 Autofix Mode |
| 78 | + |
| 79 | +During development, automatically generate error comments: |
| 80 | + |
| 81 | +```php |
| 82 | +public function testRule(): void |
| 83 | +{ |
| 84 | + // Set to true temporarily to generate error comments |
| 85 | + $this->analyzeFiles([__DIR__ . '/Data/code.php'], autofix: true); |
| 86 | +} |
| 87 | +``` |
| 88 | + |
| 89 | +**⚠️ Important**: Remove `autofix: true` before committing - tests will fail if autofix is enabled. |
| 90 | + |
| 91 | +### 🛡️ Automatic Error Validation |
| 92 | + |
| 93 | +Every error is automatically validated: |
| 94 | +- ✅ Must have an identifier |
| 95 | +- ✅ Errors are matched to specific line numbers |
| 96 | + |
| 97 | +## Advanced Usage |
| 98 | + |
| 99 | +### Multiple Test Scenarios |
| 100 | + |
| 101 | +```php |
| 102 | +class ComplexRuleTest extends RuleTestCase |
| 103 | +{ |
| 104 | + private bool $strictMode = false; |
| 105 | + |
| 106 | + protected function getRule(): Rule |
| 107 | + { |
| 108 | + return new ComplexRule($this->strictMode); |
| 109 | + } |
| 110 | + |
| 111 | + public function testDefault(): void |
| 112 | + { |
| 113 | + $this->analyzeFiles([__DIR__ . '/Data/ComplexRule/default.php']); |
| 114 | + } |
| 115 | + |
| 116 | + public function testStrict(): void |
| 117 | + { |
| 118 | + $this->strictMode = true; |
| 119 | + $this->analyzeFiles([__DIR__ . '/Data/ComplexRule/strict.php']); |
| 120 | + } |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +### PHP Version-Specific Tests |
| 125 | + |
| 126 | +```php |
| 127 | +public function testPhp82Features(): void |
| 128 | +{ |
| 129 | + $this->phpVersion = $this->createPhpVersion(80_200); |
| 130 | + $this->analyzeFiles([__DIR__ . '/Data/Rule/php82-features.php']); |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +### Custom PHPStan Configuration |
| 135 | + |
| 136 | +Create `tests/Rule/Data/YourRule/config.neon`: |
| 137 | + |
| 138 | +```neon |
| 139 | +parameters: |
| 140 | + customParameter: value |
| 141 | +``` |
| 142 | + |
| 143 | +Then reference it in your test: |
| 144 | + |
| 145 | +```php |
| 146 | +public static function getAdditionalConfigFiles(): array |
| 147 | +{ |
| 148 | + return array_merge( |
| 149 | + parent::getAdditionalConfigFiles(), |
| 150 | + [__DIR__ . '/Data/YourRule/config.neon'], |
| 151 | + ); |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +### Rules with Dependencies |
| 156 | + |
| 157 | +```php |
| 158 | +protected function getRule(): Rule |
| 159 | +{ |
| 160 | + $dependency = self::getContainer()->getByType(SomeService::class); |
| 161 | + return new RuleWithDependencies($dependency); |
| 162 | +} |
| 163 | +``` |
| 164 | + |
| 165 | +## File Organization |
| 166 | + |
| 167 | +Recommended directory structure: |
| 168 | + |
| 169 | +``` |
| 170 | +tests/ |
| 171 | +├── Rule/ |
| 172 | +│ ├── YourRuleTest.php |
| 173 | +│ ├── AnotherRuleTest.php |
| 174 | +│ └── Data/ |
| 175 | +│ ├── YourRule/ |
| 176 | +│ │ ├── code.php # Main test file |
| 177 | +│ │ ├── edge-cases.php # Additional scenarios |
| 178 | +│ │ └── config.neon # Optional PHPStan config |
| 179 | +│ └── AnotherRule/ |
| 180 | +│ └── code.php |
| 181 | +``` |
| 182 | + |
| 183 | +## Development |
| 184 | + |
| 185 | +```bash |
| 186 | +# Install dependencies |
| 187 | +composer install |
| 188 | + |
| 189 | +# Run all checks |
| 190 | +composer check |
| 191 | + |
| 192 | +# Individual checks |
| 193 | +composer check:composer # Validate composer.json |
| 194 | +composer check:ec # Check EditorConfig compliance |
| 195 | +composer check:cs # Check coding standards (PHPCS) |
| 196 | +composer check:types # Run PHPStan analysis |
| 197 | +composer check:dependencies # Analyze dependencies |
| 198 | +composer check:collisions # Check for name collisions |
| 199 | + |
| 200 | +# Fix coding standards |
| 201 | +composer fix:cs |
| 202 | +``` |
| 203 | + |
| 204 | +## License |
| 205 | + |
| 206 | +MIT License - see [LICENSE](LICENSE) file. |
0 commit comments