netresearch/typo3-testing-skill / skills/typo3-testing
typo3-testing
FlaggedUse 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.
references/test-runners.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Test Runners and Orchestration
The `runTests.sh` script is the **required** TYPO3 pattern for test orchestration, following TYPO3 core conventions.
## Requirements
Extensions **MUST** have a Docker-based `Build/Scripts/runTests.sh` that:
1. Uses **TYPO3 core-testing images** (`ghcr.io/typo3/core-testing-php*`)
2. Supports **multiple databases** (SQLite default, MariaDB, MySQL, PostgreSQL)
3. Supports **multiple PHP versions** (8.2, 8.3, 8.4, 8.5)
4. Works in **CI environments** (auto-detects non-TTY)
5. Handles **database container orchestration** for functional tests
6. Uses **--user flag** on Linux to prevent root-owned files
## runTests.sh and Composer Scripts Are Two Entry Points
`runTests.sh` does not have to be the only way in. Composer scripts that call
the tools directly (`"ci:test:php:unit": "phpunit -c Build/phpunit.xml"`) are
standard too: the TYPO3 reference extension TYPO3BestPractices/tea names them
`check:tests:unit` and calls `phpunit` from them, and its `runTests.sh` starts
`.Build/bin/phpunit` inside a core-testing container. Neither calls the other.
The composer scripts run the suite in the current PHP; `runTests.sh` runs it in
the PHP and database version you pick. `runTests.sh` stays required (TT-50).
TT-55 accepts `ci:test:php:unit`, `ci:test:php:functional`,
`check:tests:unit`, `check:tests:functional` or any script that calls
`runTests.sh`; TT-62 additionally wants a unit (or generic `test`) script, so
define the unit one even where a functional script already satisfies TT-55.
The commands in this reference use `runTests.sh`, which works for every PHP
and database version; a composer script is the shortcut for the PHP you are
running.
## Running from a non-interactive shell (agent, cron, CI step without a TTY)
A third-party extension's `runTests.sh` may invoke the container with `-it`
unconditionally. From a shell with no controlling terminal it then aborts
before any test runs:
```
cannot attach stdin to a TTY-enabled container because stdin is not a terminal
```
Wrap the call in a pseudo-TTY with `script`, which satisfies `-it` without an
interactive terminal:
```bash
script -qec "./Build/Scripts/runTests.sh -s composerInstall" /dev/null
script -qec "./Build/Scripts/runTests.sh -s unit Tests/Unit/Foo/BarTest.php" /dev/null
```
The Netresearch template runner detects a missing TTY and needs no wrapper; the
wrapper is for third-party runners that do not (verified 2026-10-08 against
`georgringer/news_importicsxml`).
## Template
Use `assets/Build/Scripts/runTests.sh` as starting point. Customize:
1. `NETWORK` variable: Replace `my-extension` with your extension key
2. `COMPOSER_ROOT_VERSION`: Set to your extension version
3. `TYPO3_BASE_URL`: Set the TYPO3 URL for E2E tests (default: `http://localhost:8080`)
## Basic Usage
```bash
# Show help
./Build/Scripts/runTests.sh -h
# Run unit tests (default)
./Build/Scripts/runTests.sh -s unit
# Run functional tests with SQLite (fastest, no container)
./Build/Scripts/runTests.sh -s functional
# Run functional tests in parallel (2-3x faster)
./Build/Scripts/runTests.sh -s functionalParallel
# Run functional tests with MariaDB
./Build/Scripts/runTests.sh -s functional -d mariadb
# Run with specific PHP version
./Build/Scripts/runTests.sh -p 8.3 -s unit
# Run E2E tests (PHP built-in server + MySQL container, NOT DDEV)
./Build/Scripts/runTests.sh -s e2e
# Run quality tools
./Build/Scripts/runTests.sh -s lint
./Build/Scripts/runTests.sh -s phpstan
./Build/Scripts/runTests.sh -s cgl
```
## Script Options
| Option | Description | Values |
|--------|-------------|--------|
| `-s` | Test suite | `unit`, `functional`, `functionalParallel`, `e2e`, `lint`, `phpstan`, `cgl`, `rector`, `fuzz`, `mutation`, `composer` (runs a composer command, e.g. `-s composer dump-autoload`) |
| `-d` | Database | `sqlite` (default), `mariadb`, `mysql`, `postgres` |
| `-i` | DB version | mariadb: 11.8 (accepted: 10.11, 11.4, 11.8, 12.3), mysql: 8.0, postgres: 16 |
A MariaDB version that has left support is mapped onto the LTS of its own series and the substitution is printed — `-i 10.5` runs 10.11, `-i 12.2` runs 12.3 — so an old call in a Makefile keeps working instead of failing. `DBMS_VERSION_EXACT=1` runs the requested version verbatim, for reproducing a bug on the engine a customer actually operates.
| `-p` | PHP version | `8.2`, `8.3`, `8.4`, `8.5` |
| `-x` | Enable Xdebug | |
| `-n` | Dry-run | For cgl, rector |
| `-u` | Update images | |
## Test Parallelization
### E2E Tests (Playwright)
Playwright parallelizes by spec file. Configure in `playwright.config.ts`:
```typescript
export default defineConfig({
fullyParallel: false, // Tests within file run sequentially (safer)
workers: process.env.CI ? 4 : undefined, // CI: fixed, Local: half of CPUs
});
```
**Performance**: 3x speedup (3.8min → 1.3min for 111 tests)
**Note**: Workers are capped at the number of spec files when `fullyParallel: false`.
### Functional Tests (functionalParallel)
Uses `xargs -P` to run test files concurrently with SQLite:
```bash
# CI: 4 parallel jobs for predictable resource usage
# Local: half of available CPUs
if [ "${CI}" == "true" ]; then
PARALLEL_JOBS=4
else
PARALLEL_JOBS="$(($(nproc) + 1) / 2)"
fi
find Tests/Functional -name '*Test.php' | xargs -P${PARALLEL_JOBS} ...
```
**Performance**: 2-3x speedup (24s → 10s for 62 tests). On CI's slower shared runners the win is larger — an 8-11min serial functional cell drops to ~2.5min.
**Why one process per file is collision-free (and works on MariaDB too):** the testing-framework derives BOTH the test instance directory AND the database name from the same per-class identifier — `substr(sha1(static::class), 0, 7)` (`FunctionalTestCase::getInstanceIdentifier`), used as `functional-<id>/` for the SQLite file and as `<originalDatabaseName>_ft<id>` for MySQL/MariaDB (`FunctionalTestCase.php`, the non-sqlite branch). So each **file** gets its own database on a shared server — no CREATE race, safe at `-P4` well under a default `max_connections` of 151. Shard by **file**, never by test *method* (`--filter`): several methods of one class share one instance.
**Glob every suite `FunctionalTests.xml` declares, not just `Tests/Functional`.** If the config runs a second testsuite (e.g. an `e2e-backend` directory `Tests/E2E/Backend/`), a sharder that globs only `Tests/Functional` **silently drops it** — the classes never run and CI stays green. Match the config:
```bash
find Tests/Functional Tests/E2E/Backend -name '*Test.php' | xargs -P${PARALLEL_JOBS} ...
```
**Force `XDEBUG_MODE=off` on non-coverage parallel runs.** If setup-php installed Xdebug as the coverage driver, it stays in coverage mode and taxes runtime ~1.6x **even when no coverage is collected** (measured: 61s vs 37.6s on the same 126-test subset). Only enable it on the serial coverage run.
**Requirement**: SQLite with tmpfs (or MySQL/MariaDB, per above) for isolated databases per test file.
### Unit Tests
Unit tests are typically fast enough (<1s) that parallelization overhead would be counterproductive. PHPUnit's native parallelization (ParaTest) doesn't support PHPUnit 12 yet.
## Gotcha: Single-Process PHPUnit OOMs on Large Functional Suites
Running the whole functional suite through plain single-process PHPUnit (`vendor/bin/phpunit -c phpunit.xml.dist`, no parallelization) accumulates every test's compiled DI container and TYPO3 bootstrap in one PHP process. On a few hundred functional tests this exhausts `memory_limit` — typically a fatal deep in Symfony's container dumper:
```
PHP Fatal error: Allowed memory size of 536870912 bytes exhausted ...
in .../symfony/dependency-injection/Dumper/PhpDumper.php
```
The symptom is misleading: progress dots stop part-way with **no PHPUnit summary line**, and a `timeout`/wrapper around the call may still report exit 0 — so it looks like "passed" when it actually died mid-run.
**Fix:** run the suite the way the project's entry point does — in **isolated worker processes**, one slice per worker, so container compilation never accumulates:
```bash
./Build/Scripts/runTests.sh -s functionalParallel # xargs -P, one phpunit process per test file
# or, for a paratest-based project entry point:
composer test
```
Reserve plain `phpunit --filter=SomeClass` for a single class. (This is the concrete reason behind Best Practice "Single Entry Point — all tests via `runTests.sh`, not direct PHPUnit".)
## Gotcha: A `--filter` That Matches Nothing Exits 0
PHPUnit treats "no test matched your filter" as a successful run. The output is
```
PHPUnit 10.5.63 by Sebastian Bergmann and contributors.
...
No tests executed!
```
and the exit code is **0**. Read only the status and a filter typo is
indistinguishable from a green suite — which is worse than a red one, because
the change it was meant to cover is now believed to be tested.
The filter matches the **test name**, which for a data-provider case is
`TestClass::testMethod with data set "<key>"` — the key the provider returned,
not a file path. A provider that keys its sets by a directory name gives keys
like `table`, not `markdown-rendering/table`, so the longer, more specific
string matches nothing:
```bash
vendor/bin/phpunit --testsuite=integration --filter 'markdown-rendering/table'
# No tests executed! exit 0
vendor/bin/phpunit --testsuite=integration --filter 'table'
# 7 / 7 (100%) exit 0
```
**Accept a filtered run on its test count, never on its exit code.** The
summary line (`Tests: 7, Assertions: 66`) or the progress line (`....... 7 / 7`)
is the evidence; `OK (7 tests)` and `No tests executed!` both exit 0. This is
the same failure shape as the OOM above — a run that produced no verdict
reporting success — and it bites hardest in the red-green loop, where a
mistyped filter makes the red step look green and the fix gets written against
a test that never ran.
## Gotcha: An Unknown `--testsuite` Exits 0 Too
A suite name that the configuration does not define behaves the same way:
PHPUnit prints `No tests executed!` and exits **0** (measured with PHPUnit
10.5.67 and 11.5.58). Nothing validates the name, so a Makefile target, a
Composer script or a CI step that passes `--testsuite architecture` against a
`phpunit.xml` defining only `unit` and `functional` stays green while running
nothing, for as long as nobody reads its output.
Make the exit code say it. Set `failOnEmptyTestSuite="true"` on the `<phpunit>`
element (or pass `--fail-on-empty-test-suite`); with it, both the unknown suite
and the non-matching `--filter` above exit **1**, while a normal run still exits
0 (same versions). Then check every suite name used in scripts, Makefiles and
workflow files against the `<testsuite name="…">` entries of the configuration
they run with.
## Database Support
### SQLite (Default)
- **Fastest**: No container startup
- **CI-friendly**: No external services needed
- **Parallelizable**: Each test file gets isolated DB
```bash
./Build/Scripts/runTests.sh -s functional # Uses SQLite
```
### MariaDB/MySQL
- Required for MySQL-specific syntax
- Mark incompatible tests with `#[Group('not-sqlite')]`
```bash
./Build/Scripts/runTests.sh -s functional -d mariadb -i 11.8
./Build/Scripts/runTests.sh -s functional -d mysql -i 8.0
```
### PostgreSQL
- For PostgreSQL compatibility testing
```bash
./Build/Scripts/runTests.sh -s functional -d postgres -i 16
```
## E2E Test Integration
E2E tests use a PHP built-in server + MySQL container. **Do NOT use DDEV for tests.**
In CI, use the reusable `e2e.yml` workflow from `netresearch/typo3-ci-workflows`.
```bash
# Run E2E tests locally (starts PHP server + DB automatically)
./Build/Scripts/runTests.sh -s e2e
# With custom URL (e.g., if TYPO3 is already running)
TYPO3_BASE_URL=http://localhost:8080 ./Build/Scripts/runTests.sh -s e2e
```
### Playwright Docker Image
Use the official Playwright image with pre-installed browsers:
```bash
IMAGE_PLAYWRIGHT="mcr.microsoft.com/playwright:v1.57.0-noble"
```
**Important**: Keep Playwright versions in sync between:
- `package.json`: `"@playwright/test": "^1.57.0"`
- `runTests.sh`: `IMAGE_PLAYWRIGHT="mcr.microsoft.com/playwright:v1.57.0-noble"`
## Helper Functions
### waitFor (TCP port)
Wait for a service to be available on a TCP port:
```bash
waitFor() {
local HOST=${1}
local PORT=${2}
# Uses netcat to check port availability
# Retries up to 10 times with 1 second delay
}
# Usage
waitFor mariadb-container 3306
```
### waitForHttp (HTTP endpoint)
Wait for an HTTP endpoint to respond:
```bash
waitForHttp() {
local URL=${1}
local MAX_ATTEMPTS=${2:-30}
# Uses wget to check HTTP availability
}
# Usage: Wait for mock OAuth server
waitForHttp "http://mock-oauth-container:8080/.well-known/openid-configuration"
```
## Mock Services
### Mock OAuth Server
For testing OAuth integration without real providers:
```bash
IMAGE_MOCK_OAUTH="ghcr.io/navikt/mock-oauth2-server:3.0.1"
${CONTAINER_BIN} run --rm -d --name mock-oauth-${SUFFIX} --network ${NETWORK} \
-e SERVER_PORT=8080 \
-e JSON_CONFIG_PATH=/config/config.json \
-v "${ROOT_DIR}/.ddev/mock-oauth:/config:ro" \
${IMAGE_MOCK_OAUTH}
waitFor mock-oauth-${SUFFIX} 8080
# Pass URL to tests
-e MOCK_OAUTH_URL="http://mock-oauth-${SUFFIX}:8080"
```
## PHP Performance Optimization
Enable opcache and JIT for faster test execution:
```bash
PHP_OPCACHE_OPTS=(-d opcache.enable_cli=1 -d opcache.jit=1255 -d opcache.jit_buffer_size=128M)
```
The template keeps the options in an array: `"${PHP_OPCACHE_OPTS[@]}"` inside a `COMMAND=(...)` array, `${PHP_OPCACHE_OPTS[*]}` inside a command string for `/bin/sh -c`. A copy of an older template that defines the variable as a string uses `${PHP_OPCACHE_OPTS}` instead.
**Note**: Disable JIT for coverage (`-d opcache.jit=off`) as it's incompatible with Xdebug.
**Functional suites: run WITHOUT JIT.** Core-testing container PHP builds (seen on 8.3 and 8.5 images) with `opcache.jit=1255` can segfault **silently** during functional bootstrap — exit 139, no PHP error, dies between PHPUnit's "Configuration:" line and the first test, triggered by the *shape* of perfectly valid source (a plain property+getter on an Extbase entity flipped it). Functional suites are IO-bound, JIT gains nothing: use a separate `PHP_FUNCTIONAL_OPTS=(-d opcache.enable_cli=1)` (no JIT) for functional/functionalParallel and keep JIT for phpstan/cgl/unit. Diagnosis pattern: fast probe via `runTests.sh -s functional -- --filter OneTestClass`, stash-bisect per candidate file, cross-check with `-d opcache.jit=off`.
## Permission Handling
### Linux --user Flag
On Linux, containers run as the host user to prevent root-owned files:
```bash
if [ $(uname) != "Darwin" ]; then
USERSET="--user $(id -u)"
fi
```
### Root-owned Files Detection
For E2E tests, detect and warn about root-owned node_modules:
```bash
if [ "$(find node_modules -maxdepth 1 -user root 2>/dev/null | head -1)" ]; then
echo "Error: node_modules contains root-owned files."
echo "Please remove: sudo rm -rf node_modules"
exit 1
fi
```
## Makefile Integration
Create a `Makefile` for convenient shortcuts:
```makefile
RUNTESTS = Build/Scripts/runTests.sh
.PHONY: test unit functional lint phpstan cs fix ci e2e
test: unit
unit:
$(RUNTESTS) -s unit
functional:
$(RUNTESTS) -s functional
functional-fast:
$(RUNTESTS) -s functionalParallel
e2e:
$(RUNTESTS) -s e2e
lint:
$(RUNTESTS) -s lint
phpstan:
$(RUNTESTS) -s phpstan
cs:
$(RUNTESTS) -s cgl -n
fix:
$(RUNTESTS) -s cgl
ci: lint cs phpstan unit functional
```
## CI/CD Integration
### GitHub Actions (Recommended)
```yaml
name: CI
on: [push, pull_request]
jobs:
tests:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
php: ['8.2', '8.3', '8.4']
suite: ['unit', 'functional']
database: ['sqlite']
include:
- php: '8.4'
suite: 'functional'
database: 'mariadb'
steps:
- uses: actions/checkout@v4
- name: Run ${{ matrix.suite }} tests
run: |
Build/Scripts/runTests.sh \
-s ${{ matrix.suite }} \
-p ${{ matrix.php }} \
-d ${{ matrix.database }}
quality:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: Build/Scripts/runTests.sh -s lint
- run: Build/Scripts/runTests.sh -s phpstan
- run: Build/Scripts/runTests.sh -s cgl -n
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ddev/github-action-setup-ddev@v1
- run: ddev start
- run: Build/Scripts/runTests.sh -s e2e
```
## Fast setup in a fresh worktree (rsync a known-good `.Build`)
A newly created worktree has no `.Build/` (it's gitignored), so `runTests.sh`
fails with `Could not open input file: .Build/bin/phpunit`. A fresh `composer
install` works but is slow, and on WSL2 a fresh resolution can segfault the
full-config PHPUnit run (flaky exit 139). Faster and stable: rsync a **known-good**
`.Build` from a sibling worktree, then regenerate the autoloader so the new
worktree's own classes are registered.
```bash
rsync -a --delete ../<sibling-worktree>/.Build/ ./.Build/
Build/Scripts/runTests.sh -s composer dump-autoload # register new PSR-4 classes
Build/Scripts/runTests.sh -s unit
```
Only reuse a `.Build` whose resolved dependency versions are compatible with this
branch (e.g. the same `nr-llm` minor). If they differ, the reused vendor can carry
a different API than your code targets — a symptom is a value object's constructor
requiring an argument your code/tests omit (signatures drift across minors).
Verify the constructor at the **resolved** version, not the library's `main`, and
run the static analyzer **after** the tests are written (test files are analyzed
too). CI remains authoritative — treat the rsynced `.Build` as a local fast path,
not a substitute for the CI matrix.
### A `.Build` also pins a PHP version, which can make one suite unrunnable
Compatibility is not only about library versions. `composer install` writes
`.Build/vendor/composer/platform_check.php` from the PHP it resolved under, and
that file **fatals** rather than warns when the runtime is older:
```
Fatal error: Uncaught RuntimeException: Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.4.1". You are running 8.2.30.
```
That matters for any suite whose gate pins a *lower* PHP than the one the
`.Build` was resolved under. The usual case is Rector: its PHPUnit rule set
activates from the phpunit version composer installed, so the gate is pinned low
in CI (`rector-php-version: '8.2'`) — and in a worktree whose `.Build` came from
a PHP 8.4 resolve, `runTests.sh -s rector -n -p 8.2` cannot start at all. The
suite is not failing; it never ran.
Recognise it by the message: a `platform_check.php` fatal is an environment
mismatch, never a code finding. Then pick one:
- keep a second `.Build` resolved at the pinned version for that one gate, or
- accept CI as the only place that gate runs — and **say so** when reporting
which gates were run locally, rather than listing it as green.
Silently skipping it is the failure mode: the gate is then first evaluated in
CI, on a pushed branch, which costs a round-trip per finding.
## Troubleshooting
### TTY Errors
Script auto-detects non-TTY environments. If issues persist:
```bash
CI=true ./Build/Scripts/runTests.sh -s unit
```
### Database Connection Errors
```bash
# Check container is running
docker ps
# Use SQLite to rule out DB issues
./Build/Scripts/runTests.sh -s functional -d sqlite
```
### SQLite functional tests fail with "unable to open database file"
The SQLite functional run fails with `unable to open database file` when the tmpfs
over the SQLite directory is not writable for the container user. `runTests.sh` runs
the PHP container as the host user (`--user $(id -u)`) and creates the directory on
the host with `mkdir -p` before the run. A tmpfs mounted over an existing directory
takes that directory's mode, 0755, and belongs to root, so the host user cannot write
to it. A tmpfs over a path that does not exist yet comes up as 1777. Measured on
docker-ce 29.8.1 (not rootless):
| Directory before the run | Mount options | tmpfs | Container user writes |
|---|---|---|---|
| created by the host user | `rw,noexec,nosuid` | `755 root` | no |
| created by the host user | `rw,noexec,nosuid,mode=1777` | `1777 root` | yes |
| missing | either | `1777 root` | yes, but see below |
Dropping the `mkdir -p` is not a fix: the daemon then creates the missing mount point
and its parents on the host as root, and the container user can no longer create the
test instance directories next to it in `typo3temp/var/tests/`.
Fix: keep the `mkdir -p` and add `,mode=1777` (world-writable, sticky, like `/tmp`)
to every SQLite `--tmpfs` option in `Build/Scripts/runTests.sh`:
```diff
- --tmpfs ${CORE_ROOT}/.Build/Web/typo3temp/var/tests/functional-sqlite-dbs/:rw,noexec,nosuid
+ --tmpfs ${CORE_ROOT}/.Build/Web/typo3temp/var/tests/functional-sqlite-dbs/:rw,noexec,nosuid,mode=1777
```
The `assets/Build/Scripts/runTests.sh` template carries the option; copies taken from
it before that change still need the edit.
### SQLite tmpfs on a directory the tests never use
The tmpfs only helps when it sits on the directory the testing-framework writes to:
`<TYPO3_PATH_ROOT>/typo3temp/var/tests/functional-sqlite-dbs/`. For an extension,
`typo3/cms-composer-installers` sets `TYPO3_PATH_ROOT` to `extra.typo3/cms.web-dir`
from `composer.json`, and to `public` when that key is absent. Paths are
case-sensitive, so a `runTests.sh` that mounts `.Build/web` in an extension whose
`web-dir` is `.Build/Web` mounts an unused directory. The databases then land on the
bind mount, and the tmpfs, including `mode=1777`, has no effect.
The template therefore reads `web-dir` from `composer.json` with PHP inside the test
image and mounts the tmpfs on `<web-dir>/typo3temp/var/tests/functional-sqlite-dbs/`
for `functional` (with `-d sqlite`), `functionalParallel` and `functionalCoverage`.
It resolves the value as the installer does: backslashes become slashes, `.` and `..`
are resolved, `null` means the composer root, and a value outside the composer root is
reset to `public` with a warning. A value the installer would accept but that still
points outside the extension stops the run.
To check an older copy, look for a hardcoded web directory in its `--tmpfs` options
and compare it with `extra.typo3/cms.web-dir`.
### Root-owned Files
```bash
# Remove root-owned files (requires sudo)
sudo rm -rf node_modules .Build
```
### Update Images
```bash
./Build/Scripts/runTests.sh -u
```
## Best Practices
1. **SQLite First**: Use SQLite for most functional tests (fastest)
2. **Parallel Tests**: Use `functionalParallel` for faster CI
3. **Matrix Testing**: Test all supported PHP versions in CI
4. **Group Incompatible Tests**: Use `#[Group('not-sqlite')]` for DB-specific tests
5. **Single Entry Point**: All tests via `runTests.sh`, not direct PHPUnit
6. **Makefile Shortcuts**: Provide `make test`, `make ci` for convenience
7. **Update Images**: Run `-u` periodically to get latest TYPO3 images
8. **Keep Versions Synced**: Playwright versions in package.json and runTests.sh
## Gotcha: `-s unit` Green ≠ Safe When You Touch a Shared Type
`./Build/Scripts/runTests.sh -s unit` covers **only** `Tests/Unit/`. When you
change a **widely-consumed** type — a shared value object, DTO, enum, or a
method on a public service interface — its consumers and their assertions live
in the **functional** suite (and integration/e2e), which `-s unit` never runs.
A green unit run then hides a real break, and it surfaces later in CI or a
reviewer's comment instead of on your machine. (Real case: a change to a
`ToolSpec` value object passed `-s unit` locally but broke a functional test
asserting the old shape — caught by CI + the PR bot, not the local unit run.)
Before pushing a change to a shared type:
```bash
# Find who depends on it, then run the suites that exercise them.
# Use -e per pattern (portable across GNU/BSD grep; escaped \| is not).
grep -rn -e 'YourValueObject' -e '->yourChangedMethod' Classes/ Tests/
./Build/Scripts/runTests.sh -s unit
./Build/Scripts/runTests.sh -s functional # the assertions on the old shape live here
```
If the extension's CI runs functional tests (it should — a functional job that
is silently skipped is its own bug), treat "did I run the same suites CI will?"
as the pre-push checklist, not "is unit green?".
## Resources
- [TYPO3 Tea Extension](https://github.com/TYPO3BestPractices/tea) - Reference implementation
- [TYPO3 Core Testing](https://github.com/typo3/typo3) - Core approach
- [typo3/core-testing images](https://github.com/typo3/core-testing) - Official images
- [nr-vault](https://github.com/netresearch/t3x-nr-vault) - Reference with all patterns
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |