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/ci-workflows-meta-package.md

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

# netresearch/typo3-ci-workflows Meta-Package

## What It Is

`netresearch/typo3-ci-workflows` is a Composer meta-package that bundles the full
set of dev-time tools used across all Netresearch TYPO3 extensions into one
`require-dev` entry. Instead of maintaining 10+ individual version constraints in
each extension's `composer.json`, one line brings everything in:

```bash
composer require --dev netresearch/typo3-ci-workflows
```

## What It Bundles (representative list)

| Package | Purpose |
|---|---|
| `phpunit/phpunit` (transitive via `typo3/testing-framework`) | PHPUnit test runner |
| `phpstan/phpstan` | Static analysis |
| `phpstan/phpstan-phpunit` | PHPUnit-specific rules |
| `phpstan/phpstan-strict-rules` | Strict rule set |
| `phpstan/phpstan-deprecation-rules` | Deprecation detection |
| `phpstan/extension-installer` | Auto-registers PHPStan extensions |
| `phpat/phpat` | Architecture testing |
| `saschaegerer/phpstan-typo3` | TYPO3-specific PHPStan extension |
| `infection/infection` | Mutation testing |
| `captainhook/captainhook` | Git hook automation |
| `friendsofphp/php-cs-fixer` | Code style |
| `rector/rector` | Automated refactoring |

Because `phpunit/phpunit` is transitive, **do not add a direct `phpunit/phpunit`
entry to `require-dev`** — it pins a phpunit version that may conflict with the
PHP version constraint of the extension (phpunit 12.5.8+ requires PHP >= 8.3, which
breaks the PHP-8.2 matrix cell). This holds for an extension that supports TYPO3
13.4 and 14.3 only. An extension that still supports 12.4 is the documented
exception below.

## The meta package is TYPO3 13/14 only

It cannot be installed alongside `typo3/cms-core: ^12.4`, and the reason is a
single member. `saschaegerer/phpstan-typo3` 2.x requires `typo3/cms-core
^13.4.3`, 3.x requires `^14.0`, and the last release that still supports TYPO3
12, 1.10.2, requires `phpstan/phpstan ^1.10.9` — which this package's
`phpstan/phpstan: ^2.0` excludes. Upstream dropped TYPO3 12 when it moved to
PHPStan 2, so no combination satisfies both. Composer says so directly:

```
- netresearch/typo3-ci-workflows v1.12.0 requires saschaegerer/phpstan-typo3 ^2.0 || ^3.0
- saschaegerer/phpstan-typo3[2.0.0, ..., 3.0.0] require typo3/cms-core ^13.4.3
  -> but it conflicts with your root composer.json require (^12.4).
```

Every other member is TYPO3-version-agnostic: with `saschaegerer/phpstan-typo3`
removed, the remaining 18 requirements resolve against `typo3/cms-core` 12.4.45
with `phpstan/phpstan` 2.2.14 and `phpunit/phpunit` 11.5.56 via
`typo3/testing-framework` 8.3.3.

**An extension that still supports 12.4 therefore does two things**, and both
are deliberate rather than leftovers:

1. Its CI caller removes the meta package on the legs that cannot resolve it:

   ```yaml
   remove-dev-deps: '[{"dep":"netresearch/typo3-ci-workflows","only-for":"^13.4|^14.3"}]'
   ```

   `only-for` means *keep* on these TYPO3 versions; every other matrix cell runs
   `composer remove --dev netresearch/typo3-ci-workflows` before installing.

2. It declares its dev tools directly in `require-dev` — `phpunit/phpunit`
   included — because on those legs the meta package is gone and nothing else
   brings a test runner. The constraint must not cap the version below what
   `typo3/testing-framework` already allows, or the 13.4 and 14.3 legs are held
   back by it; see the PHPUnit 13 section in
   [unit-testing.md](unit-testing.md).

   These entries look like duplicates of what the meta package provides, and
   removing them fails exactly the legs without it, with `.Build/bin/phpstan: not
   found` or `phpunit: not found` (exit 127). A local `composer update` before
   and after such a cleanup does not catch it: it resolves one cell, the one with
   the meta package. Only the CI matrix covers the legs that remove it.

Widening `saschaegerer/phpstan-typo3` to `^1.10 || ^2.0 || ^3.0` does not fix
this. It resolves only if `phpstan/phpstan`, `phpstan-strict-rules`,
`phpstan-deprecation-rules`, `phpstan-phpunit` and `ergebnis/phpstan-rules` are
opened to major 1 as well, and the ^12.4 legs then fall back to PHPStan 1.12.34,
where `level: 10` does not exist at all (`Level config file …
config.level10.neon was not found`). Those legs analyse with PHPStan 2 at level
10 today, so that is a downgrade, not a fix. Measured 2026-09-18.

## Adoption

Replace individual dev dependencies:

```json
// Before
"require-dev": {
    "phpunit/phpunit": "^11 || ^12",
    "phpstan/phpstan": "^2",
    "phpat/phpat": "^0.11",
    "infection/infection": "^0.29",
    "friendsofphp/php-cs-fixer": "^3"
}

// After
"require-dev": {
    "netresearch/typo3-ci-workflows": "^1"
}
```

## composer install --no-plugins Workaround

`captainhook/hook-installer` (bundled transitively) registers git hooks on every
`composer install`. In git worktree environments the `.git` directory is a file
(pointer), not a directory, which confuses the installer and emits warnings or
errors.

**Workaround for local development in a worktree:**

```bash
composer install --no-plugins
```

This skips all Composer plugins, including the hook installer. Git hooks are
managed by the bare repository's worktree setup instead.

Create a shell alias or Makefile target:

```makefile
composer-install-local:
	composer install --no-plugins
```

## Build/phpstan.no-plugins.neon Pattern

When running PHPStan locally **without** `phpstan/extension-installer` (e.g. after
`composer install --no-plugins`), the auto-registered extensions are absent and
PHPStan will error on unknown rules.

Create `Build/phpstan.no-plugins.neon` for this case:

```neon
# Build/phpstan.no-plugins.neon
# Use this file locally when extension-installer is inactive
# (e.g. after: composer install --no-plugins)
#
# Usage: phpstan analyse --configuration Build/phpstan.no-plugins.neon

includes:
    - phpstan.neon
    - vendor/phpstan/phpstan-phpunit/extension.neon
    - vendor/phpstan/phpstan-phpunit/rules.neon
    - vendor/phpstan/phpstan-strict-rules/rules.neon
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon
    - vendor/saschaegerer/phpstan-typo3/extension.neon

parameters:
    # Override anything set by extension-installer in the main neon
```

**Do not add these `includes:` to the main `phpstan.neon`.** When extension-installer
is active (in CI and standard `composer install`), it already registers them, and
duplicate includes cause PHPStan to exit 1 with "These files are included multiple
times".

## Reusable CI Workflow Integration

Pair the meta-package with the reusable GitHub Actions workflow:

```yaml
# .github/workflows/ci.yml
jobs:
  ci:
    uses: netresearch/typo3-ci-workflows/.github/workflows/ci.yml@<SHA>
    with:
      php-versions: '["8.2", "8.3", "8.4"]'
      typo3-versions: '["13", "14"]'
      upload-coverage: true
    secrets:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

Pin to a full 40-character SHA. Checkpoints TT-22, TT-23, TT-24, and TT-41 are
all satisfied by this single workflow call.

## Functional tests are OPT-IN — `run-functional-tests` defaults to `false`

The reusable `netresearch/typo3-ci-workflows/.github/workflows/ci.yml` gates its
functional jobs (both the SQLite job and the DB-service job) on the boolean input
`run-functional-tests`, and **its default is `false`**. A caller that never sets
it has the **entire functional job SKIPPED on every event** — pull_request,
`merge_group`, and push alike. `Functional Tests` and `Functional Tests SQLite`
show up as `skipped`, not failing, so nothing looks wrong — meanwhile the whole
`Build/FunctionalTests.xml` (every `<testsuite>` in it) never runs in CI, and
functional/backend test rot accumulates silently for months.

Turn it on explicitly:

```yaml
    with:
      run-functional-tests: true
