typo3-testing

TYPO3 测试技能

报告应先变成失败测试，再着手修复

Bug 报告就是一个尚不存在的测试。根据报告中的输入和预期输出编写测试，运行它，并确认它因报告中描述的原因失败。修复后再编写的测试，只能证明代码现在的行为。

通过模板生成的输出不在单元测试套件的覆盖范围内。 单元测试套件会加载 PHP 类，却不会渲染 Fluid 模板，因此修改模板后，即使页面已经损坏，测试套件也仍会全部通过。要证明这类修改有效，应实际渲染模板：编写一个调用渲染路径并断言渲染结果字符串的功能测试。

检查渲染结果字符串，而不是退出代码。Fluid 不会因无法解析内联表达式而报错——它会原样输出该表达式，导致标记传到浏览器时，{f:if(...)} 留在它所在的属性中；而只断言没有抛出异常的测试会通过。如果内联表达式需要在一个调用中嵌套另一个调用，应改用标签（<f:if>），或在 PHP 中计算值后传入。

先评估规则

增强现有测试套件时（而非从头开始），首先运行：

automated-assessment typo3-testing

安装 typo3-conformance 和 enterprise-readiness，以获得更广泛的覆盖。

根据 73 个以上的检查点生成差距报告（PHPUnit、PHPStan、runTests.sh、架构、变异测试、CI 矩阵、覆盖率）。

将报告用作任务清单。 手动编写测试之前，先解决机械检查失败的问题。

适用场景

• “enhance/improve/strengthen tests”、“increase coverage/mutation”
• “enterprise grade”、“A+ testing”

不适用场景

• 从头开始、编写特定测试、调试失败

---

测试类型选择

类型	适用场景	速度
Unit	纯逻辑、无数据库、验证器、实用工具	快
Functional	数据库交互、仓库、控制器	中
Architecture	分层约束、依赖规则（phpat）	快
E2E (Playwright)	用户工作流、浏览器、无障碍性	慢
Integration	HTTP 客户端、API 模拟、OAuth 流程	中
Mutation	测试质量、70% 以上覆盖率	CI/发布

runTests.sh - 必须使用

Build/Scripts/runTests.sh 是必需的：必须可执行，并使用 -s（测试套件）和 -p（PHP 版本）。

Git 钩子

Netresearch 默认配置：Build/captainhook.json（在 composer.json 的 extra.captainhook.config 中声明）。验证方式：ls Build/captainhook.json .git/hooks/pre-commit（参见 references/captainhook-setup.md）。

命令

# Setup (run in the extension root; paths are relative to this skill)
scripts/setup-testing.sh [-a]   # -a: Codeception acceptance setup
scripts/validate-setup.sh
scripts/generate-test.sh <Type> <Class>

# Run (always via runTests.sh)
Build/Scripts/runTests.sh -s unit|functional|phpstan|cgl|mutation|ci

修复前确认测试失败，修复后确认测试通过。Bug 修复使用 references/tdd-discipline.md 中的严格 TDD 循环——没有粘贴的输出，就不要声称“已测试”或“已验证”。

评分要求

必须编写单元测试（覆盖率 70% 以上）。数据库操作必须编写功能测试。架构评分必须使用 phpat。 PHPStan 级别为 10。

参考资料（位于 references/ 目录，省略 .md）

unit-testing.md | functional-testing.md | functional-test-patterns.md | integration-testing.md | e2e-testing.md | accessibility-testing.md | ddev-testing.md | test-runners.md | architecture-testing.md | ci-debugging.md | ci-cd.md | quality-tools.md | mutation-testing.md | fuzz-testing.md | performance-testing.md | typo3-v14-final-classes.md | mock-validity.md | javascript-testing.md | captainhook-setup.md | enforcement-rules.md | event-dispatch-testing.md | crypto-testing.md | test-environment-guards.md | sonarcloud.md | typo3-ci-config-patterns.md | tdd-discipline.md | ci-workflows-meta-package.md | synthetic-secret-fixtures.md | release-workflow-validation.md | asset-templates-guide.md | backend-module-render-verification.md | backend-user-access-testing.md | framework-compat-gate.md | datahandler-silent-rewrites.md | live-instance-verification.md

内容触发条件

• 不同 TYPO3 版本的 CI 失败 → ci-debugging.md
• 带 TSFE 上下文的功能测试 → functional-testing.md
• 不同依赖版本下的模拟失败 → mock-validity.md
• 图像/扩展测试、Environment::initialize、NormalizedParams 类型错误、backupGlobals → test-environment-guards.md
• 使用 try/catch 测试事件分发器 → event-dispatch-testing.md
• 元包、typo3-ci-workflows、no-plugins → ci-workflows-meta-package.md
• 虚构密钥、推送保护、cs-fixer 拼接 → synthetic-secret-fixtures.md
• 标签已被占用、打标签前验证 → release-workflow-validation.md
• 后端模块 500 / ViewHelper 命名空间错误 / 画布失控 → backend-module-render-verification.md
• 强制执行非管理员 BE 用户访问权限 → backend-user-access-testing.md
• 通过 DataHandler 写入代码（Agent 工具、导入器、API 端点），值被丢弃或改写且没有报错 → datahandler-silent-rewrites.md
• 软件包无法与 TYPO3 一起安装 → framework-compat-gate.md
• 在运行中的实例上确认更改（后端模块、内容元素预览、前端页面、验收截图）、sudo 模式对话框、截图中的模块内容被截断 → live-instance-verification.md
• 使用 happy-dom、fast-check、旧版 jQuery 插件测试的 Vitest，单元测试或 E2E 规格 → javascript-testing.md；Stryker → mutation-testing.md
• 没有 Playwright / 对 EXT:form 或 JS 驱动页面进行临时浏览器检查 → e2e-testing.md（CDP 备用方案）

链接

TYPO3 测试文档 | Tea 扩展 | phpat | Infection