Initial commit

2025-11-30 08:43:13 +08:00
commit f6d4a68978
178 changed files with 51030 additions and 0 deletions
--- a/skills/typo3-testing/README.md
+++ b/skills/typo3-testing/README.md
@@ -0,0 +1,642 @@
+# TYPO3 Testing Skill
+
+A comprehensive Claude Code skill for creating and managing TYPO3 extension tests.
+
+## Features
+
+- **Test Creation**: Generate Unit, Functional, and Acceptance tests
+- **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
+
+Install the skill globally in Claude Code:
+
+```bash
+cd ~/.claude/skills
+git clone https://github.com/netresearch/typo3-testing-skill.git typo3-testing
+```
+
+Or via Claude Code marketplace:
+
+```bash
+/plugin marketplace add netresearch/claude-code-marketplace
+/plugin install typo3-testing
+```
+
+## Quick Start
+
+1. **Setup testing infrastructure:**
+   ```bash
+   cd your-extension
+   ~/.claude/skills/typo3-testing/scripts/setup-testing.sh
+   ```
+
+2. **Generate a test:**
+   ```bash
+   ~/.claude/skills/typo3-testing/scripts/generate-test.sh unit MyService
+   ```
+
+3. **Run tests:**
+   ```bash
+   Build/Scripts/runTests.sh -s unit
+   composer ci:test
+   ```
+
+## 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.
+
+### Acceptance Tests
+Browser-based end-to-end tests using Codeception and Selenium. For testing complete user workflows.
+
+## 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`):
+
+```xml
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="../../.Build/vendor/phpunit/phpunit/phpunit.xsd"
+    executionOrder="random"
+    failOnRisky="true"
+    failOnWarning="true"
+    stopOnFailure="false"
+    beStrictAboutTestsThatDoNotTestAnything="true"
+    colors="true"
+    cacheDirectory=".Build/.phpunit.cache">
+
+    <testsuites>
+        <testsuite name="Unit Tests">
+            <directory>../../Tests/Unit/</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage includeUncoveredFiles="true">
+        <report>
+            <clover outputFile=".Build/coverage/clover.xml"/>
+            <html outputDirectory=".Build/coverage/html"/>
+            <text outputFile="php://stdout" showUncoveredFiles="false"/>
+        </report>
+    </coverage>
+</phpunit>
+```
+
+**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:
+
+```xml
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="../../.Build/vendor/phpunit/phpunit/phpunit.xsd"
+    stopOnFailure="false"
+    colors="true"
+    cacheDirectory=".Build/.phpunit.cache">
+
+    <testsuites>
+        <testsuite name="Functional Tests">
+            <directory>../../Tests/Functional/</directory>
+        </testsuite>
+    </testsuites>
+
+    <php>
+        <ini name="display_errors" value="1"/>
+        <env name="TYPO3_CONTEXT" value="Testing"/>
+    </php>
+</phpunit>
+```
+
+#### Coverage Thresholds
+
+Enforce minimum coverage requirements via composer scripts:
+
+```json
+{
+  "scripts": {
+    "ci:coverage:check": [
+      "@ci:tests:unit",
+      "phpunit --configuration Build/phpunit/UnitTests.xml --coverage-text --coverage-clover=.Build/coverage/clover.xml",
+      "phpunit-coverage-check .Build/coverage/clover.xml 70"
+    ]
+  }
+}
+```
+
+**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:
+
+```php
+// ❌ Traditional approach: Verbose and hard to read
+protected function setUp(): void
+{
+    parent::setUp();
+    $this->importCSVDataSet(__DIR__ . '/Fixtures/Database/pages.csv');
+    $this->importCSVDataSet(__DIR__ . '/Fixtures/Database/tt_content.csv');
+    $this->importCSVDataSet(__DIR__ . '/Fixtures/Database/tx_tea_domain_model_product_tea.csv');
+}
+```
+
+#### CSV Fixture Pattern
+
+**Fixture File** (`Tests/Functional/Fixtures/Database/tea.csv`):
+
+```csv
+tx_tea_domain_model_product_tea
+uid,pid,title,description,owner
+1,1,"Earl Grey","Classic black tea",1
+2,1,"Green Tea","Organic green tea",1
+3,2,"Oolong Tea","Traditional oolong",2
+```
+
+**Loading in Test**:
+
+```php
+use TYPO3\TestingFramework\Core\Functional\FunctionalTestCase;
+
+final class TeaRepositoryTest extends FunctionalTestCase
+{
+    protected array $testExtensionsToLoad = [
+        'typo3conf/ext/tea',
+    ];
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->importCSVDataSet(__DIR__ . '/Fixtures/Database/tea.csv');
+    }
+
+    /**
+     * @test
+     */
+    public function findAllReturnsAllRecords(): void
+    {
+        $result = $this->subject->findAll();
+
+        self::assertCount(3, $result);
+    }
+}
+```
+
+#### CSV Assertion Pattern
+
+**Even More Powerful**: Assert database state using CSV format:
+
+**Expected State File** (`Tests/Functional/Fixtures/Database/AssertTeaAfterCreate.csv`):
+
+```csv
+tx_tea_domain_model_product_tea
+uid,pid,title,description,owner
+1,1,"Earl Grey","Classic black tea",1
+2,1,"Green Tea","Organic green tea",1
+3,2,"Oolong Tea","Traditional oolong",2
+4,1,"New Tea","Newly created tea",1
+```
+
+**Assertion in Test**:
+
+```php
+/**
+ * @test
+ */
+public function createPersistsNewTea(): void
+{
+    $newTea = new Tea();
+    $newTea->setTitle('New Tea');
+    $newTea->setDescription('Newly created tea');
+
+    $this->subject->add($newTea);
+    $this->persistenceManager->persistAll();
+
+    // Assert entire database state matches expected CSV
+    $this->assertCSVDataSet(__DIR__ . '/Fixtures/Database/AssertTeaAfterCreate.csv');
+}
+```
+
+#### 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:
+
+```csv
+tx_tea_domain_model_product_tea
+uid,title
+1,"Earl Grey"
+2,"Green Tea"
+```
+
+**Named Test Data**: Use descriptive titles to make test intent clear:
+
+```csv
+tx_tea_domain_model_product_tea
+uid,title,deleted
+1,"Active Tea",0
+2,"Deleted Tea",1
+```
+
+**Fixture Organization**:
+
+```
+Tests/Functional/
+├── Fixtures/
+│   └── Database/
+│       ├── tea_initial.csv           # Initial state
+│       ├── tea_after_create.csv      # Expected after creation
+│       ├── tea_after_update.csv      # Expected after update
+│       └── tea_after_delete.csv      # Expected after deletion
+```
+
+### 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:
+
+```bash
+#!/usr/bin/env bash
+
+# Run functional tests against SQLite (default, fast)
+./Build/Scripts/runTests.sh -s functional
+
+# Run functional tests against MariaDB 10.11
+./Build/Scripts/runTests.sh -s functional -d mariadb -i 10.11
+
+# Run functional tests against MySQL 8.0
+./Build/Scripts/runTests.sh -s functional -d mysql -i 8.0
+
+# Run functional tests against PostgreSQL 16
+./Build/Scripts/runTests.sh -s functional -d postgres -i 16
+```
+
+**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`):
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  functional-tests:
+    name: Functional Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+        typo3: ['12.4', '13.0']
+        database:
+          - type: 'sqlite'
+          - type: 'mariadb'
+            version: '10.11'
+          - type: 'mysql'
+            version: '8.0'
+          - type: 'postgres'
+            version: '16'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: pdo_sqlite, pdo_mysql, pdo_pgsql
+
+      - name: Composer Install
+        run: composer install --no-progress
+
+      - name: Functional Tests
+        run: |
+          if [ "${{ matrix.database.type }}" = "sqlite" ]; then
+            ./Build/Scripts/runTests.sh -s functional
+          else
+            ./Build/Scripts/runTests.sh -s functional -d ${{ matrix.database.type }} -i ${{ matrix.database.version }}
+          fi
+```
+
+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**:
+```php
+// ❌ Won't work on SQLite (lacks ALTER TABLE support)
+$connection->executeUpdate('ALTER TABLE tt_content ADD COLUMN new_field VARCHAR(255)');
+
+// ✅ Use TYPO3 API instead (cross-database compatible)
+$schemaManager = $connection->getSchemaManager();
+$column = new Column('new_field', Type::getType('string'), ['length' => 255]);
+$schemaManager->addColumn('tt_content', $column);
+```
+
+**PostgreSQL Strict Typing**:
+```php
+// ❌ MySQL/MariaDB allow implicit conversion, PostgreSQL doesn't
+$queryBuilder->where(
+    $queryBuilder->expr()->eq('uid', '123')  // String '123' vs INT uid
+);
+
+// ✅ Explicit type casting works everywhere
+$queryBuilder->where(
+    $queryBuilder->expr()->eq('uid', $queryBuilder->createNamedParameter(123, \PDO::PARAM_INT))
+);
+```
+
+#### Local Multi-Database Testing
+
+Developers can run multi-database tests locally:
+
+```bash
+# Quick SQLite test during development
+composer ci:tests:functional
+
+# Comprehensive multi-DB test before pushing
+./Build/Scripts/runTests.sh -s functional -d mariadb
+./Build/Scripts/runTests.sh -s functional -d mysql
+./Build/Scripts/runTests.sh -s functional -d postgres
+```
+
+#### Docker Compose Alternative
+
+For complex scenarios, use `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  mariadb:
+    image: mariadb:10.11
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: test
+    ports:
+      - "3306:3306"
+
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: root
+      POSTGRES_DB: test
+    ports:
+      - "5432:5432"
+
+  mysql:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: test
+    ports:
+      - "3307:3306"
+```
+
+### 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**:
+```bash
+./Build/Scripts/runTests.sh -s unit              # Unit tests only
+./Build/Scripts/runTests.sh -s functional        # Functional tests
+./Build/Scripts/runTests.sh -s acceptance        # Acceptance tests
+./Build/Scripts/runTests.sh -s lint              # PHP linting
+./Build/Scripts/runTests.sh -s phpstan           # Static analysis
+```
+
+**2. Database Selection**:
+```bash
+./Build/Scripts/runTests.sh -s functional -d sqlite       # Default
+./Build/Scripts/runTests.sh -s functional -d mariadb      # MariaDB
+./Build/Scripts/runTests.sh -s functional -d mysql        # MySQL
+./Build/Scripts/runTests.sh -s functional -d postgres     # PostgreSQL
+```
+
+**3. Version Control**:
+```bash
+./Build/Scripts/runTests.sh -s functional -d mariadb -i 10.11
+./Build/Scripts/runTests.sh -s functional -d postgres -i 16
+./Build/Scripts/runTests.sh -p 8.3              # PHP version
+```
+
+**4. Cleanup and Maintenance**:
+```bash
+./Build/Scripts/runTests.sh -s clean            # Remove containers
+./Build/Scripts/runTests.sh -s composer update  # Update dependencies
+```
+
+#### Implementation Structure
+
+**Key Components**:
+
+```bash
+#!/usr/bin/env bash
+
+# Parse command line arguments
+while getopts "s:d:i:p:h" option; do
+    case ${option} in
+        s) TEST_SUITE=${OPTARG} ;;
+        d) DATABASE=${OPTARG} ;;
+        i) DATABASE_VERSION=${OPTARG} ;;
+        p) PHP_VERSION=${OPTARG} ;;
+        h) showHelp; exit 0 ;;
+    esac
+done
+
+# Set defaults
+DATABASE=${DATABASE:-sqlite}
+PHP_VERSION=${PHP_VERSION:-8.2}
+
+# Container configuration
+CONTAINER_NAME="typo3-testing-${DATABASE}"
+DOCKER_IMAGE="typo3/core-testing-${DATABASE}:${DATABASE_VERSION}"
+
+# Execute test suite in container
+docker run \
+    --name ${CONTAINER_NAME} \
+    --rm \
+    -v $(pwd):/app \
+    -w /app \
+    ${DOCKER_IMAGE} \
+    /bin/bash -c "composer ci:tests:${TEST_SUITE}"
+```
+
+#### 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`:
+
+```json
+{
+  "scripts": {
+    "ci:tests:unit": "Build/Scripts/runTests.sh -s unit",
+    "ci:tests:functional": "Build/Scripts/runTests.sh -s functional",
+    "ci:tests:functional:mariadb": "Build/Scripts/runTests.sh -s functional -d mariadb",
+    "ci:tests:functional:postgres": "Build/Scripts/runTests.sh -s functional -d postgres",
+    "ci:tests": [
+      "@ci:tests:unit",
+      "@ci:tests:functional"
+    ]
+  }
+}
+```
+
+This maintains the local-CI parity principle: developers and CI use identical commands.
+
+#### Example Usage Workflows
+
+**Development Workflow**:
+```bash
+# Quick unit test during coding
+composer ci:tests:unit
+
+# Functional test before commit
+composer ci:tests:functional
+
+# Full test suite before push
+composer ci:tests
+```
+
+**Pre-Release Workflow**:
+```bash
+# Test against all databases
+./Build/Scripts/runTests.sh -s functional -d sqlite
+./Build/Scripts/runTests.sh -s functional -d mariadb -i 10.11
+./Build/Scripts/runTests.sh -s functional -d mysql -i 8.0
+./Build/Scripts/runTests.sh -s functional -d postgres -i 16
+
+# Test against multiple PHP versions
+./Build/Scripts/runTests.sh -s unit -p 8.2
+./Build/Scripts/runTests.sh -s unit -p 8.3
+./Build/Scripts/runTests.sh -s unit -p 8.4
+```
+
+**CI/CD Workflow**:
+```yaml
+# .github/workflows/ci.yml
+- name: Unit Tests
+  run: composer ci:tests:unit
+
+- name: Functional Tests (SQLite)
+  run: composer ci:tests:functional
+
+- name: Functional Tests (MariaDB)
+  run: composer ci:tests:functional:mariadb
+
+- name: Functional Tests (PostgreSQL)
+  run: composer ci:tests:functional:postgres
+```
+
+## Documentation
+
+- [SKILL.md](SKILL.md) - Main workflow guide with decision trees
+- [references/](references/) - Detailed testing documentation
+- [templates/](templates/) - PHPUnit configs, AGENTS.md, examples
+
+## Requirements
+
+- PHP 8.1+
+- Composer
+- Docker (for functional and acceptance tests)
+- TYPO3 v12 or v13
+
+## Based On
+
+- [TYPO3 Testing Framework](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/Testing/)
+- [TYPO3 Best Practices: tea extension](https://github.com/TYPO3BestPractices/tea)
+- TYPO3 community best practices
+
+## License
+
+GPL-2.0-or-later
+
+## Maintained By
+
+Netresearch DTT GmbH, Leipzig