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/backend-module-render-verification.md

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

# Backend Module Render Verification

> Fluid templates escape every static gate — render the actual module before calling it done.

## Why this matters

`cgl`, `phpstan` (even level 10), and unit tests do **not** parse Fluid. A backend
module can have green CI across the board and still throw an HTTP 500 the moment a
human opens it, because the only thing that exercises the template is an actual
render. "All checks pass" is **not** evidence that a backend module renders.

Two real failure modes that no static gate catches:

| Trap | Symptom | Cause |
|------|---------|-------|
| Wrong ViewHelper namespace | **Whole module 500s** (parse-time, before any output) | e.g. `<be:infobox>` instead of `<f:be.infobox>` — an unregistered namespace prefix is a template **parse** error, not a runtime one, so it takes down the entire view |
| Unbounded chart/canvas | Page balloons (a `<canvas>` grew to 6543px tall) | Chart.js (or similar) with `maintainAspectRatio: false` inside a container that has no fixed height — the canvas keeps growing every reflow |
| Argument typed differently per version | **Module 500s on one TYPO3 version only** | `f:be.infobox` types `state` as `int` on v13 and `mixed` on v14: a string passes on 14 and raises a TypeError on 13, so a v14-only render says nothing about v13 |

## Render every template, not only the one the module opens

A module smoke test opens the default route and proves that template. The other
templates are unproven, and the argument that breaks one breaks them all: in
`nr_passkeys_fe` the same wrong `state` sat in the dashboard and in the help
page, the e2e suite opened the dashboard, and the help page went unrendered on
both versions until a test asked for it.

Two things follow:

- **Enumerate the module's routes** from `Configuration/Backend/Modules.php` and
  open each one. A non-default route's URL is the module path plus that route's
  own `path`, and where the route sets none, its identifier serves as the path:
  module `nr_passkeys_fe` with a route `help` answers at
  `/typo3/module/nr/passkeys/fe/help`, because `ModuleFactory` turns `_` into
  `/` for the module part unless the registration sets an explicit `path`. Read
  both levels out of the registration rather than composing the URL from the
  module identifier alone.
- **A branch that only renders under a data condition is not covered by opening
  the page.** An infobox shown when every user has completed something renders
  in no ordinary fixture; either seed that state or assert the template through
  a render test.

Asserting the rendered severity, not just the status, pins the mapping as well:
`f:be.infobox` emits `callout callout-<severity>`, so `.callout-info`,
`.callout-warning` and `.callout-notice` are what an e2e case checks.

## Verify the render — three complementary layers

### 1. StandaloneView (functional, no browser)

For ViewHelper-level correctness, render the template in a functional test (see
`functional-testing.md`). This catches namespace registration, argument, and output
errors **without** a browser and runs in CI.

`StandaloneView` is the v13 way and is **gone on 14.3 and main** — resolve the view
through `ViewFactoryInterface` / `ViewFactoryData` instead, which exist on 13.4,
14.3 and main and therefore survive the whole CI matrix.

Limitation: it does **not** reproduce the `ModuleTemplate` / backend doc-header
context, asset inclusion (CSS/JS), or browser layout — so it cannot catch the
canvas-height trap or a CSS/JS load-order problem.

### 2. Render-action functional test (automated, CI-able)

Between StandaloneView and a live browser sits a layer that renders the WHOLE
action — controller, `ModuleTemplateFactory`, Fluid template, doc-header
buttons — inside a functional test. Construct the controller from real
container services and set only the Extbase request by reflection:

```php
$controller = new TaskListController(
    $this->get(ModuleTemplateFactory::class),
    $this->get(IconFactory::class),
    $this->get(TaskRepository::class),
    $this->get(BackendUriBuilder::class),
    $this->get(UsageAnalyticsServiceInterface::class),
);
// Backend request: applicationType BE + backend Route (packageName resolves
// the template root paths) + extbase params + normalizedParams; assign it to
// $GLOBALS['TYPO3_REQUEST'] and reflection-set the controller's $request.
$this->setPrivateProperty($controller, 'request', $this->createBackendRequest());

$response = $controller->listAction();
self::assertSame(200, $response->getStatusCode());
self::assertStringContainsString('Test Manual Task', (string)$response->getBody());
```

Also set up a backend admin (`setUpBackendUser(1)`) and `$GLOBALS['LANG']` via
`LanguageServiceFactory::createFromUserPreferences()` — `LocalizationUtility`
and flash queues need them. Unset `BE_USER`/`TYPO3_REQUEST`/`LANG` in `tearDown()`.

Traps this layer has hit in practice:

| Trap | Symptom | Rule |
|------|---------|------|
| Asserting the route *identifier* | `record_edit` never appears in markup | Backend URLs render the route **path** — assert `record/edit` |
| Guard-path redirects via Extbase `uriFor()` | `location` header is `''` in the harness | The module router isn't fully wired; assert `RedirectResponse` + a non-empty flash-message queue instead of the URL string |
| Service that degrades instead of throwing | Error-path test gets a 200 preview | Read the service first — e.g. a wizard `generateTask()` that falls back to a canned result never reaches the controller's catch; test the fallback render |
| `final` constructor dependency | `createMock()` impossible in a unit test | That class is functional-test territory by construction — don't fight it with reflection hacks |
| PHPUnit ≥ 12 mock notices | "No expectations were configured…" per test | Use `self::createStub()` when only return values matter |

### 3. Live render (browser)

For anything with layout, charts, JS modules, or `ModuleTemplate` chrome, open the
module in a running backend (a live render is a browser/manual step, **not** an
automated test — run schema/CLI against the same binaries CI uses, not through DDEV):

```bash
# 1. Apply the schema (v14: extension:setup — NOT database:updateschema, which was removed)
vendor/bin/typo3 extension:setup
# (or: php vendor/bin/typo3 extension:setup)

# 2. Open the module in a running backend (the typo3-ddev skill covers spinning one
#    up locally + the URL scheme), then check:
#    - HTTP 200, not 500 (a 500 here is almost always a Fluid parse error)
#    - no console errors / no "Chart.js not available" (classic-script vs ES-module load order)
#    - canvases/charts have a sane bounded height
```

Take the verification screenshot at **≥1440px** viewport (narrow viewports hide
sidebar/column overflow). The screenshot doubles as documentation evidence.

## Ad-hoc: render a template from the CLI, no test and no page tree

To settle a "does this attribute actually reach the markup" question without
writing a test, boot TYPO3 in a CLI script and hand the source straight to a
rendering context. This runs against the project's own `vendor/`, so it answers
for the version that is actually installed:

```php
<?php
// usage: php render.php <template-file> [<section>]
$templateFile = $argv[1] ?? throw new InvalidArgumentException('template file expected');
$section      = $argv[2] ?? null;

$classLoader = require '/var/www/html/vendor/autoload.php';
SystemEnvironmentBuilder::run(0, SystemEnvironmentBuilder::REQUESTTYPE_FE);
$container = Bootstrap::init($classLoader);

$serverRequest = (new ServerRequest('https://example.local/', 'POST'))
    // int bitmask, NOT ApplicationType::FRONTEND - see functional-testing.md
    ->withAttribute('applicationType', SystemEnvironmentBuilder::REQUESTTYPE_FE)
    ->withAttribute('extbase', new ExtbaseRequestParameters());
$GLOBALS['TYPO3_REQUEST'] = $serverRequest;

$context = $container->get(RenderingContextFactory::class)->create();
$context->setRequest(new ExtbaseRequest($serverRequest));
$context->getTemplatePaths()->setTemplateSource(file_get_contents($templateFile));

$view = new TemplateView($context);
echo $section === null
    ? $view->render()
    : $view->renderSection($section, ['someVariable' => 'value'], true);
```

Three things cost time when this is written from scratch:

- **`RenderingContextFactory::create()` reads `$GLOBALS['TYPO3_REQUEST']` itself**
  (through `ViewHelperResolver`), so the global must be set *before* the factory
  call — not only on the context. A wrong or missing `applicationType` throws
  `RuntimeException` 1606222812 from inside `create()`, before any view helper
  runs, so a `try/catch` around `render()` never sees it.
- **A template starting with `<f:layout>` fails** with *The Fluid template files ""
  could not be loaded* unless the layout paths are set. Pass the section name as
  the second argument above and the script calls `renderSection()` instead.
- **`f:form` still needs a real frontend.** It builds its action URI through
  routing, which needs a site and a page tree. Extract the field view helpers into
  a snippet and render those; everything except the `<form>` element is reachable
  this way.

## Checklist before declaring a backend module "done"

- [ ] Module opens with **HTTP 200** in a real backend (not just green CI)
- [ ] Every ViewHelper namespace used in the template is registered (`<f:…>`, or a declared custom namespace) — a typo'd prefix is a whole-template 500
- [ ] Charts/canvases sit in a **fixed-height** wrapper; no unbounded growth
- [ ] Browser console is clean (no asset load-order / missing-global errors)
- [ ] (Optional but cheap) a `StandaloneView` functional test renders each custom template/partial
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