```

**Verify** it actually runs, don't assume: after enabling, open a `merge_group`
(or PR) run and confirm the functional cells show `success`, not `skipped`
(`gh run view <id> --json jobs --jq '.jobs[] | select(.name | test("Functional")) | {name, conclusion}'`).

**Trade-offs of enabling it:**

- Functional now runs on PRs too, expanding the matrix (≈ one cell per
  PHP × TYPO3 combination) — CI gets slower.
- If your functional suite makes real outbound calls (e.g. provider-connection
  smoke tests hitting an unreachable host and waiting for a timeout), those cells
  are *slow*; mock the transport or gate such tests behind a marker.
- Enabling a job that was skipped changes its required-status-check context. While
  skipped, the job reported a single **bare** context (`ci / Functional Tests SQLite`)
  that satisfied the required check. Enabling it makes GitHub expand that into N
  **matrix** contexts (`ci / Functional Tests SQLite (8.2, ^13.4)` … `(8.5, ^14.3)`),
  so the bare required context no longer reports and PRs sit permanently `BLOCKED`
  with every visible check green. Fix: update the branch ruleset's
  `required_status_checks` (via `gh api -X PUT repos/O/R/rulesets/<id>`, or
  `gh api -X PATCH repos/O/R/branches/main/protection/required_status_checks` for
  classic branch protection) to
  replace the bare context with the matrix-expanded ones — mirror how Unit/PHPStan
  are already listed. This is also what makes the newly-enabled job actually *gate*
  merges.

## Adding a MariaDB functional leg (and its two silent traps)

The reusable `ci.yml`'s functional job runs on **one** DBMS per call, chosen by
`functional-test-db` (default `sqlite`); its two functional jobs are mutually
exclusive per call (`== sqlite` vs `!= sqlite`). To keep an extension's
MySQL-only code paths (e.g. `MATCH … AGAINST` fulltext, strict-mode inserts —
see `functional-testing.md`) exercised in CI, add a **second, narrow call** of
the reusable workflow rather than trying to run both engines in one:

```yaml
  ci-functional-mariadb:
    uses: netresearch/typo3-ci-workflows/.github/workflows/ci.yml@<SHA>  # pin to a commit SHA
    with:
      php-versions: '["8.4"]'
      typo3-versions: '["^14.3"]'
      run-functional-tests: true
      functional-test-db: mariadb
      db-image: 'mariadb:11.8'
```

Two traps that make the leg silently *not* test MariaDB, or fail to start:

- **`db-image` defaults to `mysql:9.6`.** Setting `functional-test-db: mariadb`
  alone does **not** run against MariaDB — the DB service image is a separate
  input. Without `db-image: 'mariadb:...'` the "MariaDB leg" runs on MySQL. Set
  both.
- **MariaDB images ≥ 11 used to break the reusable workflow's health check.** The
  job health-checked the DB service with a hardcoded `mysqladmin ping`; MariaDB
  dropped the `mysql*` compatibility symlinks at 11.0 and ships only
  `mariadb-admin`, so `mariadb:11.x` never turned healthy → "Failed to initialize
  container". Fixed in [typo3-ci-workflows#174](https://github.com/netresearch/typo3-ci-workflows/pull/174):
  the health command now tries both binaries. A caller that still pins
  `mariadb:10.11` for this reason can move to a current series — but only if it
  references the workflow `@main`; a call pinned to an older SHA carries the old
  health check with it.
- **Pick a series MariaDB still supports.** Per the
  [maintenance policy](https://mariadb.org/about/#maintenance-policy) those are
  10.11 (until 2028-02), 11.4 (2029-05), 11.8 (2028-06) and 12.3 (2029-06).
  12.0–12.2 are rolling releases, not LTS, and Docker Hub stopped rebuilding
  `mariadb:12.2` in May 2026 — a tag that looks current and is not.

Also expect the enabled leg to surface **pre-existing** MySQL-strict-mode bugs
in an e2e-backend suite that has only ever run on SQLite — file those separately
and, if needed, scope the leg to `--testsuite functional` (via
`functional-test-command`) until they're fixed, then drop the scoping.
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