¿Qué hace Integración CI de AppFolio?
Descripción general
Configura pipelines de CI que validan integraciones con la API de AppFolio para gestión de propiedades utilizando una estrategia de dos niveles. Las pruebas unitarias simulan el cliente REST de AppFolio para verificar la lógica de búsqueda de inquilinos, creación de órdenes de trabajo y listado de propiedades sin consumir cuota de API. Las pruebas de integración se ejecutan contra el entorno sandbox de AppFolio solo en fusiones a la rama main, utilizando credenciales Basic Auth almacenadas como secretos de GitHub. Esto mantiene la retroalimentación de las PR rápida y gratuita mientras detecta cambios en el contrato de la API antes de los despliegues a producción.
Prerrequisitos
- Un repositorio con Actions habilitado, una instalación de dependencias bloqueada y pruebas unitarias que utilicen únicamente fixtures sintéticos de inquilinos, propiedades y órdenes de trabajo.
- Una credencial de sandbox de AppFolio administrada por separado y un registro fixture preaprovisionado y no productivo que el propietario de la integración esté autorizado a leer.
- Propietario de CI definido, un presupuesto de solicitudes fijo y una ruta de incidentes para rotación de credenciales, interrupción del proveedor o restablecimiento de datos del sandbox.
Instrucciones
- Mantén las verificaciones de solicitudes de pull solo con mocks; no expongas las credenciales de AppFolio a código no confiable ni a solicitudes de pull bifurcadas.
- Bloquea el trabajo de sandbox en vivo solo para pushes a
mainprotegida después de que lint, tipo y pruebas unitarias pasen, e inyecta credenciales únicamente a través de secretos del repositorio. - Limita la ejecución de integración a un fixture conocido de solo lectura, un trabajador y el presupuesto de solicitudes indicado; registra solo evidencia de estado y recuento enmascarados.
- Trata la autenticación fallida, los límites de tasa o los fixtures faltantes como una condición de lanzamiento bloqueada en lugar de crear datos de sandbox compartidos desde CI.
Flujo de trabajo de GitHub Actions
# .github/workflows/appfolio-tests.yml
name: Pruebas de API de AppFolio
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 # No se necesitan credenciales de API
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 }}
Pruebas unitarias con 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('crea una orden de trabajo de mantenimiento para una propiedad', async () => {
vi.mocked(appfolioClient.post).mockResolvedValue({
id: 'wo-4821',
property_id: 'prop-100',
category: 'Plumbing',
status: 'Open',
});
const result = await createWorkOrder('prop-100', 'Plumbing', 'Leaking faucet unit 3B');
expect(result.status).toBe('Open');
expect(appfolioClient.post).toHaveBeenCalledWith('/work_orders', {
property_id: 'prop-100',
category: 'Plumbing',
description: 'Leaking faucet unit 3B',
});
});
});
Pruebas de integración
// 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)('Búsqueda de inquilino de AppFolio (sandbox en vivo)', () => {
const client = new AppFolioClient({
clientId: process.env.APPFOLIO_CLIENT_ID!,
clientSecret: process.env.APPFOLIO_CLIENT_SECRET!,
baseUrl: process.env.APPFOLIO_BASE_URL!,
});
it('lista inquilinos para una propiedad conocida', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
Gestión de costos de CI
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // El sandbox de AppFolio tiene un límite de 100 req/min
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`Presupuesto de API de CI excedido: ${callCount}/${MAX_CALLS_PER_RUN} llamadas. ` +
'Reduce el alcance de las pruebas de integración o divídelo entre trabajos.'
);
}
}
export function getCallCount(): number { return callCount; }
Manejo de errores
| Problema de CI | Causa | Solución |
|---|---|---|
| 401 No autorizado en trabajo de integración | Credenciales de sandbox expiradas o rotadas | Regenera APPFOLIO_CLIENT_ID y APPFOLIO_CLIENT_SECRET en los Secretos de GitHub |
| 429 Demasiadas solicitudes | Límite de tasa del sandbox (100 req/min) alcanzado por pruebas paralelas | Ejecuta pruebas de integración con --maxWorkers=1 |
| Lista de inquilinos vacía | Datos del sandbox restablecidos periódicamente por AppFolio | Detén el trabajo y restaura el fixture preaprovisionado fuera de CI |
| Fallo de tipo en respuesta de API | Esquema de AppFolio actualizado sin previo aviso | Regenera tipos desde la especificación OpenAPI, actualiza interfaces |
| Trabajo de integración omitido | Regla de protección de rama no coincide con refs/heads/main | Verifica que la condición if del flujo de trabajo coincida con el nombre de tu rama por defecto |
Salida
- Resultados de solicitudes de pull de verificaciones mock-only de lint, tipo y pruebas unitarias
- Un recibo de sandbox de rama protegida con el estado del proveedor enmascarado, identidad del fixture, recuento de solicitudes y resultado de la prueba de integración
- Una decisión de lanzamiento acotada que se bloquea en caso de credenciales no disponibles, errores del proveedor, desviación del fixture o agotamiento del presupuesto de solicitudes
Ejemplos
Para un cambio en el mapeo de órdenes de trabajo, agrega una respuesta sintética simulada y verifica el nuevo campo en el conjunto de pruebas de la PR. Después de la fusión, el flujo de trabajo protegido de main lee una orden de trabajo sandbox preaprovisionada y confirma la forma normalizada sin crear inquilinos, propiedades ni órdenes de trabajo. Si el fixture no está disponible, la credencial falla o se excede el presupuesto de solicitudes, marca el lanzamiento como bloqueado y haz que el propietario del sandbox restaure el fixture o la credencial antes de reejecutar el carril en vivo.
Recursos
Próximos pasos
Consulta appfolio-deploy-integration.