Skip to content

netresearch/typo3-testing-skill / skills/typo3-testing

typo3-testing

Flagged

Use when reproducing defects as failing tests, testing template or rendered output changes, confirming changes on a running TYPO3 instance, or setting up TYPO3 extension tests: unit/functional/E2E, PHPUnit 11-13, mutation testing, final-class mocks (v14), CI matrix across TYPO3 12/13/14.3 LTS, typo3-ci-workflows meta-package, CI failures. Also: transaction rollback, worker crashes, competing requests, testing-framework setup, test matrix, integration/e2e testing, coverage, test generation.

FileKindSize
SKILL.mdskill md6.8 KB
assets/.php-cs-fixer.dist.phpscript7.0 KB
assets/AGENTS.mdmarkdown5.0 KB
assets/Build/Scripts/runTests.shexecutablescript27.5 KB
assets/Build/playwright/.nvmrcother6 B
assets/Build/playwright/package.jsonmanifest535 B
assets/Build/playwright/playwright.config.tsscript1.3 KB
assets/Build/playwright/tests/playwright/accessibility/modules.spec.tsscript2.0 KB
assets/Build/playwright/tests/playwright/config.tsscript712 B
assets/Build/playwright/tests/playwright/e2e/backend-module.spec.tsscript1.9 KB
assets/Build/playwright/tests/playwright/fixtures/setup-fixtures.tsscript2.7 KB
assets/Build/playwright/tests/playwright/helper/login.setup.tsscript975 B
assets/FunctionalTests.xmlconfig1.4 KB
assets/FunctionalTestsBootstrap.phpscript1.6 KB
assets/Makefileother2.3 KB
assets/UnitTests.xmlconfig890 B
assets/UnitTestsBootstrap.phpscript2.1 KB
assets/bootstrap.phpscript1.4 KB
assets/codecov.ymlconfig1.6 KB
assets/docker/codeception.ymlconfig979 B
assets/docker/docker-compose.ymlconfig1.4 KB
assets/example-tests/ExampleAcceptanceCest.phpscript2.2 KB
assets/example-tests/ExampleFunctionalTest.phpscript2.4 KB
assets/example-tests/ExampleUnitTest.phpscript1.6 KB
assets/fixtures/README.mdmarkdown2.0 KB
assets/fixtures/be_users.csvother361 B
assets/fixtures/pages.csvother257 B
assets/fixtures/sys_category.csvother228 B
assets/fixtures/tt_content.csvother338 B
assets/github-actions-e2e.ymlconfig8.8 KB
assets/github-actions-tests.ymlconfig6.3 KB
assets/infection.json5other2.8 KB
assets/phpat.neonother330 B
assets/phpat.phpscript8.4 KB
assets/phpstan-baseline.neonother365 B
assets/phpstan.neonother1.4 KB
assets/rector.phpscript2.9 KB
checkpoints.yamlconfig61.7 KB
references/accessibility-testing.mdmarkdown7.6 KB
references/architecture-testing.mdmarkdown4.4 KB
references/asset-templates-guide.mdmarkdown3.4 KB
references/backend-module-render-verification.mdmarkdown9.7 KB
references/backend-user-access-testing.mdmarkdown9.5 KB
references/captainhook-setup.mdmarkdown2.4 KB
references/ci-cd.mdmarkdown39.5 KB
references/ci-debugging.mdmarkdown20.0 KB
references/ci-workflows-meta-package.mdmarkdown11.6 KB
references/crash-and-concurrency-testing.mdmarkdown4.8 KB
references/crypto-testing.mdmarkdown16.6 KB
references/datahandler-silent-rewrites.mdmarkdown7.2 KB
references/ddev-testing.mdmarkdown1.3 KB
references/e2e-testing.mdmarkdown53.0 KB
references/enforcement-rules.mdmarkdown5.7 KB
references/event-dispatch-testing.mdmarkdown2.8 KB
references/framework-compat-gate.mdmarkdown4.9 KB
references/functional-test-patterns.mdmarkdown11.0 KB
references/functional-testing.mdmarkdown46.3 KB
references/fuzz-testing.mdmarkdown8.6 KB
references/integration-testing.mdmarkdown14.1 KB
references/javascript-testing.mdmarkdown29.3 KB
references/live-instance-verification.mdmarkdown8.6 KB
references/mock-validity.mdmarkdown15.7 KB
references/mutation-testing.mdmarkdown36.0 KB
references/performance-testing.mdmarkdown11.2 KB
references/quality-tools.mdmarkdown25.5 KB
references/release-workflow-validation.mdmarkdown3.6 KB
references/sonarcloud.mdmarkdown18.8 KB
references/synthetic-secret-fixtures.mdmarkdown3.8 KB
references/tdd-discipline.mdmarkdown9.1 KB
references/test-environment-guards.mdmarkdown18.5 KB
references/test-runners.mdmarkdown24.6 KB
references/typo3-ci-config-patterns.mdmarkdown9.0 KB
references/typo3-v14-final-classes.mdmarkdown16.5 KB
references/unit-testing.mdmarkdown59.1 KB
scripts/generate-test.shexecutablescript6.0 KB
scripts/setup-testing.shexecutablescript6.3 KB
scripts/validate-setup.shexecutablescript4.0 KB

