docs
TYPO3 v14
Extending  /  Development and tests

18 — Development and tests

For anyone working on yavi_core or a theme.

Repository layout

text
<distribution>/
├── config/sites/<id>/settings.yaml   ← what the backend module writes
├── packages/
│   ├── yavi-core/                    framework
│   └── yavi-lucerne/                 theme
├── vendor/
└── init-yavi.sh                      local DDEV setup

The packages are wired in through a Composer path repository, so an edit in packages/ takes effect without reinstalling.

The everyday loop

bash
# edit a template, SCSS file or PHP class
ddev exec vendor/bin/typo3 cache:flush
# reload

Almost every "my change does nothing" is a missing cache flush: SCSS is compiled into a hashed file, Fluid templates are compiled, DI is compiled, and the importmap is only cache-busted per file change in Development context.

Tests

bash
ddev composer test                                  # everything
ddev exec php packages/yavi-core/Tests/run.php Unit # one suite

The runner is dependency-free — no PHPUnit — and exits non-zero on failure, so it works as a pre-commit or CI gate. Tests/bootstrap.php attempts a full TYPO3 bootstrap and degrades to autoload-only when there is no database; tests that need the container report themselves as skipped instead of failing.

What the suites cover today:

AreaGuards against
LicenceCache trust, signature age, product scope
SettingsEvery Layout field renders, maps to a CSS variable, survives the write path, and clears itself when set to the default
TokensSpacing -base inputs, radius factors vs lengths, the SCSS lists staying in sync across themes
TemplatesNo positive tabindex, every <iframe> has a title, every aria-labelledby points at an existing id
ViewHelpersFormatText, InlineIcon, gradient seeds, corner radius parsing

Note the assertion signature — the name comes first:

php
$this->assertSame('round trip: ' . $key, $expected, $actual);

Adding a test

Put it in Tests/Unit/ or Tests/Integration/, name the class …Test, and name each test after the defect it protects against. A failure should tell the next person what broke, not merely that something did.

Build scripts

bash
ddev exec php packages/yavi-core/Build/sync-theme-scss.php          # regenerate every theme's SCSS lists
ddev exec php packages/yavi-core/Build/sync-theme-scss.php --check  # fail on drift, used by the tests

Where things live

You want to changeLook in
A content element's markupyavi-core/Resources/Private/Templates/ContentElements/
A shared building blockyavi-core/Resources/Private/Partials/ContentElements/
Geometry of a componentyavi-core/Resources/Public/Scss/Structure/
Colour and decorationyavi-core/Resources/Public/Scss/Skin/ or the theme's Skin/
A backend fieldyavi-core/Configuration/TCA/Overrides/
A site settingyavi-core/Configuration/Sets/Full/settings.definitions.yaml
The backend moduleyavi-core/Classes/Controller/Backend/ThemeSettingsController.php + Resources/Private/Templates/Backend/ThemeSettings.html
Its stylingyavi-core/Resources/Public/Vendor/Backend/Css/backend-module.css
Labelsyavi-core/Resources/Private/Language/

Adding a site setting

  1. Declare it in settings.definitions.yaml with a category, a label and a description. The description is not optional — a test enforces that every field explains itself and says more than its label.
  2. Map it to a CSS custom property in ThemeCssVariablesRenderer::CSS_VARIABLE_MAP — another test fails if a field cannot reach a variable.
  3. Read the token in the SCSS with a fallback: var(--my-token, <the theme's default>).
  4. Flush the cache, run the tests.

Language files

FileContains
Backend.xlf / de.Backend.xlfTCA labels, backend module
locallang.xlf / de.locallang.xlfFrontend labels
locallang_mod.xlf, locallang_be.xlf (+ de. variants)Module and backend layout labels
locallang_db.xlf / de.locallang_db.xlfForm finisher labels

Two rules that are easy to get wrong:

Coding conventions in this codebase