TYPO3 Extension Testing

# Where every task starts

## Nothing starts until the server answers

A skill is a file the installer left behind. It loads and reads the same whether
the tools behind it are there or not, and neither side notices. So the first
call below is also the check.

- A client may carry this server's name in each tool's name:
  `mcp__<server>__typo3_project_describe`. So a search for the bare name comes
  back empty where the server is there. A search for a tool's schema needs the
  same form. A `select:` on the bare names returns nothing where the tools are
  there. Look for the qualified form before you read an empty result as an
  answer about the server.
- No `typo3_` tool in this session, or a first call that errors: stop. Say that
  this workflow needs the server and it is not there, and name what came back.
- Do not fall back to general TYPO3 knowledge, and do not start to read the
  checkout. That answer carries this workflow's order and confidence and none of
  its evidence. Nothing in it says which of the two it is.
- Continue only when the user asks you to after you said so. Repeat it in the
  answer and in every finding a lookup would have carried.

## The order

This is an order rather than a list. Each step decides what the next one is
worth. Where a step below carries a condition to skip it, that condition is
narrow on purpose. A skipped prescription teaches the next reader to skip the
ones that matter too.

1. **`typo3_project_describe`** — the repository and whether it holds an
   installation yet. It reports the TYPO3 and PHP version, the project's own
   extensions, its sites, and the commands this repository declares. That
   version filters every later answer. A check the repository does not declare
   is a wrong answer however sensible it sounds.

   The answer ends with the whole procedures this server carries, as ids. That
   list is the only place a client that renders no resource list sees their
   names. Each one is a `typo3_rule_lookup` with that `documentId` rather than a
   search.
2. **`typo3_extension_describe`** for each extension in scope. It says what the
   extension registers, and what it ships beside that. That is its manual, its
   README, its test layers, and its XLF files with the source language each one
   declares. It also says what the extension does *not* ship, and that is the
   half no file listing gives you.

   Where step 1 reported no extension, that answer is this step, and there is
   nothing to call. Say so. A core checkout is that case, because step 1 names
   the project's own extensions and not TYPO3's.
3. **`typo3_task_guide`** with a short English task, the paths it touches, the
   target version and the change type. It answers the workflow this task belongs
   to and the checks that come with it.

   Run it in every session, this skill's own tasks included. The guide builds
   the brief from the paths as well as the task text. No skill knows which paths
   the caller holds.

   A skill that covers the task is not that brief. A skipped step costs the
   hints and the core checks those paths match. Where the guide's own answer
   named this skill, this is one call for an answer already in the session. The
   price of a step there is nothing to decide about.
4. **`typo3_hint_lookup`** for each subsystem in scope, with its concrete paths.
   One query per subsystem. A single broad query is not subsystem evidence.

   Where step 3 ran with those paths, its answer says whether you still owe this
   step. A brief that carried everything the lookup matched says so: "these are
   everything typo3_hint_lookup matches for these paths". There the guide made
   the call, and the same query returns the same hints. A brief that stopped
   short says that instead and names the ids it left. You owe those: fetch them
   by id rather than repeat the query.

   Read the sentence rather than the populated `hints` key. That key is present
   either way and does not tell the two apart. `omittedHints` is that sentence
   as data. It is empty where the brief carried everything, and it holds the ids
   the brief left where it stopped short.
5. **`typo3_changelog_lookup` with `type: deprecation`**, at each major the
   package declares. Omit the query and raise `limit` to carry that major whole.
   Those two are the changelog's own axes, and the extension's vocabulary is not
   among them. An entry carries a query only when its title carries every word
   of it at once. The core titled those entries about its own code.

   That is one call per declared major, and what comes back is the major. Every
   entry carries its own index tags. `ext:core`, `ext:frontend`, `ext:form` and
   the rest name the system extension a change is **in**. `TCA`, `TypoScript`,
   `Fluid`, `YAML`, `Backend`, `Frontend` name the surface.

   Step 2 picks the package's entries out of that answer by those tags. The tags
   are the system extensions it requires, renders through or registers into, and
   the kinds of file it ships. That costs no further call. An extension key of
   your own is not among them and matches nothing. `tag` narrows one question
   inside a major rather than composes the sweep out of eleven.

   You check the answers against step 2, which is the other half the words did.
   Verify each identifier that comes back in the checkout. A deprecation nothing
   here calls is not a finding.

   Carry the `FullyScanned` / `PartiallyScanned` tag into the answer. It says
   whether the Extension Scanner can find the remaining call sites or whether
   that reading is yours. Bounded this way, you can write the sweep before you
   open a file. That is why it is a step of the order rather than something the
   reading stumbles into.

   **What its silence is worth.** A changelog records change events. So a
   pattern nothing has touched for ten majors has no entry at all. An empty
   sweep is therefore not an answer about what still works. "Does this still
   work in version N" goes to `typo3_documentation_lookup` at that version. Ask
   it here, and whenever the reading raises it again.

   That is a question for a documented surface: a ViewHelper, a TCA type, a
   TypoScript setting. The manual matches page titles, section paths and what
   each manual declares by name, never the text of a page. Declared is a
   property, a class or method the manual documents, a console command. You
   reach one by its own name where the query writes that name the way code
   does. You also reach it where the query is nothing but the name. A PHP
   identifier the manual does not declare has no page named after it.

   An identifier goes to `typo3_changelog_lookup` under its own name. That
   reaches the entries that write it, however the core titled the change. Then
   it goes to the class below. Where the manual has no page for a surface
   either, that is a result and not an answer. Undocumented is not unsupported.

   **A second declared major.** A package that declares more than one asks a
   second question of every deprecation the sweep returns. Is the replacement on
   the lower one? The entry's `issue` is a query of its own, and it reaches
   every entry filed under that number. The Feature the core announced the
   replacement in is among them.

   The version the core released it in settles that question. Where the number
   reaches no sibling, nobody wrote an entry for the replacement.
   `typo3_rule_lookup` with
   `documentId="extension/compatibility/a-declared-major-that-is-not-installed"`
   is the reading that closes it.

   **Where you do not owe the sweep.** A task that produces no change does not
   reach this step at all. The property is what the task produces. A triage, a
   reproduction and a review illustrate it; they are not the list you read it
   off. The sweep asks what a package will have to stop calling. A task that
   writes nothing is not going to call anything.

   The exemption ends where the workflow produces a change. A review asked to
   make the change is that other workflow. It starts this order again with the
   files it is about to write. To carry somebody else's patch onto current code
   is on the same side. It writes commits. The sweep says whether the code that
   moved under the patch deprecated something the patch calls.

   Skip the sweep only where the change touches no TYPO3 API: a code style
   fixer, a CI file, an `.editorconfig`. A deprecation is a statement about API
   the package calls. So a change that calls none has nothing for the sweep to
   land on. The sweep is empty before it runs.

   That condition is worth a statement, because this step is the largest answer
   the order asks for. It is one call per declared major, with that major's
   deprecations whole. You read which side a change falls on off the files it
   touches, never off the task it started as. One PHP file edited along the way
   puts it back among the ordinary ones.

   A skip there costs the deprecation no finding would have walked into. How
   small the change is decides nothing either. Three statements can call a
   deprecated API as easily as three hundred.

   A test file is one of those wherever it sits. It calls the API it exercises
   and the framework around it, and both deprecate. A fixture is exempt where it
   is data the suite reads, and not where it is a class.

**Before the reading**, write down what the order established. That is the
version that filters every later answer, the packages in scope, and the commands
this repository declares. Write down which steps what discharged. Those are
answers already in the session rather than a second reading. What the files show
belongs to the report at the other end. A caller who cannot see what an answer
rests on cannot tell it from one that rests on nothing.

**Then** read the checkout. Not before. A file list first makes everything after
the list look optional. The conventions then arrive as a footnote to a verdict
that has already formed.

**Before the first edit**, name the files this change will create, change or
delete. A deletion is the caller's to ask for, and this is somebody else's
checkout. It is the one act nothing here can put back.

**Last**, the report names every step of this order it did not reach, and what
stood in for it. That is an answer already in the session, a condition that made
the step empty, or an exemption. A reader cannot tell a step passed over in
silence from one somebody dropped.

## When the lookups run out

A behaviour question that survives the lookups above is one you read out of the
installed source. Do not guess at it. The class that implements the behaviour
and the one it inherits from answer it. That reading is the step after the
lookups. It replaces a change to the code until it works.

A first change that did not work is evidence about the reading. So the second
attempt at one failure reads the source rather than changes the code again.

What it settles is what this installation does and never what TYPO3 supports. So
a finding says that you could not settle the question beyond the version
installed. An answer built on the reading names the version it holds for.

## What each runtime lookup adds after the extension answer

`typo3_extension_describe` in step 2 says what one package registers. The
lookups below say what the installation resolved. That is a different fact even
where the words are the same. So step 2 has made none of these calls:

- `typo3_backend_module_lookup` — the tree position, the labels, the access
  level, the routes and the navigation component the parent module supplies.
  Step 2 lists the modules the package declares. A declaration cannot show that
  inheritance.
- `typo3_icon_lookup` — whether any installed package registers an identifier.
  That validates the ones a template uses. Step 2 lists the identifiers this
  package contributes.
- `typo3_label_lookup` — the labels as the installation resolves them, with its
  overrides applied. Step 2 lists the package's XLF files and the source
  language each declares, never what a unit says here.
- `typo3_fluid_namespace_list` — the prefixes any template may use without a
  declaration, from every package at once. Step 2 lists the package's own
  declarations. So an empty list there is no evidence that no package registers
  a prefix globally.
- `typo3_configuration_lookup` — the resolved configuration value, after every
  extension has had its say. For a form data group it gives the order the
  providers really run in. Step 2 answers nothing about that surface at all.
  What a registration declares is not what the installation resolves.
- `typo3_service_lookup` — the class the container really injects for a service
  id, an interface or a tag. Decorations and overrides count. Step 2 lists what
  the package's own `Services.yaml` declares, never what won.
- `typo3_schema_lookup` — the columns TYPO3 derives for a table from its TCA. It
  gives the type, the nullability and the default each one gets. Step 2 lists
  the tables the package registers and nothing about their shape.
- `typo3_flexform_lookup` — the data structure the installation resolves a
  `type=flex` field to, sheet by sheet, with listeners and migrations applied.
  Step 2 lists the content elements a package registers, never the structure
  each one's form builds.
- `typo3_record_lookup` — the rows of any table the installation has TCA for. It
  says how many there are and where they sit. It says what one column holds
  across them and which rows depart from its default. Step 2 has no row in its
  answer at all.

None of these says whether what it reports is right. `typo3_hint_lookup` and
`typo3_documentation_lookup` do. A subsystem its own runtime lookup confirmed
can still break every rule that governs it. So it is not established until you
asked both.

## A rule reads in both directions

It says what new code should do, and it says what this checkout already does
wrong. A file that settled into the opposite of a rule is a finding, not a local
style to preserve. Consistency with a project's own habit establishes nothing
about whether the habit is right.

## What the code is for is evidence, and the repository states it

A mechanism that costs something is not a defect because it costs. Before you
report one, find what it is there for and say so. That is the manual, the
README, the changelog, the setting that drives it, or the declared versions.

Where the documentation states a purpose, what you have is a trade-off, not a
defect. Name it with its cost and its alternative. Where you cannot find one,
the finding says that you could not establish one, not that none exists. If you
skip this, your review is a list of everything the author did on purpose.

## What a finding rests on is part of the finding

Three things carry one. A file you read, at its path and its line. A command you
ran, with what it printed. A mechanism you traced into an installed package. Say
which of the three it is. If you leave it unsaid, a finding from a CI file
weighs as much as one with a verified line.

Where one of the project's own commands would settle it, run it.
`typo3_project_describe` marks each command it lists **check**, **change** or
**unknown**, read off the declared body. A check reports and hands the code back
as it was. So even a task told not to change files runs it. The linter the
repository already declares is the cheapest evidence in it.

Do not run a change under that instruction. Name an unknown in the answer as
evidence that is available, and do not run it unasked. An unknown is a test
suite, a shell pipeline, a console command.

What a check prints is not the finding. The configuration that makes it fail is
still what the finding is about. The run takes that finding from derived to
established.

## What this server does not know

It does not read your working tree. You establish which files changed, which
branch you are on, and whether a path or an identifier still exists there. Then
pass the concrete paths back, because that turns a general convention into an
answer about this code.

## Query it in English

The knowledge is English and the match is lexical. So a query in another
language reaches the loanwords the two happen to share and nothing else.
Translate the subject before the call and the answer back afterwards, whatever
language you speak with the user.

# Test strategy checklist

Read this when you choose test layers, set up or repair their harnesses, review
coverage, or select commands. Use only the rows the task and the checkout
support.

## Verify the starting point

- Identify the layers the requested behavior needs.
- Run or inspect each layer's discovery command before you rely on it.
- Establish or repair missing prerequisites before you add coverage.
- Preserve a review-only boundary: report setup defects without changing them.
- Do not force behavior into an existing lower layer merely because the correct
  layer has no harness yet.

## Select the layer

- Unit: isolated logic whose behavior needs neither TYPO3 bootstrap nor
  persistence.
- Functional: services, configuration, database schema, repositories,
  DataHandler, fixtures, or interaction between TYPO3 components.
- Browser: rendered journeys, backend interaction, JavaScript, or accessibility
  behavior nothing below the UI can establish.
- Static quality: defects and style no test observes — static analysis, coding
  standards, structural rules. Establish them when the task asks for them.
  Extend them rather than invent them when it does not.

## Respect the functional frontend boundary

- A TYPO3 functional frontend subrequest proves server-side routing, rendering
  and the generated response.
- An asset URL or AssetCollector tag in that response proves registration, not
  that the browser loaded or executed the asset.
- A functional test does not execute JavaScript, apply CSS, calculate layout,
  exercise focus behavior or inspect the browser accessibility tree.
- Use a browser test for an interactive claim. Describe untested interaction as
  unverified rather than as frontend-tested.
- Documentation and configuration: validate examples and declarations directly.
  Do not disguise a file-presence assertion as a behavioral test.

Prefer the lowest layer that observes the contract and would fail for the
reported defect. Record why a higher layer is necessary.

## Complete setup

- Resolve development dependencies against the package's declared TYPO3 and PHP
  constraints. Do not copy a version from another project.
- Reuse installed template configuration and existing project conventions.
- Keep extension-owned unit and functional tests in the extension. Keep
  browser-owned configuration in the project that serves the tested site.
- Establish a stable local command before CI, then make CI call that command.
- Keep a check command apart from the command that writes. Keep automatic
  formatting inside the first-party paths the project intends it to touch.
- Fix a new static-analysis finding. A baseline records what was already there.
- Keep credentials and machine-specific URLs out of tracked configuration.
- Prove every newly established layer with a meaningful test or a real browser
  spec. When no unit-testable behavior exists, report an empty discovered suite.
  Do not manufacture behavior or a vacuous assertion.
- Treat a missing runner or environment as an infrastructure failure, not as a
  failed product assertion.

## Select commands

1. Prefer the narrowest existing command that names the affected test or suite.
2. During setup, introduce one project-owned command per selected layer. Run it
   before you wire CI.
3. Use a direct PHPUnit or browser-runner invocation only when its executable,
   configuration, and target path exist in the checkout.
4. Then run the containing command `typo3_project_describe` declares, or the
   repository's documented test setup.
5. Never translate TYPO3 core commands into extension commands by analogy.
6. Separate missing infrastructure or environment prerequisites from a failing
   test.

## Coverage review

- Trace every claimed behavior to an existing test or a concrete missing case.
- Include success, boundary, failure, authorization, and persistence behavior
  only where the production code exposes those branches.
- Check that fixtures are minimal, deterministic, and independent of local site
  data, time, execution order, and external services.
- Name exact files and commands. Label anything you did not execute as
  unverified.

# PHPUnit unit and functional guidance

Read this after you choose a PHPUnit layer. Let the checkout, the
`project-extension-tests` hint, and versioned documentation decide concrete
package versions, bootstrap APIs, configuration contents, and commands.

## Verify the harness

1. Inspect the harness before you change it. That is `composer.json`, the lock
   file, the installed PHPUnit and `typo3/testing-framework`, and the PHPUnit
   configuration. It is the bootstrap files, the Composer scripts, and CI.
2. Run the narrowest declared PHPUnit discovery or suite command. Tell a missing
   executable, an invalid configuration, a bootstrap failure, and an unavailable
   functional database apart from a failed assertion.
3. If configuration is absent or stale, take its current shape from the
   installed testing framework or the versioned official documentation. Do not
   copy another extension's dependency constraint. Do not point at the core mono
   repository.
4. Preserve one command per useful layer. Give CI the same entrypoint that
   passes locally rather than a second invocation you assemble apart.
5. When `typo3/testing-framework` is missing, use its official compatibility
   information only to form candidates. Let Composer resolve the newest
   candidate that intersects the package's TYPO3, PHP, PHPUnit,
   minimum-stability, and lock constraints. Do not name or write a concrete
   constraint until the solver has accepted it.
6. Select the functional database from existing project or CI infrastructure and
   the behavior under test. SQLite is useful only when the production schema and
   queries support it. It is not the default merely because it needs no service
   container.

## Choose the folders

Keep an established repository layout. Where none exists, `typo3_rule_lookup`
with `documentId="extension/testing/phpunit"` holds the files, whole. Those are
`Build/UnitTests.xml`, `Build/FunctionalTests.xml` and the bootstrap beside
each. It says where they sit in a project, and what each needs after you write
it out.

- Keep runner configuration and bootstraps out of `Tests/`. They describe how
  the suite runs rather than one tested behavior.
- Keep unit and functional trees separate, so each configuration discovers only
  its own layer.
- Mirror the production subject below `Tests/Unit/` when that makes a test easy
  to find. Organize functional tests by behavior or subsystem when several
  production classes participate.
- Put fixtures beside the functional test or its small subsystem. Do not put
  them in one extension-wide bucket whose ownership is unclear.
- If a project already uses another shape that works, adapt it. Do not move
  files for cosmetic consistency. Calculate testsuite paths from the final
  configuration location.

## Write the test

- Unit-test isolated behavior without a TYPO3 boot. Prefer real value objects
  and collaborators. A test whose subject is only mocks is evidence about the
  mock arrangement.
- Use a functional test for dependency injection, configuration, persistence,
  repositories, TCA, DataHandler, routing, database schema, and server-side
  frontend rendering.
- Load only the extensions the behavior needs, derived from the package
  requirements and the subject under test.
- Keep fixtures beside the test, minimal, deterministic, and explicit about
  their expected result. Avoid records from the developer's installation.
- Resolve services from the functional test container when the wiring is part of
  the contract.
- Reset or isolate state that survives between tests. A test that passes alone
  but fails in its containing suite is not finished.
- Add the smallest real assertion that proves the behavior. Never use a vacuous
  assertion to certify the harness.

## Prove it

1. Run the new test or method alone.
2. Run its complete unit or functional suite.
3. Run both suites when shared bootstrap, dependencies, scripts, or CI changed.
4. Run the CI-equivalent command after local execution passes.
5. Report database or environment prerequisites apart from test results.

For a server-rendered frontend response, PHPUnit proves routing, configuration,
markup, and response behavior. It does not execute JavaScript, apply CSS, or
exercise a browser accessibility tree. Use the Playwright guide for those
claims.

# Playwright browser guidance

Read this after you choose a browser layer. Keep the runner with the project
that serves the TYPO3 site. Let the checkout and the current official Playwright
documentation decide dependency versions, supported configuration fields, and
browser installation commands.

## Verify the harness

1. Inspect the harness before you touch it. That is the project and frontend
   package manifests, the lock file, the Playwright configuration, and the test
   directories. It is the scripts, the ignored artifacts, and CI. Inspect the
   command that serves the site.
2. Establish the real mounted URL and whether the journey needs backend or
   frontend authentication. Do not invent a page identifier. Do not certify an
   unmounted content element.
3. Run test discovery and one existing spec before you edit the harness. Tell
   runner installation, browser availability, site reachability, authentication,
   and assertion failures apart.
4. Choose where browsers execute from evidence in the project: host, development
   container, or dedicated browser image. Keep the site URL and the artifact
   paths reachable from that execution environment.
5. If the checkout does not decide browser execution, leave the topology open.
   Local and CI reachability, browser persistence, and the project's container
   policy decide it later. Do not turn a generic host or DDEV preference into
   project evidence.

## Choose the folders

Keep an established repository layout. Where none exists, `typo3_rule_lookup`
with `documentId="project/testing/playwright"` holds the files, whole. Those are
`Build/playwright.config.ts`, the login setup and a spec per project. The page
adds the environment they read the site from, and what you do not commit.

- Project-owned describes the suite's lifecycle, not necessarily the repository
  root. Reuse an existing frontend package manifest when it belongs to this
  deployed project and can own browser commands. Do not create a second manifest
  only to move Playwright closer to the root. If the only manifest belongs to a
  reusable extension, establish an explicit project test package instead.
- Point `testDir` at the chosen browser-test root. Do not rely on accidental
  discovery across PHP or frontend unit tests.
- Keep setup files distinct from journey specs. Then express their order through
  Playwright project dependencies.
- Keep reusable browser fixtures and page objects apart from test cases only
  after a second spec needs them.
- Store accepted visual baselines beside their specs or under an explicit
  snapshot path. Commit only those baselines.
- If the repository already uses `Tests/Browser/`, `e2e/`, or a frontend-package
  directory, keep it and map the same ownership boundaries there.

## Establish or repair it

- Put configuration and specs at the project level unless the repository already
  owns them elsewhere. A standalone extension cannot prove a rendered journey
  without a site that mounts it.
- Read the base URL from the environment or the project configuration. Do not
  commit a developer-specific host.
- Add stable package scripts for a targeted run, the normal suite, and any
  accepted snapshot-update workflow before you wire CI.
- Keep reports, traces, screenshots, videos, and temporary authentication state
  in declared artifact or ignored paths. Commit reference snapshots only when
  the project uses visual regression tests on purpose.
- Use setup dependencies or fixtures for shared authenticated state. Do not log
  in on its own in every spec.
- Enable only the browsers and projects the task or the support policy requires.
  More combinations are not evidence when nobody runs or maintains them.

## Write the spec

- Test a user-visible journey or a browser-only contract. That is navigation,
  authentication, form behavior, JavaScript interaction, focus, responsive
  behavior, visual output, or accessibility.
- Prefer role, label, and other user-facing locators over DOM structure or CSS
  implementation details.
- Wait for observable conditions rather than fixed timeouts.
- Keep test data deterministic. Clean up the state the spec creates.
- Add an accessibility scan to the relevant mounted page or journey when the
  task makes an accessibility claim. Do not disable a rule merely to make the
  first run green.
- Review visual differences before you update snapshots. Never accept baselines
  blindly.

## Prove it

1. Run the new spec alone against the real served site.
2. Confirm that the expected report, trace, screenshot, or snapshot path works.
3. Run the containing browser project or suite.
4. Run the same script CI will call.
5. Report untested browsers, unavailable URLs, and environment prerequisites as
   unverified rather than passed.

# Static analysis and coding standards guidance

Read this after you choose the static-quality layer. It covers analysis, coding
standards, and the lint or normalisation steps that run beside them. The
checkout, the package's declared TYPO3 and PHP range, and versioned
documentation decide the concrete facts. Those are package versions, rule sets,
configuration contents, and commands.

## Verify what is already there

1. Inspect what is there before you change any of it. That is the package
   manifests, the lock file, the installed analysers and fixers, and their
   configuration and rule sets. It is the existing baselines, the Composer
   scripts, the development environment, and CI. Half an infrastructure is the
   ordinary case. That is a fixer without an analyser, a lint step without
   either, a configuration nothing calls.
2. Run every check that already exists, unchanged, and record its output. You
   measure every later claim against that run. A first analyser report on a
   project that never ran one is a list of findings rather than a regression.
3. Separate a missing executable, an unreadable configuration, and a real
   finding. Only the third says anything about the code.
4. Read what the existing configuration excludes on purpose before you widen it.
   A generated directory, a vendored library, or a fixture tree of broken code
   is a decision, not an oversight.
5. For a review-only request this is the whole workflow. Report what is missing
   or unenforced and change nothing.

## What a complete surface covers

This is the expectation the checkout is measured against. It names each check by
what it establishes rather than by the tool behind it. What the package ships
decides which of them apply. A check whose subject the extension does not ship
is absent for a reason rather than missing.

- **Syntax** — every shipped PHP file parses on every PHP version the package
  declares. Run `php -l` through a lint runner such as `overtrue/phplint` or
  `php-parallel-lint/php-parallel-lint`, so one command covers the tree.
- **Static analysis** — types, unreachable code, and calls that cannot succeed.
  Run `phpstan/phpstan` against the extension's own paths, which is what the
  core runs on itself. `GeneralUtility::makeInstance()` and its neighbours carry
  `@template` annotations. So the analyser gets its types from the installed
  core rather than from a TYPO3-specific analyser extension.

  Beside it, `phpstan/extension-installer` wires up whatever extensions the
  project installed. `phpstan/phpstan-phpunit` belongs beside a PHPUnit suite.
  `bnf/phpstan-psr-container` types the container's `get()` calls, and
  `phpstan/phpstan-deprecation-rules` reports use of deprecated API. Establish
  that a TYPO3-specific analyser extension is still maintained before adding
  one. Several are not, and an abandoned extension on a current core produces
  false findings instead of types. `vimeo/psalm` is the alternative where a
  project already runs it.

  Which packages to require is the whole of what this page decides about the
  analyser. What goes into its configuration is not. Ask `typo3_hint_lookup`
  with `id=extension-static-analysis`. It answers where the file belongs, which
  include it carries, and the constants an extension's analysis never sees. It
  answers which manifest you exclude rather than fix, the cache directory, the
  level, and what a baseline is for. It reads that off the packages that
  configure themselves this way. So ask it rather than recall a configuration
  from another project.
- **Coding standards** — the TYPO3 coding guidelines as the project applies
  them. Run `friendsofphp/php-cs-fixer` with the `typo3/coding-standards` rule
  set, which also owns the file header the guidelines require. Run
  `editorconfig-checker` where the repository ships an `.editorconfig`. Run
  `squizlabs/php_codesniffer` with `phpcompatibility/php-compatibility` where
  you have to prove the declared PHP range without a matrix.
- **Manifests and dependencies** — `composer validate` on the extension's own
  manifest. It also checks the manifest against what the extension declares
  about itself elsewhere. `composer audit` for advisories against what it
  requires. `ergebnis/composer-normalize` where the project keeps its manifest
  normalised.
- **Shipped configuration and data** — the files the package ships. The XLIFF
  linter `symfony/translation` ships validates against the schema rather than
  only parses the XML. A TYPO3 project usually has it installed. A YAML lint
  such as `j13k/yaml-lint` or the framework's own `lint:yaml` covers
  configuration. `helmich/typo3-typoscript-lint` covers TypoScript.

  Two of them have to learn about this project before their verdict is worth
  anything. `typo3_hint_lookup` with `id=language-files` says what the XLIFF
  linter needs before it accepts a file named the way TYPO3 names one. A linter
  ships a configuration of its own and merges yours over it. So what it reports
  and what it advises are its defaults rather than this project's conventions.
  Advice written for an older TYPO3 is still advice the tool gives today.

  Fluid templates have no established linter. The functional tests that render
  them prove them. Say so rather than invent a check for them.
- **Shipped frontend assets** — where the package ships JavaScript, TypeScript
  or CSS. Run `eslint` for the scripts, with `@typescript-eslint` where the
  sources are TypeScript. Run `stylelint` for the stylesheets, with
  `stylelint-scss` and `stylelint-order` where Sass compiles. A formatter such
  as `prettier` goes on the fix side and never into the check. Lint the sources
  the repository maintains rather than the compiled bundle below
  `Resources/Public/`. A finding in generated output is a finding about the
  build step that produced it.

  Declare each of them as a script in the package's own `package.json`. Then the
  same one command exists locally and in CI. Take the Node version from what the
  project declares rather than from the machine that happens to run it. Run each
  one over the files it guards before you report the entry as covered. A linter
  that finds nothing in the only sources the package ships is a gap dressed as
  coverage. That is the standard this page already applies to a matrix whose
  cells run only version-independent steps.

Read the names as the default per check where the checkout covers it with
nothing, never as a replacement for what it already runs. A project with another
analyser, another lint runner or its own wrapper around one has answered that
question already. A second tool for the same check is a second answer to
maintain. Versions come from the solver and from what the package's range
allows, never from this list.

`rector/rector` with `ssch/typo3-rector` reads like a check in its dry-run mode
and is not one. It proposes migrations, which belong to an upgrade task rather
than to the surface CI has to keep green.

Then say which axis each one has, because that decides where it runs. Syntax and
analysis depend on the PHP and TYPO3 combination and belong in the matrix. A
standards, manifest or format check is version-independent, and one run of it
proves as much as sixteen. A matrix whose every cell runs only
version-independent steps proves that the files parse and nothing more. Say so,
with what it costs and what it does not buy.

## Resolve the dependencies

1. Form candidates from the package's own declared TYPO3 and PHP range. Never
   form them from another project's manifest or from the core's build tooling.
2. Let Composer resolve the newest candidate that intersects those constraints
   together with what is already installed. Do not write a concrete constraint
   until the solver has accepted it.
3. Take a rule set from a package the project already requires before you add
   another one. Every added package is a further thing that has to stay current
   across the whole declared range. An abandoned one stops doing that.
4. Keep every one of them in the development requirements.
5. Where the solver refuses one, read what it refused rather than which TYPO3
   version the project runs. A check tool has to meet what this project
   resolved. A package nothing here pins can sit a major ahead of what the
   framework asks for. So the same tool goes into one project and not into the
   next.

   Where it cannot meet it, the tool gets an installation of its own. That is a
   second manifest below the build directory with its own vendor directory. The
   project-owned command calls that binary. The check exists either way. What
   moves is where the tool's own dependencies live.

## Establish one command per check

1. Give each check one stable project-owned command. Declare it where the
   project already declares its commands. Name it for what it checks rather than
   for the binary behind it.
2. Keep the check and the fix apart. A check reports and fails; a fix writes.
   One command that rewrites the tree on the way to its verdict is not a check.
   CI cannot call it.
3. Keep automatic formatting inside the first-party paths the project intends it
   to touch. Vendored code, generated output, other packages' files, and
   fixtures that assert exact bytes stay outside the fixer's paths. Confirm that
   with the fixer's own dry run before the first write and with the tree's
   status afterwards.
4. Point analysis at the paths the extension owns, at the level the project can
   hold today. A level chosen for the eventual state produces a wall of findings
   nobody works off.
5. Run each command locally until it passes. Then make CI call that same
   command. A CI step assembled apart proves something the developer cannot
   reproduce.

## Work the findings off

- Fix the finding. A baseline records what was already there on the day somebody
  wrote it. It never receives an error the change in hand introduced.
- Where a baseline exists, read it as a work list with an owner and a horizon.
  The horizon is usually the release that drops the oldest supported version.
  Say which of its entries the current change retires.
- A suppression that is correct while the package supports an older version is
  evidence rather than debt. Establish what it is there for, and what would
  remove it, before you propose that it goes.
- Keep a formatting pass in its own commit, apart from a behavioural change.
  Nobody can review a diff that mixes both.
- Where you introduce a check onto a repository that does not yet pass it, the
  conformance commits come first. The commit that adds the check comes last.
  Then no commit fails the check it introduces. The obvious split does the
  opposite. Tooling first leaves the new check on a tree the conformance pass
  has not reached yet. Verify it: run the check at the new HEAD.
- Report a finding in code the task does not touch. Do not fix it quietly beside
  the requested work.

## Prove it

1. Run each check on the narrowest scope it supports, then on its full target.
2. Run the fix command, run the check again, and inspect the tree for files
   outside the intended scope.
3. Run the CI-equivalent commands after the local commands pass.
4. Report the exact commands, their results, and the files the fixer changed.
   Report every check you did not run, with the reason.