references/integration-testing.md

View on GitHub
<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->

# Integration Testing for TYPO3 Extensions

Integration tests verify interactions between components with realistic (but mocked) external dependencies.

## Integration vs Functional vs E2E

| Type | Database | External APIs | TYPO3 Framework | Speed |
|------|----------|---------------|-----------------|-------|
| **Unit** | No | No | No | Fast (ms) |
| **Integration** | No | Mocked | Partial | Medium (ms) |
| **Functional** | Yes | No | Full | Slow (s) |
| **E2E** | Yes | Real/Mocked | Full + Browser | Slowest (s-min) |

**Integration tests** fill the gap between unit tests (isolated) and functional tests (full framework):
- Test component interactions
- Mock external APIs (HTTP, LDAP, OAuth)
- Verify request/response handling
- Test without database overhead

## Directory Structure

```
Tests/
├── Unit/
├── Integration/
│   ├── AbstractIntegrationTestCase.php
│   ├── Service/
│   │   └── ApiServiceIntegrationTest.php
│   └── Provider/
│       └── OAuthProviderIntegrationTest.php
└── Functional/
```

## Base Test Case

```php
<?php

declare(strict_types=1);

namespace Vendor\Extension\Tests\Integration;

use GuzzleHttp\Psr7\HttpFactory;
use GuzzleHttp\Psr7\Response;
use PHPUnit\Framework\MockObject\Stub;
use PHPUnit\Framework\TestCase;
use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamFactoryInterface;

/**
 * Base class for integration tests.
 *
 * Provides utilities for testing API interactions
 * with realistic HTTP responses.
 */
abstract class AbstractIntegrationTestCase extends TestCase
{
    protected RequestFactoryInterface $requestFactory;
    protected StreamFactoryInterface $streamFactory;

    protected function setUp(): void
    {
        parent::setUp();
        $this->requestFactory = new HttpFactory();
        $this->streamFactory = new HttpFactory();
    }

    /**
     * Create an HTTP client stub that returns sequential responses.
     *
     * @param list<ResponseInterface> $responses
     */
    protected function createHttpClientWithResponses(array $responses): ClientInterface&Stub
    {
        $client = self::createStub(ClientInterface::class);
        $client->method('sendRequest')
            ->willReturnOnConsecutiveCalls(...$responses);

        return $client;
    }

    /**
     * Create a successful JSON response.
     *
     * @param array<string, mixed> $body
     */
    protected function createSuccessResponse(array $body, int $statusCode = 200): ResponseInterface
    {
        return new Response(
            status: $statusCode,
            headers: ['Content-Type' => 'application/json'],
            body: \json_encode($body, JSON_THROW_ON_ERROR),
        );
    }

    /**
     * Create an error response.
     *
     * @param array<string, mixed> $body
     */
    protected function createErrorResponse(array $body, int $statusCode = 400): ResponseInterface
    {
        return new Response(
            status: $statusCode,
            headers: ['Content-Type' => 'application/json'],
            body: \json_encode($body, JSON_THROW_ON_ERROR),
        );
    }

    /**
     * Create a stub HTTP client that captures request bodies.
     *
     * @return array{client: ClientInterface&Stub, requests: array<RequestInterface>}
     */
    protected function createRequestCapturingClient(ResponseInterface $response): array
    {
        $requests = [];
        $client = self::createStub(ClientInterface::class);
        $client->method('sendRequest')
            ->willReturnCallback(function (RequestInterface $request) use ($response, &$requests) {
                $requests[] = $request;
                return $response;
            });

        return ['client' => $client, 'requests' => &$requests];
    }
}
```

## Integration Test Examples

### API Service Integration

