start-vibing-stacks 2.16.0 → 2.17.0

package/stacks/php/skills/phpunit-testing/SKILL.md

@@ -1,40 +1,207 @@
 ---
 name: phpunit-testing
-version: 1.0.0
+version: 2.0.0
+description: "PHP testing for 2026 — covers PHPUnit 12 (released 2025, foundation for Pest 4) and Pest 4 (March 2026: 20-30% faster, browser testing via Playwright, visual regression, smoke testing, sharding for CI parallelization, mutation testing). Includes Unit / Feature / Browser / Architecture test layout, AAA pattern, data providers / datasets, mocking, fixtures, dataset sharding, coverage thresholds. Invoke when authoring tests, choosing PHPUnit vs Pest, configuring sharding/parallel, or wiring CI test stages."
 ---
 
-# PHPUnit Testing Skill
+# PHP Testing — PHPUnit 12 & Pest 4 (2026)
+
+**ALWAYS invoke when writing tests, choosing the framework, or wiring CI sharding.**
+
+> Pest 4 (Mar 10, 2026) is built on PHPUnit 12. New projects in 2026: prefer **Pest 4** for ergonomics and built-in browser/visual testing; stay on **PHPUnit 12** if your team has muscle memory or you need raw assertion control.
+
+## Framework Choice
+
+| Need | Pick |
+|---|---|
+| New Laravel app, want fluent expectation API + browser tests | **Pest 4** |
+| Plain PHP library, prefer xUnit-classic | **PHPUnit 12** |
+| Big legacy PHPUnit suite | **PHPUnit 12** (don't migrate just for migration's sake) |
+| Need visual regression / Playwright in PHP | **Pest 4** (built-in) |
+
+Both share the same engine — assertions, mocks, runners are interoperable through Pest's PHPUnit base. Pest is a thin DSL on top.
 
 ## Setup
 
+### Pest 4 (recommended for new Laravel projects)
+
 ```bash
-composer require --dev phpunit/phpunit
+composer require --dev pestphp/pest "^4.0"            # PHP 8.3+
+composer require --dev pestphp/pest-plugin-laravel "^4.0"
+./vendor/bin/pest --init
 ```
 
-## Test File Location
+### PHPUnit 12
+
+```bash
+composer require --dev phpunit/phpunit "^12.0"
+```
+
+## File Layout
 
 ```
 tests/
+├── Pest.php                      # Pest config (test dirs, datasets, helpers)
+├── TestCase.php                  # Shared base
 ├── Unit/
-│   ├── Services/
-│   │   └── UserServiceTest.php
-│   └── Helpers/
-│       └── StringHelperTest.php
+│   ├── Services/UserServiceTest.php
+│   └── Helpers/StringHelperTest.php
 ├── Feature/
-│   └── Api/
-│       └── UserApiTest.php
-└── phpunit.xml
+│   └── Api/UserApiTest.php
+├── Browser/                      # Pest 4 — Playwright-backed
+│   └── LoginFlowTest.php
+└── Arch/                         # Pest — architecture rules
+    └── LayerBoundariesTest.php
+phpunit.xml                       # used by both Pest & PHPUnit
+```
+
+## `phpunit.xml` — production-grade baseline
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+    bootstrap="vendor/autoload.php"
+    colors="true"
+    cacheDirectory=".phpunit.cache"
+    requireCoverageMetadata="true"
+    beStrictAboutCoverageMetadata="true"
+    beStrictAboutOutputDuringTests="true"
+    failOnRisky="true"
+    failOnWarning="true"
+    executionOrder="random">
+
+    <testsuites>
+        <testsuite name="Unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="Feature">
+            <directory>tests/Feature</directory>
+        </testsuite>
+        <testsuite name="Browser">
+            <directory>tests/Browser</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory>app</directory>
+        </include>
+    </source>
+
+    <coverage includeUncoveredFiles="true">
+        <report>
+            <clover outputFile="coverage.xml"/>
+            <text outputFile="php://stdout" showOnlySummary="true"/>
+        </report>
+    </coverage>
+
+    <php>
+        <env name="APP_ENV" value="testing"/>
+        <env name="DB_CONNECTION" value="sqlite"/>
+        <env name="DB_DATABASE" value=":memory:"/>
+    </php>
+</phpunit>
 ```
 
-## Test Template
+## Pest 4 — patterns
+
+### Unit + Feature
 
 ```php
