AppFolio CI Integration
Überblick
Konfiguriere CI-Pipelines, die AppFolio Immobilienverwaltungs-API-Integrationen validieren, unter Verwendung einer zweistufigen Strategie. Unit-Tests mocken den AppFolio REST-Client, um Mieterabfragen, Arbeitsauftragserstellung und Immobilienlogik zu überprüfen, ohne das API-Kontingent zu verbrauchen. Integrationstests laufen gegen die AppFolio Sandbox-Umgebung nur bei Merges auf den Hauptzweig und verwenden Basic-Auth-Zugangsdaten, die als GitHub Secrets gespeichert sind. Dies hält PR-Feedback schnell und kostenlos, während echte API-Vertragsänderungen vor Produktionsdeployments erkannt werden.
Voraussetzungen
- Ein Repository mit aktivierten Actions, einer gesperrten Abhängigkeitsinstallation und Unit-Tests, die nur synthetische Mieter-, Immobilien- und Arbeitsauftrags-Fixtures verwenden.
- Ein separat verwaltetes AppFolio Sandbox-Anmeldedatenpaar und ein vorab bereitgestellter, nicht-produktiver Fixture-Datensatz, den der Integrationsverantwortliche lesen darf.
- Definierte CI-Verantwortung, ein festgelegtes Request-Budget und ein Incident-Pfad für die Rotation von Zugangsdaten, Ausfall des Anbieters oder Zurücksetzen der Sandbox-Daten.
Anleitung
- Halte Pull-Request-Prüfungen reinen Mock-basiert; setze AppFolio-Zugangsdaten keinen nicht vertrauenswürdigen Codes oder geforkten Pull-Requests aus.
- Beschränke den Live-Sandbox-Job auf geschützte
main-Pushes, nachdem Lint-, Typ- und Unit-Prüfungen bestanden sind, und injiziere Zugangsdaten nur über Repository-Secrets. - Begrenze den Integrationslauf auf einen bekannten, schreibgeschützten Fixture, einen Worker und das angegebene Request-Budget; protokolliere nur die geschwärzten Status- und Zählergegebenheiten.
- Behandle fehlgeschlagene Authentifizierung, Ratenbegrenzungen oder fehlende Fixtures als blockierte Release-Bedingung, anstatt gemeinsame Sandbox-Daten aus der CI zu erstellen.
GitHub Actions Workflow
# .github/workflows/appfolio-tests.yml
name: AppFolio API Tests
on: [push, pull_request]
jobs:
unit-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm run lint && npm run typecheck
- run: npm test -- --testPathPattern=unit # Keine API-Zugangsdaten erforderlich
integration-tests:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: unit-tests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm test -- --testPathPattern=integration
env:
APPFOLIO_CLIENT_ID: ${{ secrets.APPFOLIO_CLIENT_ID }}
APPFOLIO_CLIENT_SECRET: ${{ secrets.APPFOLIO_CLIENT_SECRET }}
APPFOLIO_BASE_URL: ${{ secrets.APPFOLIO_SANDBOX_URL }}
Mock-basierte Unit-Tests
// tests/unit/work-order-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createWorkOrder } from '../../src/services/work-order-service';
import * as appfolioClient from '../../src/lib/appfolio-client';
vi.mock('../../src/lib/appfolio-client');
describe('WorkOrderService', () => {
it('erstellt einen Wartungsauftrag für eine Immobilie', async () => {
vi.mocked(appfolioClient.post).mockResolvedValue({
id: 'wo-4821',
property_id: 'prop-100',
category: 'Plumbing',
status: 'Open',
});
const result = await createWorkOrder('prop-100', 'Plumbing', 'Undichter Wasserhahn Einheit 3B');
expect(result.status).toBe('Open');
expect(appfolioClient.post).toHaveBeenCalledWith('/work_orders', {
property_id: 'prop-100',
category: 'Plumbing',
description: 'Undichter Wasserhahn Einheit 3B',
});
});
});
Integrationstests
// tests/integration/tenant-lookup.test.ts
import { describe, it, expect } from 'vitest';
import { AppFolioClient } from '../../src/lib/appfolio-client';
const canRun = process.env.APPFOLIO_CLIENT_ID && process.env.APPFOLIO_CLIENT_SECRET;
describe.skipIf(!canRun)('AppFolio Mieterabfrage (Live-Sandbox)', () => {
const client = new AppFolioClient({
clientId: process.env.APPFOLIO_CLIENT_ID!,
clientSecret: process.env.APPFOLIO_CLIENT_SECRET!,
baseUrl: process.env.APPFOLIO_BASE_URL!,
});
it('listet Mieter für eine bekannte Immobilie', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
CI-Kostenmanagement
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // AppFolio Sandbox hat ein Ratenlimit von 100 req/min
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`CI-API-Budget überschritten: ${callCount}/${MAX_CALLS_PER_RUN} Aufrufe. ` +
'Reduziere den Integrationstestumfang oder teile die Tests auf mehrere Jobs auf.'
);
}
}
export function getCallCount(): number { return callCount; }
Fehlerbehandlung
| CI-Problem | Ursache | Behebung |
|---|---|---|
| 401 Unauthorized im Integrationsjob | Abgelaufene oder rotierte Sandbox-Zugangsdaten | APPFOLIO_CLIENT_ID und APPFOLIO_CLIENT_SECRET in den GitHub Secrets neu generieren |
| 429 Too Many Requests | Sandbox-Ratenlimit (100 req/min) durch parallele Tests erreicht | Integrationstests mit --maxWorkers=1 ausführen |
| Mieterliste leer | Sandbox-Daten werden von AppFolio regelmäßig zurückgesetzt | Job anhalten und den vorab bereitgestellten Fixture außerhalb der CI wiederherstellen |
| Typprüfung schlägt bei API-Antwort fehl | AppFolio-Schema ohne Vorankündigung aktualisiert | Typen aus OpenAPI-Spezifikation neu generieren, Schnittstellen aktualisieren |
| Integrationsjob übersprungen | Branch-Schutzregel stimmt nicht mit refs/heads/main überein | Überprüfen, ob die if-Bedingung des Workflows mit Ihrem Standard-Branch-Namen übereinstimmt |
Ausgabe
- Pull-Request-Ergebnisse aus reinen Mock-basierten Lint-, Typ- und Unit-Prüfungen
- Ein Sandbox-Beleg des geschützten Branches mit dem geschwärzten Anbieterstatus, der Fixture-Identität, der Anzahl der Anfragen und dem Ergebnis des Integrationstests
- Eine begrenzte Release-Entscheidung, die bei nicht verfügbaren Zugangsdaten, Anbieterfehlern, Fixture-Abweichungen oder Erschöpfung des Request-Budgets blockiert
Beispiele
Bei einer Änderung der Arbeitsauftragszuordnung füge eine synthetische Mock-Antwort hinzu und überprüfe das neue Feld in der PR-Suite. Nach dem Merge liest der geschützte Hauptzweig-Workflow einen vorab bereitgestellten Sandbox-Arbeitsauftrag und bestätigt die normalisierte Form, ohne Mieter, Immobilien oder Arbeitsaufträge zu erstellen. Wenn der Fixture nicht verfügbar ist, die Zugangsdaten fehlschlagen oder das Request-Budget überschritten wird, markiere die Version als blockiert und lasse den Sandbox-Verantwortlichen den Fixture oder die Zugangsdaten wiederherstellen, bevor die Live-Spur erneut ausgeführt wird.
Ressourcen
Nächste Schritte
Siehe appfolio-deploy-integration.