ima-claude 2.20.0 → 2.26.0

package/plugins/ima-claude/skills/phpunit-wp/SKILL.md

@@ -5,46 +5,28 @@ description: "PHPUnit testing for WordPress plugins with FP principles - fast un
 
 # PHPUnit for WordPress Plugins
 
-Expert guidance for PHPUnit testing in WordPress plugins, emphasizing pure function testing, minimal mocking, and FP principles.
-
-## When to Use This Skill
-
-- Setting up PHPUnit for new WordPress plugins
-- Debugging silent/hanging test runs
-- Writing testable pure functions
-- Mocking WordPress functions correctly
-- Testing with FP principles
-
 ## Core Philosophy
 
-**Test pure functions, not WordPress integration.**
+Test pure functions, not WordPress integration.
 
-1. **Pure business logic** = Fast unit tests (<100ms, no WordPress)
-2. **WordPress wrappers** = Integration tests (slower, full WP environment)
-3. **Mock minimally** = Only mock what's needed for pure function context
+| Layer | Approach | Speed |
+|-------|----------|-------|
+| Pure business logic | Unit tests, no WordPress | <100ms |
+| WordPress wrappers | Integration tests, full WP env | Seconds |
+| Mocks | Only what pure functions actually use | Minimal |
 
-**Foundation**: Reference `../php-fp/SKILL.md` and `../php-fp-wordpress/SKILL.md` for FP patterns.
+References: `../php-fp/SKILL.md`, `../php-fp-wordpress/SKILL.md`
 
 ---
 
-## THE TWO CRITICAL SETUP BUGS (We Keep Forgetting!)
+## THE TWO CRITICAL SETUP BUGS
 
-### 🐛 Bug #1: Silent PHPUnit Execution
+### Bug #1: Silent PHPUnit Execution
 
-**Symptom**: `composer test` produces ZERO output, not even "no tests found"
+**Symptom**: `composer test` produces zero output
 
-**Root Cause**: PHPUnit 9.x doesn't output anything without `--testdox` flag
+**Cause**: PHPUnit 9.x requires `--testdox` for visible output
 
-**❌ BROKEN** (silent execution):
-```json
-{
-    "scripts": {
-        "test": "phpunit"
-    }
-}
-```
-
-**✅ FIXED** (visible output):
 ```json
 {
     "scripts": {
@@ -54,46 +36,25 @@ Expert guidance for PHPUnit testing in WordPress plugins, emphasizing pure funct
 }
 ```
 
----
-
-### 🐛 Bug #2: Autoload Files Kill Tests
+### Bug #2: Autoload Files Kill Tests
 
-**Symptom**: Tests hang or exit silently with no error message
+**Symptom**: Tests hang or exit silently
 
-**Root Cause**: Composer autoload runs BEFORE test bootstrap defines `ABSPATH`
+**Cause**: Composer autoload runs BEFORE bootstrap defines `ABSPATH`
 
-**The Fatal Flow**:
 ```
-1. bootstrap.php line 17: require vendor/autoload.php
-2. Composer sees: "autoload": { "files": ["includes/helpers.php"] }
-3. Composer loads helpers.php IMMEDIATELY
-4. helpers.php line 14: if (!defined('ABSPATH')) { exit; }
-5. ABSPATH not defined yet (happens bootstrap.php line 22)
-6. Script exits silently
-7. PHPUnit never starts
+1. bootstrap.php requires vendor/autoload.php
+2. Composer loads autoload "files" immediately
+3. helpers.php: if (!defined('ABSPATH')) { exit; }
+4. ABSPATH not yet defined → silent exit → PHPUnit never starts
 ```
 
-**❌ BROKEN** (causes silent exit):
-```json
-{
-    "autoload": {
-        "files": [
-            "includes/helpers/url-validation.php",
-            "includes/helpers/share-urls.php"
-        ]
-    }
-}
-```
+Fix: Remove `autoload.files`, load helpers manually in bootstrap AFTER defining `ABSPATH`.
 
-**✅ FIXED** (no autoload files):
 ```json
 {
-    // NO autoload section with files array!
-    // Bootstrap loads helpers manually AFTER defining ABSPATH
     "autoload-dev": {
-        "psr-4": {
-            "MyPlugin\\Tests\\": "tests/"
-        }
+        "psr-4": { "MyPlugin\\Tests\\": "tests/" }
     }
 }
 ```
@@ -102,90 +63,43 @@ Expert guidance for PHPUnit testing in WordPress plugins, emphasizing pure funct
 
 ## Environment Setup
 