-<?php
+// tests/Unit/Services/UserServiceTest.php
+use App\Services\UserService;
+
+beforeEach(fn () => $this->service = new UserService);
+
+it('creates a user with valid data', function () {
+    $user = $this->service->create(['name' => 'John', 'email' => 'john@test.com']);
+
+    expect($user)
+        ->name->toBe('John')
+        ->email->toBe('john@test.com');
+});
+
+it('rejects invalid email', function () {
+    $this->service->create(['name' => 'John', 'email' => 'invalid']);
+})->throws(InvalidArgumentException::class, 'Invalid email');
+
+dataset('invalid_users', [
+    'empty name'  => [['name' => '',     'email' => 'a@b.com'], 'Name required'],
+    'empty email' => [['name' => 'John', 'email' => ''],        'Email required'],
+    'no data'     => [[],                                        'Name required'],
+]);
+
+it('rejects invalid data', function (array $data, string $expected) {
+    $this->service->create($data);
+})->with('invalid_users')->throws(InvalidArgumentException::class);
+```
+
+### Browser test (Pest 4 — Playwright-backed)
+
+```php
+// tests/Browser/LoginFlowTest.php
+use function Pest\Browser\visit;
+
+it('logs the user in', function () {
+    visit('/login')
+        ->fill('email',    'user@test.com')
+        ->fill('password', 'secret')
+        ->press('Sign in')
+        ->assertPathIs('/dashboard')
+        ->assertSee('Welcome back');
+});
+
+// Multi-viewport smoke
+it('login page is responsive', function (string $device) {
+    visit('/login')
+        ->onDevice($device)            // 'iphone-14', 'ipad', 'desktop-1280'
+        ->assertNoConsoleErrors()
+        ->assertNoBrokenLinks()
+        ->screenshot();
+})->with(['iphone-14', 'ipad', 'desktop-1280']);
+```
+
+### Architecture test (Pest)
 
+```php
+// tests/Arch/LayerBoundariesTest.php
+arch('controllers do not call DB directly')
+    ->expect('App\Http\Controllers')
+    ->not->toUse(['Illuminate\Support\Facades\DB']);
+
+arch('domain layer is framework-free')
+    ->expect('App\Domain')
+    ->not->toUse([
+        'Illuminate\Database',
+        'Illuminate\Http',
+        'Illuminate\Support\Facades',
+    ]);
+
+arch('strict types everywhere')
+    ->expect('App')
+    ->toUseStrictTypes();
+```
+
+### Mutation testing
+
+```bash
+./vendor/bin/pest --mutate --covered-only
+```
+
+Pest mutates your code and re-runs tests; surviving mutants reveal weak assertions.
+
+## PHPUnit 12 — same domain, classic style
+
+```php
+<?php
 declare(strict_types=1);
 
 namespace Tests\Unit\Services;
 
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
 use App\Services\UserService;
 
@@ -48,80 +215,99 @@ final class UserServiceTest extends TestCase
         $this->service = new UserService();
     }
 
-    public function testCreateUserWithValidData(): void
+    #[Test]
+    public function it_creates_a_user_with_valid_data(): void
     {
-        // Arrange
-        $data = ['name' => 'John', 'email' => 'john@test.com'];
-
-        // Act
-        $user = $this->service->create($data);
-
-        // Assert
-        $this->assertSame('John', $user->name);
-        $this->assertSame('john@test.com', $user->email);
+        $user = $this->service->create(['name' => 'John', 'email' => 'john@test.com']);
+        self::assertSame('John', $user->name);
+        self::assertSame('john@test.com', $user->email);
     }
 
