git:20260327.4812567 to git:20260506.f690756

52 added, 58 removed. Audit A to A.

---

name: typo3-testing

- description: "Use when setting up TYPO3 extension test infrastructure, writing unit/functional/E2E tests, configuring PHPUnit, mutation testing, mocking, CI/CD test pipelines, or debugging CI failures. Also triggers on: ensure proper testing, test matrix, integration testing, e2e testing, coverage, test generation."

+ description: "Use when setting up TYPO3 extension test infrastructure, writing unit/functional/E2E tests, configuring PHPUnit 11/12/13, mutation testing, mocking final classes (v14), CI/CD matrix across TYPO3 12/13/14.3 LTS, dev-dependency consolidation via typo3-ci-workflows meta-package, or debugging CI failures. Also triggers on: testing-framework setup, ensure proper testing, test matrix, integration testing, e2e testing, coverage, test generation."

---

# TYPO3 Testing Skill

- Scripts and references for TYPO3 extension testing.

+ ## Assessment-First Rule

+ **When enhancing an existing test suite** (not from scratch), run FIRST:

+ ```bash

+ automated-assessment typo3-testing

+ ```

+ > Install other skills (e.g. `typo3-conformance`, `enterprise-readiness`) for broader coverage.

+ Generates a gap report from 73+ checkpoints (PHPUnit, PHPStan, runTests.sh, CaptainHook, architecture, mutation, CI matrix, coverage).

+ **Use the report as the task list.** Resolve mechanical failures before manual test writing.

+ ### Applies

+ - "enhance/improve/strengthen tests", "increase coverage/mutation"

+ - "enterprise grade", "A+ testing", "fix all findings"

+ ### Does NOT Apply

+ - From scratch, writing a specific test, debugging a failure

+ ---

+ References for TYPO3 extension testing.

## Test Type Selection

| Type | Use When | Speed |

|------|----------|-------|

| **Unit** | Pure logic, no DB, validators, utilities | Fast |

| **Functional** | DB interactions, repositories, controllers | Medium |

| **Architecture** | Layer constraints, dependency rules (phpat) | Fast |

| **E2E (Playwright)** | User workflows, browser, accessibility | Slow |

| **Integration** | HTTP client, API mocking, OAuth flows | Medium |

| **Mutation** | Test quality verification, 70%+ coverage | CI/Release |

## runTests.sh - Mandatory

- **`Build/Scripts/runTests.sh` is mandatory** for all Netresearch TYPO3 extensions. It must be executable and support `-s` (suite) and `-p` (PHP version) flags. CI and local dev must use this script or the same `.Build/bin/` tool paths.

+ `Build/Scripts/runTests.sh` is mandatory. Must be executable, support `-s` (suite) and `-p` (PHP version).

## Git Hooks

- Verify: `ls captainhook.json .git/hooks/pre-commit 2>/dev/null || echo "Run: composer install"` (see `references/captainhook-setup.md`)

+ Netresearch default: `Build/captainhook.json` (declared in composer.json `extra.captainhook.config`). Verify: `ls Build/captainhook.json .git/hooks/pre-commit 2>/dev/null` (see `references/captainhook-setup.md`).

- ## Setup and Running Tests

+ ## Commands

```bash

- # Setup

- <skill-dir>/scripts/setup-testing.sh [--with-e2e] # Initialize testing

- <skill-dir>/scripts/validate-setup.sh # Validate existing setup

- <skill-dir>/scripts/generate-test.sh <Type> <Class> # Generate test file

+ # Setup (from skill dir)

+ scripts/setup-testing.sh [--with-e2e]

+ scripts/validate-setup.sh

+ scripts/generate-test.sh <Type> <Class>

- # Run tests (always via runTests.sh)

- Build/Scripts/runTests.sh -s unit # Unit tests

- Build/Scripts/runTests.sh -s functional # Functional tests

- Build/Scripts/runTests.sh -s phpstan # Static analysis

- Build/Scripts/runTests.sh -s cgl # Coding guidelines

- Build/Scripts/runTests.sh -s mutation # Mutation testing

- Build/Scripts/runTests.sh -s ci # Full CI suite

+ # Run (always via runTests.sh)

```

