Download the PHP package netresearch/agent-typo3-testing without Composer

TYPO3 Testing Skill

A comprehensive Claude Code skill for creating and managing TYPO3 extension tests.

🔌 Compatibility

This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.

Supported Platforms:

• ✅ Claude Code (Anthropic)
• ✅ Cursor
• ✅ GitHub Copilot
• ✅ Other skills-compatible AI agents

Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.

Features

• Test Creation: Generate Unit, Functional, and E2E tests
• E2E Testing: Playwright-based browser automation (TYPO3 Core standard)
• Accessibility Testing: axe-core integration for WCAG compliance
• Infrastructure Setup: Automated testing infrastructure installation
• CI/CD Integration: GitHub Actions and GitLab CI templates
• Quality Tools: PHPStan, Rector, php-cs-fixer integration
• Fixture Management: Database fixture templates and tooling
• Test Orchestration: runTests.sh script pattern from TYPO3 best practices

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

npx (skills.sh)

Install with any Agent Skills-compatible agent:

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

Composer (PHP Projects)

Requires netresearch/composer-agent-skill-plugin.

Quick Start

1. Setup testing infrastructure:

2. Generate a test:

3. Run tests:

Test Types

Unit Tests

Fast, isolated tests without external dependencies. Perfect for testing services, utilities, and domain logic.

Functional Tests

Tests with database and full TYPO3 instance. Use for repositories, controllers, and integration scenarios.

E2E Tests (Playwright)

Browser-based end-to-end tests using Playwright (TYPO3 Core standard). For testing complete user workflows, backend modules, and accessibility compliance with axe-core.

Advanced Testing Patterns

Advanced PHPUnit Configuration

The tea extension demonstrates production-grade PHPUnit configuration with parallel execution, strict mode, and comprehensive coverage analysis.

Parallel Test Execution

PHPUnit 10+ supports parallel test execution for significant performance improvements:

Configuration (Build/phpunit/UnitTests.xml):

Key Features:

• executionOrder="random": Detects hidden test dependencies by randomizing test order
• failOnRisky="true": Treats risky tests as failures (tests without assertions)
• failOnWarning="true": Fails on warnings like deprecated function usage
• beStrictAboutTestsThatDoNotTestAnything="true": Ensures every test has assertions

Separate Unit and Functional Configurations

The tea extension maintains separate PHPUnit configurations:

Unit Tests (Build/phpunit/UnitTests.xml):

• No database bootstrap
• Fast execution (milliseconds per test)
• Strict mode enabled
• Code coverage analysis

Functional Tests (Build/phpunit/FunctionalTests.xml):

• Database bootstrap included
• TYPO3 testing framework integration
• SQLite for fast in-memory testing
• Test doubles for external services

Example functional test configuration:

Coverage Thresholds

Enforce minimum coverage requirements via composer scripts:

Progressive Coverage Targets:

• MVP Extensions: 50% minimum
• Production Extensions: 70% minimum
• Reference Extensions: 80%+ target

CSV Fixture and Assertion Pattern

The tea extension demonstrates an elegant CSV-based pattern for functional test fixtures, significantly improving test readability and maintainability.

Problem Statement

Traditional fixture loading in TYPO3 functional tests uses SQL files or PHP arrays:

CSV Fixture Pattern

Fixture File (Tests/Functional/Fixtures/Database/tea.csv):

Loading in Test:

CSV Assertion Pattern

Even More Powerful: Assert database state using CSV format:

Expected State File (Tests/Functional/Fixtures/Database/AssertTeaAfterCreate.csv):

Assertion in Test:

Benefits

1. Readability: CSV format is human-readable and version control friendly
2. Maintainability: Easy to modify fixtures without PHP syntax knowledge
3. Comprehensive Assertions: Assert entire table state in single call
4. Change Detection: Diff tools show fixture changes clearly
5. Cross-Test Reuse: Same CSV fixtures reusable across multiple tests

Best Practices

Minimal Fixtures: Include only necessary columns for the test:

Named Test Data: Use descriptive titles to make test intent clear:

Fixture Organization:

Multi-Database Testing

The tea extension demonstrates comprehensive multi-database testing across SQLite, MariaDB, MySQL, and PostgreSQL, ensuring compatibility across all TYPO3-supported database systems.

Why Multi-Database Testing Matters

Different databases have subtle behavioral differences:

• SQLite: Case-insensitive LIKE, limited ALTER TABLE support
• MySQL: Case sensitivity varies by OS and configuration
• MariaDB: Different optimizer behavior, JSON handling differences
• PostgreSQL: Strict type casting, different string comparison semantics

Extensions using advanced SQL features (e.g., JSON columns, full-text search, stored procedures) must test across all target databases.

runTests.sh Pattern

The tea extension uses Build/Scripts/runTests.sh for orchestrated multi-database testing:

Script Responsibilities:

1. Docker container orchestration
2. Database initialization and schema setup
3. Test execution with proper environment variables
4. Cleanup and teardown

CI Matrix Configuration

GitHub Actions (.github/workflows/ci.yml):

This matrix runs tests across:

• 3 PHP versions × 2 TYPO3 versions × 4 databases = 24 test combinations

Database-Specific Considerations

SQLite Advantages:

• Fast (in-memory execution)
• No external dependencies
• Ideal for local development

SQLite Limitations:

PostgreSQL Strict Typing:

Local Multi-Database Testing

Developers can run multi-database tests locally:

Docker Compose Alternative

For complex scenarios, use docker-compose.yml:

runTests.sh Orchestration Pattern

The runTests.sh script from the tea extension provides comprehensive test orchestration with Docker-based isolation.

Core Features

1. Test Suite Selection:

2. Database Selection:

3. Version Control:

4. Cleanup and Maintenance:

Implementation Structure

Key Components:

Benefits

1. Isolation: Each test run in clean container environment
2. Reproducibility: Same environment locally and in CI
3. Version Flexibility: Test against multiple PHP/TYPO3/DB versions
4. Developer Convenience: Single command for all test types
5. CI Integration: Same script used locally and in CI

Integration with Composer Scripts

Composer scripts delegate to runTests.sh:

This maintains the local-CI parity principle: developers and CI use identical commands.

Example Usage Workflows

Development Workflow:

Pre-Release Workflow:

CI/CD Workflow:

Documentation

• SKILL.md - Main workflow guide with decision trees
• references/ - Detailed testing documentation
• assets/ - PHPUnit configs, AGENTS.md, examples

Requirements

• PHP 8.1+
• Composer
• Docker (for functional tests)
• Node.js 22.18+ (for E2E tests)
• TYPO3 v12 or v13

Based On

• TYPO3 Testing Framework
• TYPO3 Best Practices: tea extension
• TYPO3 community best practices

Acknowledgments

This skill stands on the shoulders of the TYPO3 community's exceptional work. We gratefully acknowledge:

• TYPO3 Core Development Team — For creating and maintaining the TYPO3 Testing Framework, the typo3/core-testing-* Docker images, and establishing the testing patterns that make this skill possible.

• TYPO3 Best Practices Team — For the exemplary Tea Extension that serves as the reference implementation for testing infrastructure, demonstrating production-grade PHPUnit configuration, multi-database testing, and runTests.sh orchestration.

• TYPO3 Documentation Team — For the comprehensive testing documentation that guides extension developers toward quality practices.

License

This project uses split licensing:

• Code (scripts, workflows, configs): MIT
• Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Maintained By

Netresearch DTT GmbH, Leipzig

Made with ❤️ for Open Source by Netresearch