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/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
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 |