-    public function testCreateUserThrowsOnInvalidEmail(): void
+    #[Test]
+    #[DataProvider('invalidDataProvider')]
+    public function it_rejects_invalid_data(array $data, string $expected): void
     {
         $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage('Invalid email');
-
-        $this->service->create(['name' => 'John', 'email' => 'invalid']);
-    }
-
-    /**
-     * @dataProvider invalidDataProvider
-     */
-    public function testCreateUserRejectsInvalidData(array $data, string $expectedError): void
-    {
-        $this->expectException(\InvalidArgumentException::class);
-        $this->expectExceptionMessage($expectedError);
-
+        $this->expectExceptionMessage($expected);
         $this->service->create($data);
     }
 
     public static function invalidDataProvider(): array
     {
         return [
-            'empty name' => [['name' => '', 'email' => 'a@b.com'], 'Name required'],
-            'empty email' => [['name' => 'John', 'email' => ''], 'Email required'],
-            'null data' => [[], 'Name required'],
+            'empty name'  => [['name' => '',     'email' => 'a@b.com'], 'Name required'],
+            'empty email' => [['name' => 'John', 'email' => ''],        'Email required'],
+            'no data'     => [[],                                        'Name required'],
         ];
     }
 }
 ```
 
+> PHPUnit 12 deprecated `/** @test */` and `/** @dataProvider */` annotations — use the `#[Test]` and `#[DataProvider]` attributes shown above.
+
 ## Mocking
 
 ```php
-public function testServiceCallsRepository(): void
-{
-    $repo = $this->createMock(UserRepository::class);
-    $repo->expects($this->once())
-         ->method('save')
-         ->with($this->isInstanceOf(User::class))
-         ->willReturn(true);
+// PHPUnit
+$repo = $this->createMock(UserRepository::class);
+$repo->expects($this->once())
+     ->method('save')
+     ->with($this->isInstanceOf(User::class))
+     ->willReturn(true);
 
-    $service = new UserService($repo);
-    $result = $service->create(['name' => 'John', 'email' => 'j@t.com']);
+// Pest — same engine, fluent
+$repo = mock(UserRepository::class)
+    ->shouldReceive('save')->once()->andReturn(true)
+    ->getMock();
+```
 
-    $this->assertTrue($result);
-}
+For HTTP: `Http::fake()` (Laravel) or Saloon's `MockClient` — see `external-api-patterns`.
+
+## Sharding for CI *(Pest 4 / PHPUnit 12)*
+
+```bash
+# Split a slow suite across 4 runners
+./vendor/bin/pest --parallel --shard=1/4
+./vendor/bin/pest --parallel --shard=2/4
+./vendor/bin/pest --parallel --shard=3/4
+./vendor/bin/pest --parallel --shard=4/4
+```
+
+```yaml
+# .github/workflows/ci.yml
+strategy:
+  matrix:
+    shardIndex: [1, 2, 3, 4]
+    shardTotal: [4]
+steps:
+  - run: ./vendor/bin/pest --parallel --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
 ```
 
-## Running
+## Coverage Thresholds
 
 ```bash
-vendor/bin/phpunit                          # All tests
-vendor/bin/phpunit tests/Unit/              # Unit only
-vendor/bin/phpunit --filter testCreateUser  # Specific test
-vendor/bin/phpunit --coverage-text          # With coverage
+# Fail under 70%
+./vendor/bin/pest --coverage --min=70
+./vendor/bin/phpunit --coverage-text --min=70
 ```
 
+Realistic 2026 baseline: **70% line coverage minimum**, 100% on Services / Domain layer, lower for Controllers (covered by feature tests anyway).
+
 ## Rules
 
