Skip to content

netresearch/typo3-testing-skill / skills/typo3-testing

typo3-testing

Flagged

Use when reproducing defects as failing tests, testing template or rendered output changes, confirming changes on a running TYPO3 instance, or setting up TYPO3 extension tests: unit/functional/E2E, PHPUnit 11-13, mutation testing, final-class mocks (v14), CI matrix across TYPO3 12/13/14.3 LTS, typo3-ci-workflows meta-package, CI failures. Also: transaction rollback, worker crashes, competing requests, testing-framework setup, test matrix, integration/e2e testing, coverage, test generation.

FileKindSize
SKILL.mdskill md6.8 KB
assets/.php-cs-fixer.dist.phpscript7.0 KB
assets/AGENTS.mdmarkdown5.0 KB
assets/Build/Scripts/runTests.shexecutablescript27.5 KB
assets/Build/playwright/.nvmrcother6 B
assets/Build/playwright/package.jsonmanifest535 B
assets/Build/playwright/playwright.config.tsscript1.3 KB
assets/Build/playwright/tests/playwright/accessibility/modules.spec.tsscript2.0 KB
assets/Build/playwright/tests/playwright/config.tsscript712 B
assets/Build/playwright/tests/playwright/e2e/backend-module.spec.tsscript1.9 KB
assets/Build/playwright/tests/playwright/fixtures/setup-fixtures.tsscript2.7 KB
assets/Build/playwright/tests/playwright/helper/login.setup.tsscript975 B
assets/FunctionalTests.xmlconfig1.4 KB
assets/FunctionalTestsBootstrap.phpscript1.6 KB
assets/Makefileother2.3 KB
assets/UnitTests.xmlconfig890 B
assets/UnitTestsBootstrap.phpscript2.1 KB
assets/bootstrap.phpscript1.4 KB
assets/codecov.ymlconfig1.6 KB
assets/docker/codeception.ymlconfig979 B
assets/docker/docker-compose.ymlconfig1.4 KB
assets/example-tests/ExampleAcceptanceCest.phpscript2.2 KB
assets/example-tests/ExampleFunctionalTest.phpscript2.4 KB
assets/example-tests/ExampleUnitTest.phpscript1.6 KB
assets/fixtures/README.mdmarkdown2.0 KB
assets/fixtures/be_users.csvother361 B
assets/fixtures/pages.csvother257 B
assets/fixtures/sys_category.csvother228 B
assets/fixtures/tt_content.csvother338 B
assets/github-actions-e2e.ymlconfig8.8 KB
assets/github-actions-tests.ymlconfig6.3 KB
assets/infection.json5other2.8 KB
assets/phpat.neonother330 B
assets/phpat.phpscript8.4 KB
assets/phpstan-baseline.neonother365 B
assets/phpstan.neonother1.4 KB
assets/rector.phpscript2.9 KB
checkpoints.yamlconfig61.7 KB
references/accessibility-testing.mdmarkdown7.6 KB
references/architecture-testing.mdmarkdown4.4 KB
references/asset-templates-guide.mdmarkdown3.4 KB
references/backend-module-render-verification.mdmarkdown9.7 KB
references/backend-user-access-testing.mdmarkdown9.5 KB
references/captainhook-setup.mdmarkdown2.4 KB
references/ci-cd.mdmarkdown39.5 KB
references/ci-debugging.mdmarkdown20.0 KB
references/ci-workflows-meta-package.mdmarkdown11.6 KB
references/crash-and-concurrency-testing.mdmarkdown4.8 KB
references/crypto-testing.mdmarkdown16.6 KB
references/datahandler-silent-rewrites.mdmarkdown7.2 KB
references/ddev-testing.mdmarkdown1.3 KB
references/e2e-testing.mdmarkdown53.0 KB
references/enforcement-rules.mdmarkdown5.7 KB
references/event-dispatch-testing.mdmarkdown2.8 KB
references/framework-compat-gate.mdmarkdown4.9 KB
references/functional-test-patterns.mdmarkdown11.0 KB
references/functional-testing.mdmarkdown46.3 KB
references/fuzz-testing.mdmarkdown8.6 KB
references/integration-testing.mdmarkdown14.1 KB
references/javascript-testing.mdmarkdown29.3 KB
references/live-instance-verification.mdmarkdown8.6 KB
references/mock-validity.mdmarkdown15.7 KB
references/mutation-testing.mdmarkdown36.0 KB
references/performance-testing.mdmarkdown11.2 KB
references/quality-tools.mdmarkdown25.5 KB
references/release-workflow-validation.mdmarkdown3.6 KB
references/sonarcloud.mdmarkdown18.8 KB
references/synthetic-secret-fixtures.mdmarkdown3.8 KB
references/tdd-discipline.mdmarkdown9.1 KB
references/test-environment-guards.mdmarkdown18.5 KB
references/test-runners.mdmarkdown24.6 KB
references/typo3-ci-config-patterns.mdmarkdown9.0 KB
references/typo3-v14-final-classes.mdmarkdown16.5 KB
references/unit-testing.mdmarkdown59.1 KB
scripts/generate-test.shexecutablescript6.0 KB
scripts/setup-testing.shexecutablescript6.3 KB
scripts/validate-setup.shexecutablescript4.0 KB