- After modifying a test, **always verify** it fails before the fix and passes after.

+ Verify tests fail before fix, pass after. Bug fixes use the strict TDD loop in `references/tdd-discipline.md` — no "tested/verified" claims without pasted output.

## Scoring Requirements

- | Criterion | Requirement |

- |-----------|-------------|

- | Unit tests | Required, 70%+ coverage |

- | Functional tests | Required for DB operations |

- | Architecture tests | **phpat required** for full points |

- | PHPStan | Level 10 (max) |

- ## References

- | Reference | Topic |

- |-----------|-------|

- | `unit-testing.md` | UnitTestCase, mocking, FakeClock |

- | `functional-testing.md` | FunctionalTestCase, CSV fixtures, **TSFE limitations** |

- | `functional-test-patterns.md` | PHPUnit 10+ migration, container reset |

- | `integration-testing.md` | PSR-18 mocking, OAuth flows |

- | `e2e-testing.md` | Playwright, Page Object Model |

- | `ddev-testing.md` | Local multi-version matrix |

- | `test-runners.md` | runTests.sh, Docker orchestration |

- | `architecture-testing.md` | phpat, layer constraints |

- | `ci-debugging.md` | **Multi-version CI failure analysis** |

- | `ci-cd.md` | GitHub Actions, GitLab CI |

- | `quality-tools.md` | PHPStan, PHP-CS-Fixer, Rector |

- | `mutation-testing.md` | Infection, MSI |

- | `typo3-v14-final-classes.md` | Interface extraction, mock strategies |

- | `javascript-testing.md` | Jest, frontend testing |

- | `captainhook-setup.md` | CaptainHook git hooks for TYPO3 |

- | `enforcement-rules.md` | E2E CI rules, troubleshooting |

- All references in `references/` directory.

- ### Explicit Content Triggers

+ Unit tests required (70%+ coverage). Functional tests required for DB operations. **phpat required** for architecture points. PHPStan level 10.

- For CI test failures across TYPO3 versions, load `references/ci-debugging.md`.

+ ## References (in `references/`, `.md` implied)

- For functional tests with frontend context (parseFunc, typoLink, TSFE), load `references/functional-testing.md`.

- ## External Resources

+ ### Content Triggers

- - [TYPO3 Testing Documentation](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Testing/)

- - [Tea Extension](https://github.com/TYPO3BestPractices/tea) (reference implementation)

- - [phpat documentation](https://github.com/carlosas/phpat)

- - [Infection PHP documentation](https://infection.github.io/)

- - [DDEV documentation](https://ddev.readthedocs.io/)

+ - CI failures across TYPO3 versions → `ci-debugging.md`

+ - Functional tests with TSFE context → `functional-testing.md`

+ - Mock failures across dependency versions → `mock-validity.md`

+ - Image/extension tests, `Environment::initialize`, `NormalizedParams` TypeError, `backupGlobals` → `test-environment-guards.md`

+ - Event dispatcher testing with try/catch → `event-dispatch-testing.md`

+ - Meta-package, typo3-ci-workflows, no-plugins → `ci-workflows-meta-package.md`

+ - Fake secrets, push-protection, cs-fixer concat → `synthetic-secret-fixtures.md`

+ - Burned tag, validate before tagging → `release-workflow-validation.md`

- ---

+ ## Links

- > **Contributing:** https://github.com/netresearch/typo3-testing-skill

+ [TYPO3 Testing Docs](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Testing/) |

+ [Tea Extension](https://github.com/TYPO3BestPractices/tea) |

+ [phpat](https://github.com/carlosas/phpat) |

+ [Infection](https://infection.github.io/)