-1. **One assertion concept per test**
-2. **Descriptive method names**: `testMethodName_Scenario_ExpectedResult`
-3. **Use data providers** for multiple inputs
-4. **setUp/tearDown** for shared state
-5. **Never skip tests** in commits
+1. **One concept per test** — don't `@dataProvider` a test that mixes unrelated assertions
+2. **Descriptive names** — `it_rejects_invalid_email`, not `testCreateUser2`
+3. **Datasets / data providers** for input matrices (DRY assertions, named cases)
+4. **`#[Test]` attribute, not `@test` PHPDoc** (PHPUnit 12 deprecated the latter)
+5. **`setUp` for shared fresh state, not shared mutable state**
+6. **Architecture tests on every Laravel project** — enforce layer rules in code, not docs
+7. **Mutation testing on critical Services** quarterly — catches "fake green" suites
+8. **Never `->skip()` / `->only()` in committed code**
+9. **Browser tests use real browsers (Pest 4 Playwright)** — no jsdom hacks
+
+## See Also
+
+- `playwright-automation` (`_shared`) — same Playwright engine Pest 4 uses
+- `quality-gate` — test step ordering
+- `external-api-patterns` — `Http::fake()` / Saloon mocking patterns
+- `phpstan-analysis` — typing that makes tests cheaper

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: security-scan-php
-version: 1.0.0
+version: 2.0.0
+description: "Laravel-specific security overlay on top of `security-baseline` (OWASP 2021 + 2025 deltas). Mass assignment, Sanctum/policies, Blade XSS, env() pitfalls in Octane, file upload validation, signed URLs, password hashing (Argon2id default since L10), CSRF on web routes, role-aware scoping, supply-chain hardening (composer audit + Roave Security Advisories + gitleaks 3-layer). Cross-references stay aligned with `security-baseline` §A01–§A10 anchors so the security-auditor agent can match. Invoke when reviewing any Laravel feature touching user data, auth, persistence, file IO, or external calls."
 ---
 
-# Laravel Security Scan
+# Laravel Security Scan (overlay on `security-baseline`)
+
+> **This skill is a Laravel overlay.** The universal OWASP rules (with 2025 deltas — Software Supply Chain Failures, Mishandling Exceptional Conditions) live in `_shared/skills/security-baseline`. The §A01–§A10 anchors below match those (2021 numbering kept for security-auditor cross-references).
 
 ## OWASP Top 10 for Laravel
 
@@ -189,15 +192,105 @@ $user = $request->user();
 - [ ] Sensitive headers set (X-Content-Type-Options, X-Frame-Options, CSP)
 - [ ] Rate limiting on authentication endpoints
 
+## Supply-Chain Hardening (OWASP 2025-A03)
+
+Laravel apps inherit every CVE in the Composer tree. The build server is a target.
+
+```bash
+# Production install — never run third-party scripts on the build server
+composer install --no-dev --no-scripts --optimize-autoloader --classmap-authoritative
+
+# Audit (Composer 2.8+) — fail the PR on vulns OR abandoned packages
+composer audit --abandoned=fail --ignore-severity=low
+```
+
+```json
+// composer.json — refuse to install any version with a known CVE
+"require-dev": {
+    "roave/security-advisories": "dev-latest"
+},
+"config": {
+    "allow-plugins": {
+        "pestphp/pest-plugin": true
+        // Add new plugins explicitly. Default-deny.
+    }
+}
+```
+
+Layered secret detection (mirrors `secrets-management` skill):
+
+```yaml
+# .github/workflows/ci.yml
+- uses: gitleaks/gitleaks-action@v2     # Layer 2 — CI scan
+- run: composer audit --abandoned=fail   # Composer-side audit
+```
+
+Layer 1 = pre-commit gitleaks hook locally. Layer 3 = GitHub Push Protection at the org/repo. See `secrets-management` skill for full setup.
+
+---
+
+## Mishandling Exceptional Conditions (OWASP 2025-A10) — Laravel-specific
+
+The new 2025 category. Common Laravel mistakes:
+
+| Anti-pattern | Why dangerous | Fix |
+|---|---|---|
+| `try { Gate::authorize(...) } catch { /* ignore */ }` | Authz fails open — caller proceeds as if allowed | Let it bubble; Laravel maps `AuthorizationException` to 403 |
+| `Render::abort` returning a 500 with full stack trace | Leaks file paths, ORM internals, env hints | Set `APP_DEBUG=false` in prod; custom `app/Exceptions/Handler.php` returns generic problem+json |
+| Webhook handler returns 500 on parse error | Provider retries forever, floods the queue | Verify signature first; on parse error log + return 200 (idempotently dropped) |
+| Partial writes when transaction rolls back partially | Money charged but order not created | `DB::transaction()` closure (auto-rollback) — see `mariadb-octane` |
+| `if (!config('feature.requireMfa')) return $user;` | Missing config = MFA bypassed | Default-deny: `if (config('feature.requireMfa', true) === false && app()->runningInConsole())` — and even then, gate behind explicit env |
+| Octane uncaught exception leaves DB in TX | Next request inherits open TX → cascading failures | `try/finally { DB::rollBack() }` or `DB::transaction()` closure (see `mariadb-octane`) |
+
+```php
+// Correct webhook reception — fail closed on signature, fail open on parse
+public function handle(Request $request): JsonResponse
+{
+    try {
+        $event = \Stripe\Webhook::constructEvent(
+            $request->getContent(),
+            $request->header('Stripe-Signature'),
+            config('services.stripe.webhook_secret'),
+        );
+    } catch (\UnexpectedValueException | \Stripe\Exception\SignatureVerificationException $e) {
+        Log::warning('[stripe] invalid signature', ['err' => $e->getMessage()]);
+        return response()->json(['error' => 'invalid signature'], 400);   // 4xx → provider stops retrying
+    }
+
+    try {
+        ProcessStripeEvent::dispatch($event->type, $event->data->object);
+    } catch (\Throwable $e) {
+        Log::error('[stripe] dispatch failed', ['event' => $event->id, 'err' => $e->getMessage()]);
+        // Acknowledge anyway — we'll reconcile from the webhook log
+    }
+    return response()->json(['status' => 'received']);
+}
+```
+
+---
+
 ## Sensitive Patterns (FORBIDDEN)
 
 | Pattern | Risk |
 |---------|------|
 | `DB::raw()` with user input | SQL Injection |
 | `{!! $userInput !!}` | XSS |
-| `md5()` / `sha1()` for passwords | Weak hashing |
+| `md5()` / `sha1()` for passwords | Weak hashing (Argon2id is the Laravel 10+ default) |
 | Dynamic code execution | RCE |
 | `unserialize()` on user data | Object injection |
 | `$request->all()` without `$fillable` | Mass assignment |
 | `env()` in runtime code | Null after config cache |
 | Static user state in services | Data leaks in Octane |
+| `composer install` with `--ignore-platform-reqs` in prod | Hides incompatible PHP/ext versions |
+| `composer install` in prod **without** `--no-scripts` | Supply-chain RCE on package post-install hooks |
+| Missing `roave/security-advisories` dev dep | Known CVE installs silently |
+| `try { ... } catch { /* nothing */ }` around authz | 2025-A10 fail-open |
+
+## See Also
+
+- `_shared/skills/security-baseline` — universal §A01–§A10 (OWASP 2021 + 2025 deltas)
+- `_shared/skills/secrets-management` — gitleaks 3-layer + OIDC + Roave
+- `_shared/skills/observability` — log redaction
+- `composer-workflow` — `audit` + `roave/security-advisories`
+- `mariadb-octane` — transaction safety in long-lived workers
+- `api-security` — Sanctum cookie SPA + CORS hardening