```php
<?php

declare(strict_types=1);

namespace Vendor\Extension\Tests\Integration\Service;

use Vendor\Extension\Service\ExternalApiService;
use Vendor\Extension\Tests\Integration\AbstractIntegrationTestCase;

final class ExternalApiServiceIntegrationTest extends AbstractIntegrationTestCase
{
    /**
     * @test
     */
    public function fetchDataReturnsDeserializedResponse(): void
    {
        // Arrange: Mock HTTP client with expected response
        $expectedData = [
            'items' => [
                ['id' => 1, 'name' => 'Item 1'],
                ['id' => 2, 'name' => 'Item 2'],
            ],
            'total' => 2,
        ];

        $client = $this->createHttpClientWithResponses([
            $this->createSuccessResponse($expectedData),
        ]);

        $service = new ExternalApiService(
            httpClient: $client,
            requestFactory: $this->requestFactory,
        );

        // Act
        $result = $service->fetchItems();

        // Assert
        self::assertCount(2, $result->getItems());
        self::assertSame(2, $result->getTotal());
    }

    /**
     * @test
     */
    public function fetchDataHandlesRateLimitWithRetry(): void
    {
        // Arrange: First request fails with 429, second succeeds
        $client = $this->createHttpClientWithResponses([
            $this->createErrorResponse(['error' => 'Rate limit exceeded'], 429),
            $this->createSuccessResponse(['items' => [], 'total' => 0]),
        ]);

        $service = new ExternalApiService(
            httpClient: $client,
            requestFactory: $this->requestFactory,
        );

        // Act
        $result = $service->fetchItems();

        // Assert: Should succeed after retry
        self::assertSame(0, $result->getTotal());
    }

    /**
     * @test
     */
    public function createItemSendsCorrectPayload(): void
    {
        // Arrange: Capture the request
        ['client' => $client, 'requests' => $requests] = $this->createRequestCapturingClient(
            $this->createSuccessResponse(['id' => 123, 'created' => true], 201)
        );

        $service = new ExternalApiService(
            httpClient: $client,
            requestFactory: $this->requestFactory,
            streamFactory: $this->streamFactory,
        );

        // Act
        $service->createItem('Test Item', ['category' => 'test']);

        // Assert: Verify request payload
        self::assertCount(1, $requests);
        $request = $requests[0];

        self::assertSame('POST', $request->getMethod());
        self::assertStringContainsString('/api/items', (string)$request->getUri());

        $body = \json_decode((string)$request->getBody(), true);
        self::assertSame('Test Item', $body['name']);
        self::assertSame('test', $body['category']);
    }
}
```

### OAuth Provider Integration

```php
<?php

declare(strict_types=1);

namespace Vendor\Extension\Tests\Integration\Provider;

use Vendor\Extension\Provider\OAuthProvider;
use Vendor\Extension\Tests\Integration\AbstractIntegrationTestCase;

final class OAuthProviderIntegrationTest extends AbstractIntegrationTestCase
{
    /**
     * @test
     */
    public function exchangeCodeForTokenReturnsAccessToken(): void
    {
        // Arrange: Mock OAuth token endpoint response
        $tokenResponse = [
            'access_token' => 'test_access_token_123',
            'token_type' => 'Bearer',
            'expires_in' => 3600,
            'refresh_token' => 'test_refresh_token_456',
        ];

        $client = $this->createHttpClientWithResponses([
            $this->createSuccessResponse($tokenResponse),
        ]);

        $provider = new OAuthProvider(
            httpClient: $client,
            requestFactory: $this->requestFactory,
            streamFactory: $this->streamFactory,
            clientId: 'test_client',
            clientSecret: 'test_secret',
            tokenEndpoint: 'https://oauth.example.com/token',
        );

        // Act
        $token = $provider->exchangeCodeForToken('auth_code_xyz');

        // Assert
        self::assertSame('test_access_token_123', $token->getAccessToken());
        self::assertSame('Bearer', $token->getTokenType());
        self::assertSame(3600, $token->getExpiresIn());
    }

    /**
     * @test
     */
    public function refreshTokenObtainsNewAccessToken(): void
    {
        // Arrange
        $refreshResponse = [
            'access_token' => 'new_access_token_789',
            'token_type' => 'Bearer',
            'expires_in' => 3600,
        ];

        ['client' => $client, 'requests' => $requests] = $this->createRequestCapturingClient(
            $this->createSuccessResponse($refreshResponse)
        );

        $provider = new OAuthProvider(
            httpClient: $client,
            requestFactory: $this->requestFactory,
            streamFactory: $this->streamFactory,
            clientId: 'test_client',
            clientSecret: 'test_secret',
            tokenEndpoint: 'https://oauth.example.com/token',
        );

        // Act
        $token = $provider->refreshToken('old_refresh_token');

        // Assert: Verify refresh grant was sent
        $body = (string)$requests[0]->getBody();
        self::assertStringContainsString('grant_type=refresh_token', $body);
        self::assertStringContainsString('refresh_token=old_refresh_token', $body);

        self::assertSame('new_access_token_789', $token->getAccessToken());
    }
}
```