references/typo3-ci-config-patterns.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# TYPO3 CI Configuration Patterns

## 1. ext_emconf.php and strict_types

- `ext_emconf.php` must NOT contain `declare(strict_types=1)` — TER cannot parse it
- PHP-CS-Fixer rule `declare_strict_types => true` must exclude ext_emconf.php
- Pattern: `->notPath('ext_emconf.php')` in Finder config
- The shared `typo3-ci-workflows` config already handles this

## 2. Shared PHP-CS-Fixer config factory

Use the shared factory from `netresearch/typo3-ci-workflows` in `Build/.php-cs-fixer.php`:

```php
<?php
declare(strict_types=1);

// Build/.php-cs-fixer.php
$createConfig = require __DIR__ . '/../.Build/vendor/netresearch/typo3-ci-workflows/config/php-cs-fixer/config.php';

return $createConfig(<<<'EOF'
    Copyright header here
EOF, __DIR__ . '/..');
```

- Requires `"netresearch/typo3-ci-workflows": "^1.0"` in `require-dev`
- Benefits: centralized rules, ext_emconf.php exclusion, consistent formatting
- **TYPO3 12 compatibility**: `typo3-ci-workflows` may pull in dependencies for TYPO3 13, causing conflicts. For TYPO3 12 extensions, you may need to inline the config or ensure you use compatible dependency versions, such as `saschaegerer/phpstan-typo3: ^2.0`.

## 3. labeler.yml for TYPO3 extensions

Standard labeler config for PR auto-labeling:

```yaml
documentation:
  - changed-files:
      - any-glob-to-any-file: ['Documentation/**', '*.md']
configuration:
  - changed-files:
      - any-glob-to-any-file: ['Configuration/**', 'ext_emconf.php', 'composer.json']
tests:
  - changed-files:
      - any-glob-to-any-file: ['Tests/**', 'phpunit*.xml']
ci:
  - changed-files:
      - any-glob-to-any-file: ['.github/**']
```

## 4. Composer allow-plugins for CI dependencies

When using `typo3-ci-workflows`, fractor, or infection, add their installers to `allow-plugins`:

```json
{
    "config": {
        "allow-plugins": {
            "a9f/fractor-extension-installer": true,
            "infection/extension-installer": true,
            "captainhook/hook-installer": true
        }
    }
}
```

Verify a change to `allow-plugins`, or to dependencies that bring a plugin, with an install that loads plugins. `composer install --no-plugins`, which the CaptainHook worktree workaround in [quality-tools.md](quality-tools.md) uses, skips the allow-plugins check entirely: measured with Composer 2.11.2 and `phpstan/extension-installer` missing from `allow-plugins`, `--no-plugins` installs succeeded with and without an existing `vendor` directory, while the plain install failed with `phpstan/extension-installer contains a Composer plugin which is blocked by your allow-plugins config`. Run the check in a checkout where a plain install works (a regular clone, not a worktree that needs `--no-plugins`), from no vendor directory and no lock file; where no such checkout exists, the install in CI is the check:

```bash
rm -rf "$(composer config vendor-dir)" composer.lock
composer install --no-interaction
```

To drop a platform override, use `composer config --unset platform`. `composer config --unset platform.php` removes only the PHP entry and leaves an empty `"platform": {}` block in `composer.json`.

## 5. TYPO3 v14.3 LTS CI matrix

TYPO3 v14.3 LTS (released 2026-04-21) is the current gold standard. Use
`typo3/testing-framework:^9.5` — a single branch that supports **both v13
and v14** cores. PHPUnit constraint: `^11.2.5 || ^12.1.2 || ^13.0.2`.

### Matrix example (GitHub Actions)

```yaml
strategy:
  matrix:
    include:
      # TYPO3 14.3 LTS (default)
      - { php: '8.2', typo3: '^14.3' }
      - { php: '8.3', typo3: '^14.3' }
      - { php: '8.4', typo3: '^14.3' }
      - { php: '8.5', typo3: '^14.3' }
      # TYPO3 13.4 LTS
      - { php: '8.2', typo3: '^13.4' }
      - { php: '8.3', typo3: '^13.4' }
      - { php: '8.4', typo3: '^13.4' }
      - { php: '8.5', typo3: '^13.4' }
      # TYPO3 12.4 LTS (ELTS window approaching 2026-04-30)
      - { php: '8.2', typo3: '^12.4' }
      - { php: '8.3', typo3: '^12.4' }
```

### composer.json (v13 + v14 dual support)

```json
{
    "require": {
        "php": "^8.2",
        "typo3/cms-core": "^13.4 || ^14.3"
    },
    "require-dev": {
        "typo3/testing-framework": "^9.5",
        "phpunit/phpunit": "^11.2.5 || ^12.1.2 || ^13.0.2"
    }
}
```

