majiayu000 TYPO3 Testing Skill
Templates, scripts, and references for comprehensive TYPO3 extension testing.
Test Type Selection
To select the appropriate test type, use this decision table:
| Type | Use When | Speed |
|---|---|---|
| Unit | Pure logic, no DB, validators, utilities | Fast (ms) |
| Functional | DB interactions, repositories, controllers | Medium (s) |
| Architecture | Layer constraints, dependency rules (phpat) | Fast (ms) |
| E2E (Playwright) | User workflows, browser, accessibility | Slow (s-min) |
| Integration | HTTP client, API mocking, OAuth flows | Medium (ms) |
| Fuzz | Security, parsers, malformed input | Manual |
| Crypto | Encryption, secrets, key management | Fast (ms) |
| Mutation | Test quality verification, 70%+ coverage | CI/Release |
Setting Up Test Infrastructure
To initialize testing infrastructure for an extension, run:
scripts/setup-testing.sh [--with-e2e]
To validate an existing setup, run:
scripts/validate-setup.sh
To generate a new test file, run:
scripts/generate-test.sh <TestType> <ClassName>
Running Tests
To execute tests via the Docker-based runner, use these commands:
# Unit tests
Build/Scripts/runTests.sh -s unit
# Functional tests
Build/Scripts/runTests.sh -s functional
# Architecture tests (phpat)
Build/Scripts/runTests.sh -s architecture
# E2E tests (Playwright)
Build/Scripts/runTests.sh -s e2e
# Quality tools
Build/Scripts/runTests.sh -s lint
Build/Scripts/runTests.sh -s phpstan
Build/Scripts/runTests.sh -s mutation
Scoring Requirements
To achieve full conformance scores, ensure:
| Criterion | Requirement |
|---|---|
| Unit tests | Required, 70%+ coverage |
| Functional tests | Required for DB operations |
| Architecture tests | phpat required for full points |
| PHPStan | Level 10 (max) |
Note: Full conformance requires phpat architecture tests enforcing layer boundaries.
Enforcement Rules
This skill enforces the following patterns. Violations should be flagged and corrected:
E2E Testing in CI (MANDATORY)
| Rule | Enforcement |
|---|---|
| NEVER use DDEV in CI/CD | Flag any .github/workflows/*.yml or .gitlab-ci.yml using ddev commands |
| Use GitHub Services | E2E workflows MUST use MariaDB service container |
| Use PHP built-in server | E2E workflows MUST use php -S for HTTP, not DDEV |
| Dual-mode Playwright config | playwright.config.ts MUST use TYPO3_BASE_URL env var |
Why: DDEV in CI is slow (2-3+ min startup), complex (Docker-in-Docker), resource-heavy, and fragile. The TYPO3 community standard is direct PHP or testing containers.
Correct pattern:
# GitHub Actions E2E
services:
db:
image: mariadb:11.4
# ...
steps:
- name: Start PHP server
run: php -S 0.0.0.0:8080 -t .Build/Web &
- name: Run Playwright
env:
TYPO3_BASE_URL: http://localhost:8080
run: npm run test:e2e
Incorrect pattern (flag this):
# WRONG - Never do this in CI
- run: ddev start
- run: ddev exec vendor/bin/phpunit
Using Reference Documentation
Core Testing References
When writing unit tests, consult references/unit-testing.md for UnitTestCase patterns, mocking strategies, and assertion examples.
When testing time-dependent code (schedulers, cache expiration, TTL), consult references/unit-testing.md for FakeClock patterns, Symfony Clock component usage, and Carbon setTestNow() for deterministic time testing.
When writing functional tests, consult references/functional-testing.md for FunctionalTestCase setup, CSV fixtures, and database testing patterns.
When migrating to PHPUnit 10+ or fixing container issues, consult references/functional-test-patterns.md for container reset patterns and migration guides.
When testing HTTP clients or external APIs, consult references/integration-testing.md for PSR-18 mocking, OAuth flow testing, and request capturing.
When writing browser-based E2E tests, consult references/e2e-testing.md for Playwright setup, Page Object Model patterns, and PHP-based E2E alternatives.
When setting up DDEV for local testing, consult references/ddev-testing.md for multi-version matrix testing and Playwright integration. Note: DDEV is for LOCAL development only - never use DDEV in CI/CD.
When configuring test runners, consult references/test-runners.md for runTests.sh customization and Docker orchestration.
Specialized Testing References
When enforcing architecture rules, consult references/architecture-testing.md for phpat configuration, layer constraints, and dependency rules.
When testing accessibility, consult references/accessibility-testing.md for axe-core integration and WCAG compliance testing.
When testing parsers or security-critical code, consult references/fuzz-testing.md for nikic/php-fuzzer patterns and malformed input generation.
When testing encryption or secrets, consult references/crypto-testing.md for sodium testing patterns and key management verification.
When measuring test quality, consult references/mutation-testing.md for Infection configuration and MSI interpretation.
When benchmarking performance, consult references/performance-testing.md for timing measurements, memory leak detection, and throughput testing.
TYPO3 Specific References
When testing against TYPO3 v14 final/readonly classes, consult references/typo3-v14-final-classes.md for interface extraction and mock strategies.
When writing JavaScript/TypeScript tests, consult references/javascript-testing.md for Jest and frontend testing patterns.
Quality & CI References
When configuring static analysis, consult references/quality-tools.md for PHPStan, PHP-CS-Fixer, and Rector setup.
When setting up CI/CD pipelines, consult references/ci-cd.md for GitHub Actions and GitLab CI workflows.
When integrating SonarCloud, consult references/sonarcloud.md for quality gate configuration.
Using Asset Templates
Infrastructure Setup
To set up Docker-based test orchestration, copy assets/Build/Scripts/runTests.sh to your extension. This is the required foundation for all test execution.
To initialize test bootstrapping, use these templates:
assets/bootstrap.php- General test bootstrap with autoloader detectionassets/UnitTestsBootstrap.php- Unit test bootstrap with optional TYPO3 stub autoloaderassets/FunctionalTestsBootstrap.php- Functional test bootstrap for TYPO3 testing framework
PHPUnit Configuration
To configure PHPUnit, copy and customize:
assets/UnitTests.xml- Unit test suite configurationassets/FunctionalTests.xml- Functional test suite configuration
Code Quality Tools
To set up static analysis and code style, use:
assets/phpstan.neon- PHPStan level 10 configurationassets/phpstan-baseline.neon- Baseline template for legacy code migrationassets/phpat.php- Architecture test rules for layer enforcementassets/phpat.neon- PHPat PHPStan extension configurationassets/.php-cs-fixer.dist.php- PHP-CS-Fixer code style rulesassets/rector.php- Rector automated refactoring configuration
CGL Enforcement: TYPO3 CGL is strict about alignment (e.g., binary_operator_spaces in setUp() methods). Always run composer ci:cgl or the project's CS fixer before committing. Do not rely on manual formatting.
Mutation Testing & Coverage
To configure mutation testing, copy assets/infection.json5 and adjust mutator settings and MSI thresholds.
To configure coverage reporting, copy assets/codecov.yml for Codecov integration.
CI/CD Workflows
To set up GitHub Actions, use:
assets/github-actions-tests.yml- Main CI workflow (lint, phpstan, unit, functional tests)assets/github-actions-e2e.yml- E2E workflow with GitHub Services + PHP built-in server (NOT DDEV)
E2E Testing Setup
To set up Playwright E2E testing, copy the assets/Build/playwright/ directory containing:
package.json- Node.js dependenciesplaywright.config.ts- Playwright configurationtests/playwright/- Test structure with login setup, fixtures, and example specs
Development Shortcuts
To add common command shortcuts, copy assets/Makefile for make-based task execution.
Docker Services
To configure additional Docker services for testing, use templates from assets/docker/:
docker-compose.yml- Base Docker Compose configurationcodeception.yml- Codeception-specific Docker setup
Example Tests
To see test patterns in action, review examples in assets/example-tests/:
ExampleUnitTest.php- Unit test structure and assertionsExampleFunctionalTest.php- Functional test with fixturesExampleAcceptanceCest.php- Codeception acceptance test
Database Fixtures
To set up test data, use CSV fixtures from assets/fixtures/:
be_users.csv- Backend user fixture with password hashespages.csv- Page tree structurett_content.csv- Content elementssys_category.csv- Category hierarchy
Consult assets/fixtures/README.md for fixture format documentation.
AI Agent Documentation
To document AI agent behavior for your extension, use assets/AGENTS.md as a template.
External Resources
When understanding TYPO3 testing patterns, consult the TYPO3 Testing Documentation.
When seeking reference implementations, study the Tea Extension.
When implementing architecture tests, consult phpat documentation.
When configuring mutation testing, consult Infection PHP documentation.
When setting up DDEV environments, consult DDEV documentation.
Contributing: https://github.com/netresearch/typo3-testing-skill