Phpunit Migration Test Generation

---
name: phpunit-migration-test-generation
version: 5.2.1
description: Use this skill when the user asks to generate, write, or create migration tests for a Shopware 6 migration class — phrases like "generate migration tests", "write a migration test", "create migration test", "test this migration", "test Migration1234Foo". Analyzes the source migration's SQL operations to pick an appropriate pattern (schema-add, schema-remove, data-update, config, mail template), then generates a test that runs against a real database and passes PHPStan and PHPUnit validation. Do NOT activate for unit tests (use phpunit-unit-test-writing) or integration tests of non-migration source classes (use phpunit-integration-test-generation).
user-invocable: true
context: fork
agent: test-writing:test-generator
allowed-tools: Read, Grep, Glob, Write, Edit, mcp__plugin_dev-tooling_php-tooling
---

# PHPUnit Migration Test Generation

Generate Shopware-compliant PHPUnit migration tests that pass PHPStan and PHPUnit validation.

## File Write Restrictions

Write ONLY to:
- `tests/migration/**` — Migration test files

NEVER write to:
- `src/**` — Source code (read-only)
- `tests/unit/**` — Unit tests (out of scope)
- `tests/integration/**` — Integration tests (out of scope)
- Any other directory

## Quick Start

1. Read the target migration source class
2. Analyze SQL operations to determine test pattern
3. Apply the migration test template with conditional sections
4. Validate with PHPStan and PHPUnit
5. Fix any errors and repeat
6. Generate completion report

---

## Phase 1: Validate Input

1. Verify single file provided
2. Verify file exists and is a PHP class (not interface/trait)
3. Verify path contains `Migration/V6_`
4. Verify class extends `Shopware\Core\Framework\Migration\MigrationStep`

If validation fails, return FAILED with reason.

## Phase 2: Analyze Source

Read the migration class and extract information needed for test generation. See references/source-analysis.md for detection patterns.

### Step 1: Extract Metadata

- Class name, full namespace
- Timestamp from `getCreationTimestamp()` return value
- `#[Package('...')]` attribute value — the test class carries the same value. When the migration class carries none, take the value from the nearest `src/` directory the test path mirrors, walking up until one exists and using the value its `.php` files carry. When that yields no value, emit no `#[Package]` and report that in the Phase 5 report's `Package` field (`none`, per references/output-format.md) rather than guessing a value.
- Area from namespace (`Core`, `Administration`, `Storefront`, `Elasticsearch`)
- Version from namespace (`V6_6`, `V6_7`, `V6_8`)

### Step 2: Classify SQL Operations

Read `update()` and `updateDestructive()` method bodies. Classify:
- **Schema-add**: CREATE TABLE, addColumn(), ALTER TABLE ... ADD
- **Schema-remove**: DROP TABLE, DROP COLUMN, dropColumnIfExists(), dropTableIfExists()
- **Data-update**: UPDATE, INSERT, DELETE on non-config tables
- **Config**: system_config operations
- **Mail-template**: mail_template operations

A migration may contain multiple patterns (e.g., schema-add + data-update).

### Step 3: Check updateDestructive

Determine if `updateDestructive()` has logic:
- Not overridden → no logic
- Empty body or only `parent::updateDestructive()` → no logic
- Any other statement → has logic

### Step 4: Select Traits

Based on detected patterns, select traits per references/source-analysis.md trait selection table.

## Phase 3: Generate Test

### Step 1: Determine Test Path

Mirror source path:
- `src/Core/Migration/V6_7/Migration1234Foo.php` → `tests/migration/Core/V6_7/Migration1234FooTest.php`
- `src/Administration/Migration/V6_7/Migration1234Bar.php` → `tests/migration/Administration/V6_7/Migration1234BarTest.php`

### Step 2: Apply Template

Use the migration test template at templates/migration-test.md. Include conditional sections based on Phase 2 analysis:

- **Always**: base template, testGetCreationTimestamp, setUp with Connection
- **Schema-add detected**: rollback method, schema verification test
- **updateDestructive has logic**: updateDestructive test method
- **Data-update detected**: state setup, value assertion test
- **Config detected**: config insert/preserve tests
- **Mail-template detected**: minimal no-exception test

Fill all placeholders using Phase 2 metadata.

### Step 3: Write Test File

Write to the path determined in Step 1.

## Phase 4: Validate and Fix

### Validation Loop

```
- [ ] PHPStan passes (0 errors)
- [ ] PHPUnit passes (all tests green)
- [ ] ECS passes (code style)
```

### Step 1: Run PHPStan

```json
{
  "paths": ["tests/migration/Path/To/GeneratedTest.php"],
  "error_format": "json"
}
```

### Step 2: Fix PHPStan Errors

Common migration test errors:
- Missing imports for `TableHelper`, `KernelLifecycleManager`, `Uuid`, `Defaults`
- Type mismatches in assertion arguments
- Unknown method calls on `Connection`

### Step 3: Run PHPUnit

```json
{
  "paths": ["tests/migration/Path/To/GeneratedTest.php"],
  "output_format": "result-only"
}
```

If tests fail, re-run without `output_format` to get failure details.

### Step 4: Fix Test Failures

Common migration test failures:
- Column/table already exists (rollback not working)
- Wrong timestamp value
- Missing test data setup
- Transaction not rolling back (wrong trait)

### Step 5: Run ECS Check and Fix

Check for violations, then apply fixes if needed.

### Repeat Until Pass

Loop Steps 1-5 until all validations pass. Maximum 3 iterations — after that, proceed to Phase 5 with status PARTIAL.

## Phase 5: Generate Report

For output format and examples, see references/output-format.md.

### Status Determination

| Condition | Status |
|-----------|--------|
| All validations pass | SUCCESS |
| Test generated, validation issues remain after 3 iterations | PARTIAL |
| Invalid input | FAILED |