-### Running Tests in Local WP Environment
-
-**Important**: Composer and PHPUnit need Local WP's PHP environment. Git commands work in normal terminal.
-
-**Use the project's configured Local WP environment**:
-
-The `wp-local` skill provides the environment loader pattern. For composer/phpunit commands, create a similar wrapper or use the pattern directly:
+Composer/PHPUnit require Local WP's PHP environment. Git commands work in normal terminal.
 
 ```bash
-# Pattern from wp-local skill:
-# 1. Sources ~/kitty/load-localwp-env.sh with site name from $WP_LOCAL_SITE or .wp-local
-# 2. Runs command in that environment
+# Run tests in Local WP environment
+bash -c "source ~/kitty/load-localwp-env.sh $(cat .wp-local || echo $WP_LOCAL_SITE) && composer test"
 
-# Example - Run tests:
-bash -c "source ~/kitty/load-localwp-env.sh \$(cat .wp-local || echo \$WP_LOCAL_SITE) && composer test"
-
-# Or install dependencies:
-bash -c "source ~/kitty/load-localwp-env.sh \$(cat .wp-local || echo \$WP_LOCAL_SITE) && composer install"
+# Useful aliases (~/.zshrc)
+alias wptest='bash -c "source ~/kitty/load-localwp-env.sh $(cat .wp-local || echo $WP_LOCAL_SITE) && composer test"'
+alias wpcomposer='bash -c "source ~/kitty/load-localwp-env.sh $(cat .wp-local || echo $WP_LOCAL_SITE) && composer $@"'
 ```
 
-**Pro Tip**: Create a shell alias in your `~/.bashrc` or `~/.zshrc`:
-```bash
-alias wptest='bash -c "source ~/kitty/load-localwp-env.sh \$(cat .wp-local || echo \$WP_LOCAL_SITE) && composer test"'
-alias wpcomposer='bash -c "source ~/kitty/load-localwp-env.sh \$(cat .wp-local || echo \$WP_LOCAL_SITE) && composer $@"'
-```
-
-Then simply:
-```bash
-wptest                    # Run tests
-wpcomposer install       # Install dependencies
-```
-
-### Environment Configuration
+**Site resolution priority**: `$WP_LOCAL_SITE` env var → `.wp-local` file → error
 
-**Priority order** (same as wp-local):
-1. `$WP_LOCAL_SITE` environment variable (set by Kitty terminal)
-2. `.wp-local` file in project root (site UUID like `19efkkzWB`)
-3. Error if neither configured
+### Quick Diagnosis
 
-**For git operations** (no environment needed):
 ```bash
-# Regular terminal works fine - git doesn't need PHP environment
-git status
-git commit -m "fix: phpunit setup"
-git push
-```
-
-### Quick Test Diagnosis
-
-```bash
-# 1. Check if bootstrap prints (should see "Bootstrap Loaded")
-php tests/bootstrap.php
-
-# 2. Check if PHPUnit is installed
-ls -la vendor/bin/phpunit
-
-# 3. Check composer.json scripts
+php tests/bootstrap.php          # Should print "Bootstrap Loaded"
+ls -la vendor/bin/phpunit        # Verify phpunit installed
 cat composer.json | grep -A 3 scripts
-
-# 4. Check for autoload files bug
 cat composer.json | grep -A 5 autoload
 ```
 
 ---
 
-## Copy-Paste Working Template
+## Working Templates
 
 ### composer.json
+
 ```json
 {
     "name": "ima-network/my-plugin",
-    "description": "Plugin description",
     "type": "wordpress-plugin",
     "license": "GPL-2.0-or-later",
-    "require": {
-        "php": ">=7.4"
-    },
-    "require-dev": {
-        "phpunit/phpunit": "^9.5"
-    },
+    "require": { "php": ">=7.4" },
+    "require-dev": { "phpunit/phpunit": "^9.5" },
     "autoload-dev": {
-        "psr-4": {
-            "MyPlugin\\Tests\\": "tests/"
-        }
+        "psr-4": { "MyPlugin\\Tests\\": "tests/" }
     },
     "scripts": {
         "test": "phpunit --colors=always --testdox",
@@ -195,6 +109,7 @@ cat composer.json | grep -A 5 autoload
 ```
 
 ### phpunit.xml
+
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -225,236 +140,126 @@ cat composer.json | grep -A 5 autoload
 ```
 
 ### tests/bootstrap.php
+
 ```php
 <?php
-/**
- * PHPUnit Bootstrap for My Plugin
- *
- * Loads pure functions for unit testing without WordPress dependencies.
- */
 declare(strict_types=1);
 
-// 1. Load Composer autoloader FIRST (but it won't autoload files - we removed that!)
+// 1. Autoloader first (no autoload.files — removed!)
 require_once dirname(__DIR__) . '/vendor/autoload.php';
 
-// 2. Define ABSPATH to prevent plugin file exits
+// 2. Define ABSPATH before loading any plugin files
 if (!defined('ABSPATH')) {
     define('ABSPATH', '/tmp/wordpress/');
 }
 
-// 3. Define plugin constants
+// 3. Plugin constants
 if (!defined('MY_PLUGIN_PATH')) {
     define('MY_PLUGIN_PATH', dirname(__DIR__) . '/');
 }
 
-// 4. NOW manually load helper files (AFTER ABSPATH defined!)
+// 4. Load helpers manually (AFTER ABSPATH)
 require_once MY_PLUGIN_PATH . 'includes/helpers/url-validation.php';
 require_once MY_PLUGIN_PATH . 'includes/helpers/share-urls.php';
 
-// 5. Mock WordPress functions minimally
+// 5. Minimal WP function mocks
 if (!function_exists('home_url')) {
     function home_url(string $path = ''): string {
         return 'https://example.com' . $path;
     }
 }
-
 if (!function_exists('sanitize_text_field')) {
     function sanitize_text_field(string $str): string {
-        $filtered = strip_tags($str);
-        $filtered = str_replace(["\r", "\n"], '', $filtered);
-        return trim($filtered);
+        return trim(str_replace(["\r", "\n"], '', strip_tags($str)));
     }
 }
-
 if (!function_exists('esc_html')) {
     function esc_html(string $text): string {
         return htmlspecialchars($text, ENT_QUOTES, 'UTF-8');
     }
 }
 
-// 6. Confirmation message (proves bootstrap loaded)
-echo "✅ My Plugin Test Bootstrap Loaded\n";
+echo "My Plugin Test Bootstrap Loaded\n";
 ```
 
 ---
 
-## What to Test (FP Principles)
+## What to Test
 
-### ✅ DO TEST: Pure Business Logic
+### DO: Pure Business Logic
 
 ```php
 <?php
-// includes/helpers/validation.php
-declare(strict_types=1);
-
-/**
- * PURE function - Zero WordPress dependencies
- * Perfect for unit testing
- */
+// Pure function — zero WordPress dependencies, perfect for unit testing
 function my_plugin_validate_email_pure(string $email): array {
-    if (empty($email)) {
-        return ['valid' => false, 'error' => 'Email required'];
-    }
-
-    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
-        return ['valid' => false, 'error' => 'Invalid email format'];
-    }
+    if (empty($email)) return ['valid' => false, 'error' => 'Email required'];
+    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) return ['valid' => false, 'error' => 'Invalid email format'];
 
-    // Check for disposable domains
     $disposable = ['tempmail.com', 'throwaway.email'];
     $domain = substr(strrchr($email, '@'), 1);
-    if (in_array($domain, $disposable)) {
-        return ['valid' => false, 'error' => 'Disposable email not allowed'];
-    }
+    if (in_array($domain, $disposable)) return ['valid' => false, 'error' => 'Disposable email not allowed'];
 
     return ['valid' => true];
 }
 ```
 
-**Test**:
 ```php
 <?php
-// tests/Unit/ValidationTest.php
-use PHPUnit\Framework\TestCase;
-
 class ValidationTest extends TestCase {
     public function test_empty_email_returns_error() {
         $result = my_plugin_validate_email_pure('');
-
         $this->assertFalse($result['valid']);
         $this->assertEquals('Email required', $result['error']);
     }
 
-    public function test_invalid_format_returns_error() {
-        $result = my_plugin_validate_email_pure('not-an-email');
-
-        $this->assertFalse($result['valid']);
-        $this->assertEquals('Invalid email format', $result['error']);
-    }
-
-    public function test_disposable_email_rejected() {
-        $result = my_plugin_validate_email_pure('user@tempmail.com');
-
-        $this->assertFalse($result['valid']);
-        $this->assertEquals('Disposable email not allowed', $result['error']);
-    }
-
     public function test_valid_email_passes() {
         $result = my_plugin_validate_email_pure('user@example.com');
-
         $this->assertTrue($result['valid']);
-        $this->assertArrayNotHasKey('error', $result);
     }
 
-    // FP Principle: Test determinism
     public function test_function_is_deterministic() {
-        $email = 'test@example.com';
-        $result1 = my_plugin_validate_email_pure($email);
-        $result2 = my_plugin_validate_email_pure($email);
-
-        $this->assertEquals($result1, $result2);
+        $this->assertEquals(
+            my_plugin_validate_email_pure('test@example.com'),
+            my_plugin_validate_email_pure('test@example.com')
+        );
     }
 }
 ```
 
----
-
-### ❌ DON'T TEST: WordPress Integration Wrappers
+### DON'T: WordPress Integration Wrappers
 
 ```php
 <?php
-// includes/ajax-handlers.php - WordPress wrapper
+// Skip unit testing this — it's 100% WordPress integration
 function my_plugin_ajax_validate_email() {
-    // DON'T unit test this - it's all WordPress integration!
     check_ajax_referer('validate_email_nonce', 'nonce');
-
-    if (!current_user_can('read')) {
-        wp_send_json_error('Unauthorized', 403);
-    }
-
-    $email = sanitize_email($_POST['email']);
-
-    // Call pure function (which IS tested)
-    $result = my_plugin_validate_email_pure($email);
-
-    wp_send_json_success($result);
+    if (!current_user_can('read')) wp_send_json_error('Unauthorized', 403);
+    wp_send_json_success(my_plugin_validate_email_pure(sanitize_email($_POST['email'])));
 }
-add_action('wp_ajax_my_plugin_validate_email', 'my_plugin_ajax_validate_email');
 ```
 
-**Why not test**: This is 100% WordPress integration. Testing it requires:
-- Full WordPress environment
-- Mocking `$_POST`, nonces, capabilities, AJAX functions
-- Complex setup that's brittle and slow
-
-**Better approach**:
-- Unit test the pure function (`my_plugin_validate_email_pure`) ✅
-- Integration test the AJAX handler with real WordPress (separate test suite)
+Unit test the pure function. Integration test the AJAX handler with a real WP environment.
 
 ---
 
-## Mocking Rules (Minimal Philosophy)
-
-### Mock Only What's Needed for Pure Context
-
-**❌ DON'T over-mock**:
-```php
-<?php
-// Excessive mocking for a pure function test
-if (!function_exists('wp_remote_post')) { /* ... */ }
-if (!function_exists('wp_remote_get')) { /* ... */ }
-if (!function_exists('get_option')) { /* ... */ }
-if (!function_exists('update_option')) { /* ... */ }
-if (!function_exists('delete_option')) { /* ... */ }
-// ... 50 more mocks you don't need
-```
-
-**✅ DO mock minimally**:
-```php
-<?php
-// Only mock what pure functions actually use
-if (!function_exists('sanitize_text_field')) {
-    function sanitize_text_field(string $str): string {
-        return trim(strip_tags($str));
-    }
-}
-
-if (!function_exists('home_url')) {
-    function home_url(string $path = ''): string {
-        return 'https://example.com' . $path;
-    }
-}
-```
+## Mocking Rules
 
-### Common WordPress Mocks for Pure Functions
+Mock only what pure functions actually call. Common mocks for pure functions:
 
 ```php
 <?php
-// WordPress utility functions (pure-ish)
 if (!function_exists('wp_parse_args')) {
     function wp_parse_args($args, $defaults = []): array {
-        if (is_string($args)) {
-            parse_str($args, $parsed_args);
-            $args = $parsed_args;
-        }
+        if (is_string($args)) { parse_str($args, $args); }
         return array_merge($defaults, (array) $args);
     }
 }
-
-// Sanitization functions
 if (!function_exists('sanitize_email')) {
-    function sanitize_email(string $email): string {
-        return strtolower(trim($email));
-    }
+    function sanitize_email(string $email): string { return strtolower(trim($email)); }
 }
-
 if (!function_exists('esc_url_raw')) {
-    function esc_url_raw(string $url): string {
-        return filter_var($url, FILTER_SANITIZE_URL) ?: '';
-    }
+    function esc_url_raw(string $url): string { return filter_var($url, FILTER_SANITIZE_URL) ?: ''; }
 }
-
-// URL parsing (WordPress wrapper for parse_url)
 if (!function_exists('wp_parse_url')) {
     function wp_parse_url(string $url, int $component = -1) {
         return $component === -1 ? parse_url($url) : parse_url($url, $component);
@@ -464,241 +269,82 @@ if (!function_exists('wp_parse_url')) {
 
 ---
 
-## Test Organization Patterns
-
-### Pattern 1: Pure Function Testing (Fastest)
-
-```
-tests/
-└── Unit/
-    ├── ValidationTest.php      # Pure validation functions
-    ├── CalculationTest.php     # Pure calculation logic
-    └── FormatterTest.php       # Pure formatting functions
-```
-
-**Characteristics**:
-- No WordPress dependencies
-- Fast (<100ms total)
-- No database, no HTTP, no filesystem
-- Run on every commit
-
-### Pattern 2: Integration Testing (Slower)
+## Test Organization
 
 ```
 tests/
-└── Integration/
-    ├── AjaxHandlerTest.php     # Full WordPress + AJAX
-    ├── ShortcodeTest.php       # Full WordPress + rendering
-    └── DatabaseTest.php        # Full WordPress + DB
+├── Unit/               # Pure functions — no WP, <100ms, run every commit
+│   ├── ValidationTest.php
+│   ├── CalculationTest.php
+│   └── FormatterTest.php
+└── Integration/        # Full WP env — run before releases
+    ├── AjaxHandlerTest.php
+    └── DatabaseTest.php
 ```
 
-**Characteristics**:
-- Requires full WordPress installation
-- Uses WP_UnitTestCase from wordpress-develop
-- Slower (seconds to minutes)
-- Run before releases
-
 ---
 
-## Testing Patterns by Function Type
+## Patterns by Function Type
 
-### Pure Calculations
 ```php
-<?php
-function calculate_discount_pure(float $price, float $rate): float {
-    return round($price * (1 - $rate), 2);
-}
-
-// Test: Assert exact values
+// Calculations — assert exact values
 $this->assertEquals(90.0, calculate_discount_pure(100.0, 0.10));
-$this->assertEquals(95.0, calculate_discount_pure(100.0, 0.05));
-```
 
-### Pure Validation
-```php
-<?php
-function validate_age_pure(int $age): array {
-    if ($age < 0) return ['valid' => false, 'error' => 'Negative age'];
-    if ($age < 18) return ['valid' => false, 'error' => 'Must be 18+'];
-    return ['valid' => true];
-}
-
-// Test: Assert result structure
+// Validation — assert result structure
 $result = validate_age_pure(15);
 $this->assertFalse($result['valid']);
 $this->assertArrayHasKey('error', $result);
-```
 
-### Pure Transformations
-```php
-<?php
-function format_phone_pure(string $phone): string {
-    $digits = preg_replace('/\D/', '', $phone);
-    if (strlen($digits) === 10) {
-        return sprintf('(%s) %s-%s',
-            substr($digits, 0, 3),
-            substr($digits, 3, 3),
-            substr($digits, 6, 4)
-        );
-    }
-    return $phone;
-}
-
-// Test: Assert transformations
+// Transformations — assert output shape
 $this->assertEquals('(555) 123-4567', format_phone_pure('5551234567'));
 $this->assertEquals('(555) 123-4567', format_phone_pure('555-123-4567'));
-$this->assertEquals('invalid', format_phone_pure('invalid'));
-```
-
----
 
-## Performance Testing (FP Principle)
-
-Pure functions enable easy performance testing:
-
-```php
-<?php
-public function test_performance_fast_execution() {
-    $iterations = 10000;
-    $start = microtime(true);
-
-    for ($i = 0; $i < $iterations; $i++) {
-        my_plugin_validate_email_pure('user@example.com');
-    }
-
-    $elapsed = microtime(true) - $start;
-
-    // Should complete 10k validations in < 100ms
-    $this->assertLessThan(0.1, $elapsed);
-}
+// Performance — pure functions enable this for free
+$start = microtime(true);
+for ($i = 0; $i < 10000; $i++) { my_plugin_validate_email_pure('user@example.com'); }
+$this->assertLessThan(0.1, microtime(true) - $start);
 ```
 
 ---
 
-## Common Anti-Patterns
-
-### ❌ Testing Private Methods
+## Anti-Patterns
 
-```php
-<?php
-// DON'T use reflection to test private methods
-class MyTest extends TestCase {
-    public function test_private_method() {
-        $reflection = new ReflectionClass(MyClass::class);
-        $method = $reflection->getMethod('privateMethod');
-        $method->setAccessible(true);
-        // ...
-    }
-}
-
-// DO extract pure function and test that
-function my_plugin_process_data_pure(array $data): array {
-    // Extracted logic, now testable
-    return $data;
-}
-```
-
-### ❌ Testing Implementation Details
-
-```php
-<?php
-// DON'T test internal variable values
-public function test_internal_state() {
-    $obj = new MyClass();
-    $this->assertEquals(5, $obj->internalCounter); // Brittle!
-}
-
-// DO test public behavior
-public function test_public_behavior() {
-    $result = my_plugin_process_items(['a', 'b', 'c']);
-    $this->assertCount(3, $result);
-}
-```
-
-### ❌ Over-Mocking
-
-```php
-<?php
-// DON'T mock everything
-$mock = $this->createMock(Database::class);
-$mock->method('query')->willReturn([]);
-$mock->method('insert')->willReturn(1);
-$mock->method('update')->willReturn(true);
-// ... 20 more mocks
-
-// DO test pure functions that don't need mocks
-function process_results_pure(array $results): array {
-    return array_map('strtoupper', $results);
-}
-```
+| Avoid | Do Instead |
+|-------|-----------|
+| Reflection to test private methods | Extract as testable pure function |
+| Test internal variable values | Test public behavior/output |
+| Mock 20+ WordPress functions | Redesign so pure function needs <5 mocks |
 
 ---
 
 ## Quality Gates
 
-Before merging:
-- [ ] `composer test` produces visible output (not silent)
-- [ ] Bootstrap prints "Bootstrap Loaded" message
-- [ ] Tests run in < 100ms for pure functions
-- [ ] No autoload files section in composer.json
-- [ ] Pure business logic separated from WordPress wrappers
-- [ ] Mock count is minimal (< 10 functions)
-- [ ] Test assertions are deterministic (no flaky tests)
+- [ ] `composer test` produces visible output
+- [ ] Bootstrap prints confirmation message
+- [ ] Pure function tests run in <100ms
+- [ ] No `autoload.files` in composer.json
+- [ ] Pure business logic separated from WP wrappers
+- [ ] Mock count <10 functions
+- [ ] No flaky assertions
 
 ---
 
-## Working Examples
+## Reference Plugins
 
-**Reference plugins with working tests**:
 ```bash
-# ima-forms: Gold standard
-cd wp-content/plugins/ima-forms
-composer test
-
-# ima-shortcodes: Recently fixed
-cd wp-content/plugins/ima-shortcodes
-composer test
+cd wp-content/plugins/ima-forms && composer test       # Gold standard
+cd wp-content/plugins/ima-shortcodes && composer test  # Recently fixed
 ```
 
 ---
 
 ## Troubleshooting
 
-### Issue: Silent test execution
-
-**Symptom**: `composer test` produces no output
-
-**Fix**: Add `--testdox` flag to composer.json scripts
-
-### Issue: Tests hang/exit silently
-
-**Symptom**: Process hangs or exits without error
-
-**Diagnosis**:
-```bash
-# Check if bootstrap runs
-php tests/bootstrap.php
-
-# Check for autoload files bug
-cat composer.json | grep -A 5 autoload
-```
-
-**Fix**: Remove autoload files section, load manually in bootstrap
-
-### Issue: "Class not found" errors
-
-**Symptom**: PHPUnit can't find test classes
-
-**Fix**: Check `autoload-dev` PSR-4 mapping in composer.json:
-```json
-"autoload-dev": {
-    "psr-4": {
-        "MyPlugin\\Tests\\": "tests/"
-    }
-}
-```
-
-Then run: `composer dump-autoload`
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No output from `composer test` | Missing `--testdox` | Add `--testdox` to scripts |
+| Hang/silent exit | `autoload.files` loads before ABSPATH | Remove files array, load manually in bootstrap |
+| "Class not found" | Bad PSR-4 mapping | Check `autoload-dev` in composer.json, run `composer dump-autoload` |
 
 ---
 
@@ -706,11 +352,5 @@ Then run: `composer dump-autoload`
 
 - `../php-fp/SKILL.md` - Core FP principles
 - `../php-fp-wordpress/SKILL.md` - WordPress security + FP
-- `../wp-local/SKILL.md` - Local WP environment handling
-- PHPUnit docs: https://phpunit.de/documentation.html
-- WordPress test suite: https://make.wordpress.org/core/handbook/testing/automated-testing/phpunit/
-
----
-
-**Last Updated**: 2026-01-29
-**Discovery**: After debugging the same bugs across multiple plugins (ima-forms, ima-shortcodes, ima-access-control)
+- `../wp-local/SKILL.md` - Local WP environment
+- https://phpunit.de/documentation.html