---
title: "Prüfen, testen, übersetzen"
description: "app:plugin:validate, statische Prüfungen, PHPUnit mit dem Testkit PluginTestCase, Playwright und Übersetzungen eines Plugins"
---

## app:plugin:validate

```bash
php bin/console app:plugin:validate                      # alle Plugins im Plugin-Verzeichnis
php bin/console app:plugin:validate plugins/hallo-welt   # ein Plugin-Ordner
```

Der Befehl prüft je Plugin und endet bei Fehlern mit Exit-Code 1:

- **Manifest:** Pflichtfelder, Formate, Namensregeln, Anforderungen (`requires`), vorhandene Dateien unter `assets`, `PrivacyAware` bei `privacy.personalData`.
- **Code:** Die Einstiegsklasse und **alle** Klassen unter `src/` werden in einem eigenen PHP-Prozess geladen. Ein Syntaxfehler oder eine fehlende Klasse irgendwo unter `src/` macht das Plugin unbrauchbar – auch wenn die Klasse selten benutzt wird.
- **Dateirechte:** wie beim Laden in Produktion (Status „unsicher“), außer die Prüfung ist abgeschaltet.
- **Migrationen:** Dateinamen, Zerlegung in Anweisungen, erlaubtes SQL (siehe [Datenbank und Migrationen](/plugins/datenbank#migrationsdateien)), Warnung bei `CREATE TABLE` ohne `community_id` und bei nicht idempotenten Anweisungen, Prüfsummen bereits ausgeführter Dateien gegen die Datenbank.
- **Oberfläche:** gebautes `dist/` nach denselben Regeln wie `npm run build:plugins` und `frontend/*.css` (Verweis auf das Theme, siehe [Frontend-SDK → Bauen](/plugins/frontend#bauen)).
- **Vorlagen:** `|raw`, `{% apply raw %}`, `{% autoescape false %}`, `source()`, `template_from_string()` und das Einbinden fremder Vorlagen in `templates/` sind Fehler – schon beim Laden, das Plugin ist dann nicht ladbar (Kommentare zählen nicht). Für `templates/blocks` und `templates/forms` warnt die Prüfung außerdem bei fehlendem `@source` in `frontend/plugin.css`.

Fehler stehen als „Fehler“, Gründe für „unsicher“ und Warnungen darunter; dazu die Zahl der Migrationsdateien und welche noch offen sind.

## Statische Prüfungen

Die Werkzeuge der Entwicklungsumgebung schließen `plugins/*` ein: PHPStan (Stufe 8) mit eigenen Regeln für Plugins (siehe [Grenzen und Regeln](/plugins/grenzen)), eine Architekturprüfung (Plugins hängen nur von `App\Plugin\Api`, eigenen Klassen, `Psr\Log`, `Psr\Clock`, `Doctrine\DBAL`, `Symfony\Component\Uid` und PHP selbst ab), php-cs-fixer, ESLint (u. a. ohne `v-html` und nur erlaubte Importe), Prettier und vue-tsc. Sie laufen über das ganze Projekt, z. B. `vendor/bin/phpstan analyse` und `npm run lint`.

## PHPUnit mit dem Testkit

Tests liegen unter `plugins/<id>/tests/` im Namespace `<Namespace>\Tests\` und gehören zur Testsuite `plugins`. Ausführen in der Entwicklungsumgebung – immer mit `APP_ENV=test`:

```bash
docker compose exec -e APP_ENV=test app vendor/bin/phpunit plugins/hallo-welt/tests
docker compose exec -e APP_ENV=test app vendor/bin/phpunit --testsuite plugins
```

Integrationstests erben von `App\Tests\Support\Plugin\PluginTestCase`. Sie laufen gegen eine eigene Test-Datenbank mit zwei Communities, `testcom` und `othercom`, und den Konten `$this->owner`, `$this->moderator`, `$this->member`, `$this->mutedMember` und `$this->outsider`. Die Migrationen der Plugins unter `plugins/` laufen vor dem ersten Test automatisch.

```php
namespace QuickTribePlugin\HalloWelt\Tests;

use App\Tests\Support\Plugin\PluginTestCase;

final class GreetingApiTest extends PluginTestCase
{
    public function testMemberReadsOwnName(): void
    {
        $this->enablePlugin('hallo-welt');                                  // plattformweit und in testcom
        $response = $this->pluginApi('GET', 'hallo-welt', '/me', as: $this->member);
        self::assertSame(200, $response->getStatusCode());
    }

    public function testOtherCommunityStaysHidden(): void
    {
        $this->enablePlugin('hallo-welt');
        $response = $this->pluginApi('GET', 'hallo-welt', '/me', as: $this->member, slug: 'othercom');
        self::assertSame(404, $response->getStatusCode());
    }
}
```

| Methode | Zweck |
| --- | --- |
| `enablePlugin(string $id, ?string $slug = 'testcom')` | plattformweit aktivieren und in der Community einschalten (`null` = nur plattformweit) |
| `disablePluginIn(string $id, string $slug = 'testcom')` | in einer Community ausschalten |
| `pluginApi(string $method, string $id, string $path, array $body = [], ?User $as = null, ?string $slug = 'testcom', array $headers = [])` | Plugin-Endpunkt aufrufen, CSRF automatisch; `slug: null` für Endpunkte ohne Community |
| `pluginUpload(string $id, string $path, array $files, array $fields = [], ?User $as = null, ?string $slug = 'testcom', string $method = 'POST')` | Upload |
| `pendingHooks()`, `flushHooks()` | aufgezeichnete Hooks ansehen bzw. zustellen – für Aufrufe ohne Request; Requests über `pluginApi()` stellen ihre Hooks selbst zu |
| `runJob(string $id, string $job)`, `runJobOrFail()` | Job sofort ausführen; `…OrFail` lässt den Test mit der Ausnahme des Plugins scheitern |
| `runTask(string $id, string $task, array $payload = [], ?string $slug = 'testcom', ?User $actor = null)`, `runTaskOrFail()` | Aufgabe direkt ausführen, wie im Worker |
| `capturePluginLog()` | Log-Kanal `plugins` mitlesen |
| `communityId(string $slug = 'testcom')` | ID einer Test-Community |
| `pluginContext(string $id)` | der `PluginContext` des Plugins im Test – für Aufrufe der Kern-Dienste und von `db()` ohne Request |
| `deliver()` | wie am Ende eines Requests: aufgezeichnete Hooks zustellen, danach offene Löschungen (`deleteUserData()`, `deleteCommunityData()`) – nach Aufrufen ohne Request |
| `pluginState(string $id, string $key, ?Community $community = null, mixed $default = null)` | Wert aus `state()` des Plugins (global oder je Community) |
| `assertHookData(string $hook, array $data)` | Daten eines Hooks enthalten genau die Schlüssel aus dem [Hook-Katalog](/plugins/hooks) |
| `rankLeaderboard(array $ranking, ?User $viewer = null, string $period = 'all', string $slug = 'testcom')` *(ab 1.2)* | Filter `leaderboard.ranking` aller eingeschalteten Plugins auf eine Liste `[['membershipId' => …, 'points' => …], …]` anwenden |
| `sequencePlaceholders(string $text, array $recipients, ?string $eventId = null, ?string $occurrenceStart = null, string $slug = 'testcom', bool $preview = false)` *(ab 1.2)* | Werte der Platzhalter in `$text` für die Personen in `$recipients` wie beim Versand eines Serien-Schritts (`userId` → Platzhalter → Wert) |
| `checkFormField(string $pluginType, string\|array $value, ?User $as = null, string $slug = 'testcom')` *(ab 1.2)* | Antwort eines Feldtyps prüfen wie beim Absenden: `[normalisiert, null]` oder `[null, Meldung]` |
| `renderPageBlock(string $pluginId, string $block, array $data, ?User $viewer = null, string $slug = 'testcom')` *(ab 1.2)* | Baustein rendern wie die öffentliche Landingpage – sanitisiertes HTML oder `''` |
| `membership(User $user, ?Community $community = null)` | Mitgliedschaft einer Person (Standard `testcom`), z. B. für `membership_id` in Testdaten |
| `em()`, `fresh(object $entity)` | Doctrine ohne den Mandanten-Filter des letzten Requests bzw. eine Entity frisch geladen – für Prüfungen über Communities hinweg |
| `activation()`, `markMigrated(string $id, string $version, string $checksum)` | Aktivierungszustand; einen abgeschlossenen Migrationslauf eintragen (für Test-Plugins außerhalb von `plugins/`) |

- **Pflicht je Endpunkt:** ein Test für den Normalfall, für Validierung (`422`), für Berechtigung (`401`/`403`/`404`) und für die **Mandantentrennung** – derselbe Aufruf aus bzw. gegen `othercom` liefert nie Daten aus `testcom`.
- Aktivieren führt im Test keine Migrationen aus; sie laufen vorab für alle Plugins in `plugins/`.
- Im Test laufen Aufgaben sofort. Schickt ein Handler während eines Requests eine Aufgabe ab, läuft sie deshalb **innerhalb** dieses Requests: Community und handelnde Person sind wie im Worker, aber der Request wartet auf die Aufgabe, und ihr Fehler steht nur im Log (`plugin.<id>.task_failed`). Ergebnis und Fehler einer Aufgabe prüft man mit `runTask()`/`runTaskOrFail()`.
- Plugin-Klassen ohne Kern-Abhängigkeit (Berechnungen, Formatierungen) testet man als gewöhnliche Unit-Tests.
- **Forderungen ohne Kern** (ab Plugin-API 1.1): siehe [Forderungen ohne Kern testen](#forderungen-ohne-kern-testen).

## Forderungen ohne Kern testen

Ab Plugin-API 1.1 ersetzt `App\Tests\Support\Plugin\InMemoryDebits` den Dienst `debits()` in Unit-Tests. Die Attrappe verhält sich wie der echte Dienst – derselbe Vertragstest (`tests/Support/Plugin/DebitsContract`) läuft gegen beide: Idempotenz über die Referenz, Formfehler, Storno-Regeln, Teilausgleich, Überfälligkeit gegen die Uhr, Akteur, Limits, GET-Sperre und Hooks nur an die eigene Quelle. Übergib dem eigenen Code die Attrappe dort, wo er sonst `$ctx->debits()` nutzt (zum Beispiel über einen Konstruktor-Parameter vom Typ `App\Plugin\Api\Service\Debits`).

```php
use App\Plugin\Api\Model\ClaimInput;
use App\Plugin\Api\Model\ClaimStatus;
use App\Tests\Support\Plugin\InMemoryDebits;
use Symfony\Component\Clock\MockClock;

$clock = new MockClock('2026-11-01 09:00:00 Europe/Berlin');
$debits = new InMemoryDebits('schiessbuch', $clock);          // Quelle = Plugin-ID
$debits->addCommunity($communityId, 'sv-musterhausen');
$debits->addMembership($communityId, $membershipId, $userId);

$results = $debits->submitMany($communityId, [
    new ClaimInput($membershipId, 1250, 'Munition Oktober', 'sb:2026-10:'.$membershipId.':ammo', '2026-11-01'),
    new ClaimInput($membershipId, 800, 'Verzehr Oktober', 'sb:2026-10:'.$membershipId.':food', '2026-11-01'),
]);
self::assertSame(['created', 'created'], [$results[0]->outcome, $results[1]->outcome]);

// Rückbuchung nachstellen, Uhr vorstellen: ab dem 24.11. überfällig
$debits->simulate($results[0]->claim->id, ClaimStatus::Returned, overdueOn: '2026-11-24', returnReason: 'insufficient_funds');
$clock->modify('2026-11-24 08:00');
self::assertTrue($debits->get($communityId, $results[0]->claim->id)->overdue);

// Hooks, die der Kern an dieses Plugin schicken würde
$debits->cancel($communityId, $results[1]->claim->id, 'falsch gemeldet');
self::assertSame('claim.cancelled', $debits->hooks[array_key_last($debits->hooks)]['name']);
```

| Methode | Zweck |
| --- | --- |
| `new InMemoryDebits(string $pluginId, ClockInterface $clock)` | Attrappe für ein Plugin; Überfälligkeit und „heute“ rechnet sie mit `$clock` |
| `addCommunity(string $communityId, string $slug, bool $pluginEnabled = true, ?DebitSetup $setup = null)` | Community anlegen, optional mit eigenem `DebitSetup` (sonst Lastschrift aus, Datei-Verfahren) |
| `setPluginEnabled(string $communityId, bool $enabled)` | Plugin in der Community aus- bzw. einschalten (`submit()` wirft dann `Conflict`) |
| `addMembership(string $communityId, string $membershipId, string $userId, bool $canRead = true, bool $accountDeleted = false)` | Mitgliedschaft; nicht lesend bzw. mit gelöschtem Konto für die Ausschlussfälle |
| `addTreasurer(string $communityId, string $userId)` | Person mit Kassenrecht (sieht in `standings()` Beträge) |
| `setMandate(string $communityId, MandateInfo $mandate)` | Mandatsstand für `mandates()` |
| `setPlanRightsPaused(string $communityId, string $membershipId, bool $paused = true)` | Plan mit ruhenden Rechten – zählt in `standings()` als Zahlungsproblem |
| `simulate(string $claimId, ClaimStatus $status, ?int $openCents = null, ?string $overdueOn = null, ?string $returnReason = null, ?int $dunningLevel = null)` | Zustand setzen, den Einzug, Rückbuchung oder Mahnung im Kern hinterließen |
| `request(?string $userId, bool $readOnly, Closure $work)` | wie ein Request der Person `$userId`: als Akteur ist nur sie erlaubt; mit `$readOnly = true` (GET) werfen schreibende Methoden `LogicException` |
| `$hooks` | aufgezeichnete Hooks `claim.*` als Liste von `['name' => …, 'communityId' => …, 'data' => …]` |

Für `standings()` braucht der Test einen `App\Plugin\Api\Model\Viewer`; im Test darf er ihn selbst erzeugen (im Plugin-Code kommt er immer vom Kern). Integrationstests gegen den echten Dienst schreibt man mit `PluginTestCase` und `pluginContext($id)->debits()`.

## Playwright

Browser-Tests liegen unter `plugins/<id>/tests/e2e/*.spec.ts` und laufen in eigenen Projekten (`plugins-chromium`, `plugins-mobile`) mit den Tests der Plattform, z. B. `docker compose exec app npx playwright test --project=plugins-chromium` bzw. für ein Plugin `docker compose exec app npx playwright test plugins/<id>/tests/e2e`. Die Demo-Daten der Entwicklungsumgebung (`php bin/console app:fixtures:load`) aktivieren alle erkannten Plugins plattformweit und in der Community `demo`. Jede Datei muss für sich allein bestehen (die Tests laufen verteilt), und Konsolenfehler oder Verstöße gegen die Sicherheitsrichtlinie gelten als Fehler. Die Helfer der Plattform (`login`, `joinDemo` …) stehen in `tests/e2e/helpers.ts`; aus `plugins/<id>/tests/e2e/` heißt der Import `../../../../tests/e2e/helpers`. Ein vollständiges Szenario zeigt `tests/e2e/bring-list.spec.ts` im [Beispiel-Plugin](/plugins/beispiel-plugin).

## Übersetzungen

Deutsch ist **Quelltext und Schlüssel**: Texte stehen auf Deutsch im Code, mit Platzhaltern wie `{name}`. Englisch steht in `translations/messages.en.json`:

```json
{
  "Fahrgemeinschaften": "Carpools",
  "Neue Mitfahranfrage": "New ride request",
  "{name} möchte am {date} mitfahren.": "{name} would like to ride along on {date}.",
  "Ein freier Platz": "One free seat",
  "{count} freie Plätze": "{count} free seats"
}
```

**Kein ICU-Plural** (`{count, plural, one {…} other {…}}`): PHP und Twig könnten ihn formatieren, die Oberfläche (`sdk.t()`) nicht – dort wirft ein solcher Text einen Fehler, die Komponente scheitert, und das Plugin verschwindet aus allen Slots der Seite. Einzahl und Mehrzahl stehen deshalb wie in QuickTribe selbst als eigene Texte, die Auswahl trifft der Code: in Vue `count === 1 ? t('Ein freier Platz') : t('{count} freie Plätze', { count })`, in PHP z. B. mit `match`.

Dieselbe Datei nutzen

- PHP – Meldungen von Ausnahmen, Benachrichtigungen, Seitentitel, Menüpunkte, Feld- und Einstellungsnamen, Hinweise und `translator()->trans()`; ohne Eintrag gilt der Katalog der Plattform, sonst bleibt der deutsche Text;
- Twig-Vorlagen für E-Mail und PDF über den Filter `ptrans` (in der Sprache des Empfängers);
- die Oberfläche über `sdk.addMessages('en', en)` und `sdk.t()`.

`npm run build:plugins` warnt, `npm run i18n:check` scheitert bei `t('…')`-Texten der Oberfläche ohne englischen Eintrag.
