Intégration CI AppFolio
Vue d'ensemble
Configurez des pipelines CI qui valident les intégrations avec l'API de gestion immobilière AppFolio en utilisant une stratégie à deux niveaux. Les tests unitaires mockent le client REST AppFolio pour vérifier la recherche de locataires, la création d'ordres de travail et la logique de listing de propriétés sans consommer de quota API. Les tests d'intégration s'exécutent contre l'environnement bac à sable (sandbox) d'AppFolio uniquement lors des fusions sur la branche principale, en utilisant des identifiants d'authentification Basic stockés en tant que secrets GitHub. Cela maintient un feedback rapide et gratuit sur les pull requests tout en détectant les dérives réelles du contrat API avant les déploiements en production.
Prérequis
- Un dépôt avec Actions activées, une installation de dépendances verrouillée et des tests unitaires qui utilisent uniquement des fixtures synthétiques (locataires, propriétés, ordres de travail).
- Un identifiant bac à sable AppFolio géré séparément et un enregistrement de fixture pré-provisionné et non-production que le propriétaire de l'intégration est autorisé à lire.
- Une propriété CI définie, un budget de requêtes fixe et un chemin d'incident pour la rotation des identifiants, une panne du fournisseur ou une réinitialisation des données du bac à sable.
Instructions
- Conservez les vérifications des pull requests limitées aux mocks ; n'exposez pas les identifiants AppFolio à du code non fiable ou à des pull requests forchées.
- Limitez le job bac à sable aux pushes protégés sur
mainaprès la réussite des vérifications lint, type et unitaires, et injectez les identifiants uniquement via les secrets du dépôt. - Limitez l'exécution de l'intégration à une fixture en lecture seule connue, un seul worker et le budget de requêtes indiqué ; enregistrez uniquement le statut et le nombre d'appels expurgés.
- Traitez l'échec d'authentification, les limites de débit ou les fixtures manquantes comme une condition de blocage de release plutôt que de créer des données de bac à sable partagées depuis la CI.
Workflow GitHub Actions
# .github/workflows/appfolio-tests.yml
name: Tests API AppFolio
on: [push, pull_request]
jobs:
tests-unitaires:
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 # Aucun identifiant API nécessaire
tests-integration:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: tests-unitaires
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 }}
Tests Unitaires avec Mocks
// 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('crée un ordre de travail de maintenance pour une propriété', async () => {
vi.mocked(appfolioClient.post).mockResolvedValue({
id: 'wo-4821',
property_id: 'prop-100',
category: 'Plomberie',
status: 'Ouvert',
});
const result = await createWorkOrder('prop-100', 'Plomberie', 'Robinet qui fuit unité 3B');
expect(result.status).toBe('Ouvert');
expect(appfolioClient.post).toHaveBeenCalledWith('/work_orders', {
property_id: 'prop-100',
category: 'Plomberie',
description: 'Robinet qui fuit unité 3B',
});
});
});
Tests d'Intégration
// 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)('Recherche de locataire AppFolio (bac à sable en direct)', () => {
const client = new AppFolioClient({
clientId: process.env.APPFOLIO_CLIENT_ID!,
clientSecret: process.env.APPFOLIO_CLIENT_SECRET!,
baseUrl: process.env.APPFOLIO_BASE_URL!,
});
it('liste les locataires d'une propriété connue', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
Gestion du Budget CI
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // Le bac à sable AppFolio a une limite de 100 req/min
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`Budget API CI dépassé : ${callCount}/${MAX_CALLS_PER_RUN} appels. ` +
'Réduisez la portée des tests d\'intégration ou répartissez-les entre plusieurs jobs.'
);
}
}
export function getCallCount(): number { return callCount; }
Gestion des Erreurs
| Problème CI | Cause | Solution |
|---|---|---|
| 401 Non autorisé dans le job d'intégration | Identifiants du bac à sable expirés ou modifiés | Régénérez APPFOLIO_CLIENT_ID et APPFOLIO_CLIENT_SECRET dans les secrets GitHub |
| 429 Trop de requêtes | Limite de débit du bac à sable (100 req/min) atteinte par des tests parallèles | Exécutez les tests d'intégration avec --maxWorkers=1 |
| Liste des locataires vide | Données du bac à sable réinitialisées périodiquement par AppFolio | Arrêtez le job et restaurez la fixture pré-provisionnée en dehors de la CI |
| Échec de vérification de type sur la réponse API | Schéma AppFolio mis à jour sans préavis | Régénérez les types à partir de la spécification OpenAPI, mettez à jour les interfaces |
| Job d'intégration ignoré | La règle de protection de branche ne correspond pas à refs/heads/main | Vérifiez que la condition if du workflow correspond au nom de votre branche par défaut |
Sortie
- Résultats des pull requests provenant des vérifications unitaires, lint et type avec mocks uniquement
- Un reçu du bac à sable de la branche protégée avec le statut expurgé du fournisseur, l'identité de la fixture, le nombre de requêtes et le résultat du test d'intégration
- Une décision de release bornée qui bloque en cas d'identifiants indisponibles, d'erreurs du fournisseur, de dérive de fixture ou d'épuisement du budget de requêtes
Exemples
Pour une modification du mappage des ordres de travail, ajoutez une réponse mockée synthétique et vérifiez le nouveau champ dans la suite de tests de la PR. Après la fusion, le workflow protégé main lit un ordre de travail pré-provisionné du bac à sable et confirme la forme normalisée sans créer de locataires, propriétés ou ordres de travail. Si la fixture est indisponible, l'identifiant échoue ou le budget de requêtes est dépassé, marquez la release comme bloquée et demandez au propriétaire du bac à sable de restaurer la fixture ou l'identifiant avant de réexécuter la lane en direct.
Ressources
Prochaines étapes
Voir appfolio-deploy-integration.