### v14-specific testing notes

- **Fluid 5 strict-typing (#108148)**: ViewHelper test doubles now need
  typed args + typed `render(): string` return. Untyped custom VHs
  raise exceptions in v14 functional tests.
- **Cache interface strict-typing (#107315)**: test doubles for
  `BackendInterface`/`FrontendInterface` must match the new typed
  signatures.
- **FAL strict-typing (#106427)**: `AbstractFile::getIdentifier()` is
  gone; test doubles for `File`/`Folder` must use concrete methods.
- **Extbase argument strict-typing (#107777)**: `Argument` now enforces
  strict types; replace `setValue(mixed)` mocks.
- See `typo3-v14-final-classes.md` for the full list of v14 `final` classes
  that cannot be mocked (use interface-based doubles instead).

## 6. PHPStan across the supported-version matrix

### Verify every supported TYPO3 version locally — not just the highest installed

A green PHPStan run on the highest installed TYPO3 version can still fail CI on a
lower one. Class existence and deprecation results differ per version, e.g.
`TYPO3\CMS\Backend\Template\Components\ComponentFactory` exists only on **v14+**,
so referencing it produces "unknown class" / "returns mixed" errors on v12/v13;
conversely the `make*` docheader API (`MenuRegistry::makeMenu()`,
`Menu::makeMenuItem()`, `ButtonBar::makeLinkButton()`) is deprecated on **v14**
but not on v12/v13. A single-version local run sees only one side.

Before pushing, re-resolve to each supported version and re-run PHPStan — no
composer.json edit needed, `--with` applies a temporary constraint:

```bash
for V in '^12.4' '^13.4' '^14.3'; do
  composer update -W \
    --with "typo3/cms-core:$V" --with "typo3/cms-backend:$V" --with "typo3/cms-setup:$V" \
    --no-interaction
  composer dump-autoload -o
  composer ci:test:php:phpstan || echo "PHPStan FAILED on TYPO3 $V"
done
```

### Type-narrowing and core-stub differences: the v13 leg fails on code the v14 leg accepts

Version differences are not limited to class existence — the **resolved PHPStan
version and the core stubs differ per dependency set**, so identical code can
type-check on the `^14.x` leg and fail only on `^13.4`:

- **First-class-callable filters are narrowed inconsistently.**
  `array_filter(array_keys($fieldArray), \is_string(...))` is inferred as
  `list<string>` by the PHPStan the v14 set resolves, but stays `array` on the
  v13 set — so a downstream `implode(', ', $columns)` fails with *"Parameter #2
  \$array of function implode expects array<string>, array given"* **only in the
  v13 matrix legs**. An explicit loop narrows identically everywhere:

  ```php
  $columns = [];
  foreach (array_keys($fieldArray) as $column) {
      if (\is_string($column)) {
          $columns[] = $column;
      }
  }
  // list<string> on every PHPStan version in the matrix
  ```

- **Loosely-typed core properties differ between version stubs.**
  `DataHandler::$errorLog` is plain `array` in the v13 core, so string
  operations over it (`implode(', ', $dataHandler->errorLog)`) fail the v13
  legs. In assertions, prefer forms that need no string coercion at all:

  ```php
  $errorLog = $dataHandler->errorLog;
  self::assertSame([], $errorLog); // prints the offending entries itself on failure
  ```

Diagnostic shortcut: when **only the `^13.4` PHPStan legs are red** while
`^14.x` and the local run are green, suspect a narrowing/stub difference before
suspecting the code — and reproduce with the `--with "typo3/cms-core:^13.4"`
loop above rather than pushing blind fixes.

### Inline `@phpstan-ignore` is rejected — use neon `ignoreErrors`

`ergebnis/phpstan-rules` (in the shared `typo3-ci-workflows` config) **bans inline
`@phpstan-ignore` / `@phpstan-ignore-next-line`** — CI fails with *"Errors reported
by phpstan/phpstan should not be ignored via @phpstan-ignore, fix the error or use
the baseline instead."* This rule is NOT active in a bare local `Build/phpstan.neon`
run, so it only surfaces in CI. Put suppressions in the neon `ignoreErrors` block
instead, scoped by `path` and kept SPECIFIC (not a blanket `#Call to deprecated
method#`). For cross-version cases set `reportUnmatched: false` so an entry that
only applies to one TYPO3 version does not error on the others:

```yaml
parameters:
    reportUnmatchedIgnoredErrors: false
    ignoreErrors:
        # v14 only: the v12/v13 fallback docheader make* calls are deprecated there
        - message: '#Call to deprecated method (makeMenu|makeMenuItem|makeLinkButton)\(\)#'
          path: %currentWorkingDirectory%/Classes/Controller/MyModuleController.php
          reportUnmatched: false
        # v12/v13 only: ComponentFactory does not exist there
        - message: '#TYPO3\\CMS\\Backend\\Template\\Components\\ComponentFactory#'
          path: %currentWorkingDirectory%/Classes/Controller/MyModuleController.php
          reportUnmatched: false
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall