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/live-instance-verification.md

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

# Verifying a Change on a Running Instance

A green suite proves the code paths the tests reach. It does not show the page.
A backend module, a content element's backend preview or a rendered frontend
page is confirmed only after somebody looked at it in a running TYPO3 instance.
This file says when that look is owed, which tool takes it, and what the report
carries. It does not replace a committed test: a check that has to stay belongs
in `e2e-testing.md` as a Playwright spec.

## When the look is owed

- A template, a backend module, a content element or its backend preview changed.
- A bug report describes what a person sees, and the fix is declared done.
- A ticket is handed over for acceptance and needs a screenshot as evidence.

## Rules

1. **The real running instance, never a hand-built harness.** A local DDEV or
   Compose instance, or a staging system. Name the instance and its TYPO3
   version next to each screenshot.
2. **The final state.** Look after the cache flush, the deploy or the asset
   build that the change needs. A look taken before any of these describes the
   old page.
3. **Realistic data.** An empty list, a one-word title or a page without content
   hides overflow and wrapping defects. Measure the failure signal
   (`scrollWidth > clientWidth`, a console error, an HTTP status), not "it
   rendered".
4. **Read only on shared or production instances.** Creating records, scheduler
   tasks or users needs the human's go first, and the report says the database
   is shared.
5. **No password in the context.** A password typed through a browser tool
   lands in the transcript. Fill it from an environment variable inside a
   script, or log in by script and hand over only the session (a Playwright
   `storageState` file, a session cookie).

## Which tool

| Need | Tool |
|---|---|
| Click through the backend or frontend, acceptance screenshots, logged in | A scripted browser that fills the password from the environment and prints a few lines per step; at Netresearch the `typo3-browser` skill from the internal marketplace, where installed |
| Console errors, network requests, computed CSS, Lighthouse | Chrome DevTools MCP (`browser-testing-with-devtools` skill) |
| Ad-hoc interaction without a TYPO3-aware tool | Playwright MCP; every step returns a page snapshot, and a typed password stays in the transcript |
| No Playwright and no browser MCP (npm blocked) | A Node.js runner on the Chrome DevTools Protocol (`e2e-testing.md`, *Ad-hoc Browser Check Without Playwright (CDP Fallback)*) |
| A check that must keep passing | A Playwright spec (`e2e-testing.md`) |
| Status code, headers, a redirect | `curl` |
| What a service returns or a configuration resolves to inside the instance | A standalone PHP probe with the real DI container (*A PHP probe against the instance* below) |

On WSL or another host without a display, start both browser MCP servers with
`--headless`. Pass Chrome flags to the Chrome DevTools server joined with `=`
(`--chrome-arg=--no-sandbox`): a separate `--chromeArg --no-sandbox` is parsed
as an empty flag list (chrome-devtools-mcp 1.10.1).

## Backend specifics

- **Module frame.** A backend module renders inside `#typo3-contentIframe`.
  A locator, a text read or an axe scan on the top page does not see its DOM
  (`e2e-testing.md`, *Common Pitfalls*).
- **Sudo mode.** The four maintenance modules (Maintenance, Settings, Upgrade,
  Environment; *Admin Tools* in TYPO3 12 and 13, *System* in 14) ask for the
  password again, and only a system maintainer reaches them. The dialog is a
  modal in the **top** document, not inside the module frame; it appears
  asynchronously. Selectors and a wait that handles both cases:
  `e2e-testing.md`, *Common Pitfalls*. Fill it from the environment, like the
  login.
- **Screenshots below the fold.** A full-page screenshot stops at the outer
  frame, so module content below the first viewport is missing. Raise the
  viewport height to at least the module document's `scrollHeight` (read inside
  `#typo3-contentIframe`) plus the backend header. Compare the image height with
  the height you meant to capture, not with the viewport: a viewport screenshot
  is always exactly as tall as the viewport. The `typo3-docs` skill
  (`references/screenshots.md`) owns the screenshot rules.
- **Stored values without the edit form.** An edit link carries a token that
  expires, and the form is a write path. To read what a record holds, call
  `top.TYPO3.InfoWindow.showItem('<table>', <uid>)` from the top document (for
  example with Playwright's `page.evaluate`). It opens *Element information*
  for any table, read only and without a token, and lists the record's fields.
  Long text fields can be cut there; compare a checksum or a distinctive
  substring rather than the whole value.

## A PHP probe against the instance

To call a service of the running composer-mode instance from a throwaway
script, the script needs the instance's real DI container.
`Bootstrap::init($classLoader, false)` silently hands back a
`FailsafeContainer` (core services only; `$container->get()` on an extension
service throws `NotFoundException`, or *Container entry "…\BootService" is not
available*) whenever `checkIfEssentialConfigurationExists()` does not find
`config/system/settings.php`. Where it looks differs between versions
(cms-core `ConfigurationManager::getSystemConfigurationFileLocation()`):

- **v14.3:** always `Environment::getConfigPath() . '/system/settings.php'`.
  `SystemEnvironmentBuilder` takes the project and public paths from
  `TYPO3_PATH_APP` and `TYPO3_PATH_ROOT` before deriving them from the entry
  script's location, so a probe in `/tmp` without them looks under `/tmp`.
  Set both variables, then boot:

  ```php
  foreach (['TYPO3_PATH_APP' => '/var/www', 'TYPO3_PATH_ROOT' => '/var/www/public'] as $var => $path) {
      putenv("$var=$path");
      $_ENV[$var] = $_SERVER[$var] = $path;
  }
  $classLoader = require '/var/www/vendor/autoload.php';
  SystemEnvironmentBuilder::run(1, SystemEnvironmentBuilder::REQUESTTYPE_CLI);
  $container = Bootstrap::init($classLoader, false); // loads ext_localconf and TCA
  ```

- **v13.4:** the config path is used only when
  `Environment::getProjectPath() !== Environment::getPublicPath()`; otherwise
  the legacy `typo3conf/` path is read and nothing is found. When the derived
  paths come out equal, re-initialise `Environment` with an explicit public
  path after `SystemEnvironmentBuilder::run()` and before `Bootstrap::init()`:

  ```php
  Environment::initialize(
      Environment::getContext(), true, Environment::isComposerMode(),
      '/var/www', '/var/www/public', '/var/www/var', '/var/www/config',
      '/var/www/public/index.php', Environment::isWindows() ? 'WINDOWS' : 'UNIX',
  );
  ```

Guard the result with `$container instanceof FailsafeContainer` and print
`Environment::getConfigPath()` on failure; a wrong path otherwise costs a whole
round-trip to diagnose. Only **public** services can be fetched with
`$container->get()`: check the extension's `Services.yaml` and `Services.php`
for the public flag before planning a probe around a service. Run the probe as the web server user
inside the container (`docker cp probe.php <c>:/tmp/` then
`docker exec -u www-data <c> php /tmp/probe.php`); copy the file rather than
piping it to `php -`. The probe reads; rule 4 above still applies to anything
it writes.

## Typical checks

- **Content element backend preview.** Open the Page module on a page that
  holds the element. The preview renders inside the module frame. Check that it
  shows the element's content, no raw Fluid (`{f:` or `{data.`) and no
  exception, then take a screenshot with a raised viewport.
- **Backend module.** HTTP 200, no console error, every view of the module
  opened once (`backend-module-render-verification.md`).
- **Frontend page.** No console error, no failed asset request, the change
  visible with realistic content, in each language the change touches. A
  translation's URL carries the language base, its stored `slug` does not
  (`e2e-testing.md`, *Common Pitfalls*).
- **Element in a scrolling flex column.** A flex item with `overflow: hidden`
  shrinks to its border once the column's content overflows, unless it has
  `flex-shrink: 0`. jsdom computes no layout, so a unit test cannot see it.
  Fill the column until it scrolls, then measure the element's
  `getBoundingClientRect().height` and check that its buttons are visible.

## The report

State the URL, the instance (local, staging, production) with its TYPO3
version, what was checked, the measured result and the screenshot path. A
check that could not run is reported as not run, with the reason.
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