Integração CI AppFolio
Visão Geral
Configure pipelines de CI que validam integrações com a API de gestão de propriedades AppFolio usando uma estratégia de dois níveis. Testes de unidade simulam o cliente REST do AppFolio para verificar a lógica de consulta de inquilinos, criação de ordens de serviço e listagem de propriedades sem consumir cota de API. Testes de integração são executados contra o ambiente sandbox do AppFolio apenas em merges na branch principal, usando credenciais de autenticação básica armazenadas como segredos do GitHub. Isso mantém o feedback de PRs rápido e gratuito enquanto captura desvios reais no contrato da API antes dos deploys em produção.
Pré-requisitos
- Um repositório com Actions habilitadas, instalação de dependências travada e testes de unidade que usam apenas fixtures sintéticas de inquilinos, propriedades e ordens de serviço.
- Uma credencial de sandbox AppFolio gerenciada separadamente e um registro de fixture não produtivo pré-provisionado que o proprietário da integração tenha permissão para ler.
- Propriedade de CI definida, um orçamento de requisições fixo e um caminho de incidente para rotação de credenciais, indisponibilidade do provedor ou redefinição de dados do sandbox.
Instruções
- Mantenha as verificações de pull-request apenas com mocks; não exponha credenciais AppFolio a código não confiável ou pull requests bifurcados.
- Proteja o job do sandbox ao vivo para pushes protegidos na
mainapós lint, type e testes de unidade passarem, e injete credenciais apenas através de segredos do repositório. - Limite a execução da integração a uma fixture somente leitura conhecida, um worker e o orçamento de requisições declarado; registre apenas evidências de status e contagem editadas.
- Trate falhas de autenticação, limites de taxa ou fixtures ausentes como uma condição de bloqueio de lançamento, em vez de criar dados de sandbox compartilhados a partir do CI.
Workflow do GitHub Actions
# .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 # Nenhuma credencial de API necessária
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 }}
Testes de Unidade com Mock
// 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('cria uma ordem de serviço de manutenção para uma propriedade', 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',
});
});
});
Testes de Integração
// 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 Tenant Lookup (sandbox ao 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 uma propriedade conhecida', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
Gerenciamento de Custos de CI
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // Sandbox AppFolio tem limite de 100 req/min
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`Orçamento de API de CI excedido: ${callCount}/${MAX_CALLS_PER_RUN} chamadas. ` +
'Reduza o escopo do teste de integração ou divida entre jobs.'
);
}
}
export function getCallCount(): number { return callCount; }
Tratamento de Erros
| Problema de CI | Causa | Solução |
|---|---|---|
| 401 Não Autorizado no job de integração | Credenciais de sandbox expiradas ou rotacionadas | Regere APPFOLIO_CLIENT_ID e APPFOLIO_CLIENT_SECRET nos Segredos do GitHub |
| 429 Muitas Requisições | Limite de taxa do sandbox (100 req/min) atingido por testes paralelos | Execute testes de integração com --maxWorkers=1 |
| Lista de inquilinos vazia | Dados do sandbox redefinidos periodicamente pela AppFolio | Pare o job e restaure a fixture pré-provisionada fora do CI |
| Typecheck falha na resposta da API | Esquema da AppFolio atualizado sem aviso | Regere tipos a partir da especificação OpenAPI, atualize interfaces |
| Job de integração pulado | Regra de proteção de branch não corresponde a refs/heads/main | Verifique se a condição if do workflow corresponde ao nome da sua branch padrão |
Saída
- Resultados de pull-request a partir de verificações de lint, type e testes de unidade apenas com mock
- Um comprovante de sandbox de branch protegida com o status do provedor editado, identidade da fixture, contagem de requisições e resultado do teste de integração
- Uma decisão de lançamento limitada que bloqueia em caso de credenciais indisponíveis, erros do provedor, desvio de fixture ou esgotamento do orçamento de requisições
Exemplos
Para uma alteração no mapeamento de ordens de serviço, adicione uma resposta mock sintética e verifique o novo campo no conjunto de PRs. Após o merge, o workflow protegido da main lê uma ordem de serviço sandbox pré-provisionada e confirma a forma normalizada sem criar inquilinos, propriedades ou ordens de serviço. Se a fixture estiver indisponível, a credencial falhar ou o orçamento de requisições for excedido, marque o lançamento como bloqueado e peça ao proprietário do sandbox para restaurar a fixture ou credencial antes de reexecutar a pista ao vivo.
Recursos
Próximos Passos
Veja appfolio-deploy-integration.