## Provider Response Helpers

For LLM/AI provider integrations, create response helpers:

```php
/**
 * Get OpenAI-style chat completion response.
 *
 * @return array<string, mixed>
 */
protected function getOpenAiChatResponse(
    string $content = 'Test response',
    string $model = 'gpt-4o',
    string $finishReason = 'stop',
): array {
    return [
        'id' => 'chatcmpl-' . \bin2hex(\random_bytes(12)),
        'object' => 'chat.completion',
        'created' => \time(),
        'model' => $model,
        'choices' => [
            [
                'index' => 0,
                'message' => [
                    'role' => 'assistant',
                    'content' => $content,
                ],
                'finish_reason' => $finishReason,
            ],
        ],
        'usage' => [
            'prompt_tokens' => \random_int(10, 100),
            'completion_tokens' => \random_int(20, 200),
            'total_tokens' => \random_int(30, 300),
        ],
    ];
}

/**
 * Get Claude-style chat completion response.
 *
 * @return array<string, mixed>
 */
protected function getClaudeChatResponse(
    string $content = 'Test response',
    string $model = 'claude-sonnet-4-20250514',
    string $stopReason = 'end_turn',
): array {
    return [
        'id' => 'msg_' . \bin2hex(\random_bytes(12)),
        'type' => 'message',
        'role' => 'assistant',
        'content' => [
            ['type' => 'text', 'text' => $content],
        ],
        'model' => $model,
        'stop_reason' => $stopReason,
        'usage' => [
            'input_tokens' => \random_int(10, 100),
            'output_tokens' => \random_int(20, 200),
        ],
    ];
}
```

## When to Use Integration Tests

### Use Integration Tests For:
- HTTP client interactions
- OAuth/authentication flows
- Third-party API integrations
- Request/response serialization
- Error handling and retries
- Rate limiting behavior

### Use Functional Tests Instead For:
- Database operations
- TYPO3 DataHandler hooks
- TCA/FlexForm processing
- Caching behavior
- Full request lifecycle

## Running Integration Tests

Integration tests typically run with unit tests (same speed characteristics):

```bash
# Run with unit tests
Build/Scripts/runTests.sh -s unit

# Or in separate suite if desired
.Build/bin/phpunit -c Build/phpunit/IntegrationTests.xml
```

## Best Practices

1. **Mock external dependencies**: Never make real HTTP calls
2. **Test error paths**: 4xx, 5xx, timeouts, malformed responses
3. **Verify request payloads**: Capture and assert request bodies
4. **Use realistic responses**: Copy actual API responses
5. **Keep tests fast**: No database, no network
6. **Document API contracts**: Response helpers serve as documentation
7. **Pick an assertion that can fail on what you care about**: see below

## A Containment Assertion Cannot Catch Something Extra

Fixture harnesses commonly compare an expected log or output file by asking
whether each expected line is *contained* in the actual one — a custom
`assertFileContainsLines()`, `assertStringContainsString()` in a loop, or
`assertArraySubset()`-style helpers. That assertion is one-directional by
construction: it fails on a missing line and cannot fail on a surplus one.

So a fixture whose `expected/logs/warning.log` lists the one warning a case
should produce still passes when the code emits two — including the case where
the second warning is wrong, or is the same warning fired twice. The suite is
green and the defect is invisible to it.

Before relying on such a fixture, ask what property is being pinned:

| Property | Assertion that can fail on it |
|---|---|
| "this line appears" | containment |
| "these lines and no others" | equality on the whole file |
| "exactly N of these" | count, asserted explicitly |

When the harness is shared across every fixture in a repository, changing it is
its own change with its own blast radius — but say so in the pull request
rather than reporting the behaviour as covered. A one-directional assertion
documents half a rule, and the half it drops is usually the one a regression
reintroduces.

## Dependency Injection Pattern

For services with HTTP dependencies, use constructor injection:

```php
final class MyApiService
{
    public function __construct(
        private readonly ClientInterface $httpClient,
        private readonly RequestFactoryInterface $requestFactory,
        private readonly StreamFactoryInterface $streamFactory,
    ) {}
}
```

This enables easy testing:

```php
$service = new MyApiService(
    httpClient: $this->createHttpClientWithResponses([...]),
    requestFactory: $this->requestFactory,
    streamFactory: $this->streamFactory,
);
```

## Resources

- [PSR-18 HTTP Client](https://www.php-fig.org/psr/psr-18/)
- [PSR-17 HTTP Factories](https://www.php-fig.org/psr/psr-17/)
- [Guzzle PSR-7](https://github.com/guzzle/psr7)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall