AppFolio CI 통합
개요
AppFolio 부동산 관리 API 통합을 검증하는 CI 파이프라인을 2계층 전략으로 구성합니다. 유닛 테스트는 AppFolio REST 클라이언트를 모킹(mocking)하여 세입자 조회, 작업 주문 생성, 부동산 목록 로직을 API 할당량 소모 없이 검증합니다. 통합 테스트는 메인 브랜치 병합 시에만 AppFolio 샌드박스 환경에서 실행되며, GitHub Secrets에 저장된 Basic Auth 자격 증명을 사용합니다. 이를 통해 PR 피드백은 빠르고 무료로 유지하면서, 프로덕션 배포 전에 실제 API 계약 변경을 감지할 수 있습니다.
사전 요구 사항
- Actions가 활성화된 저장소, 잠긴 종속성 설치, 그리고 합성 세입자, 부동산, 작업 주문 fixture만 사용하는 유닛 테스트
- 별도로 관리되는 AppFolio 샌드박스 자격 증명과 통합 소유자가 읽을 수 있도록 미리 프로비저닝된 비프로덕션 fixture 레코드
- 정의된 CI 소유권, 고정된 요청 예산, 자격 증명 교체, 공급자 중단 또는 샌드박스 데이터 재설정을 위한 인시던트 경로
지침
- 풀 리퀘스트 검사는 모크(mock) 전용으로 유지하고, AppFolio 자격 증명을 신뢰할 수 없는 코드나 포크된 풀 리퀘스트에 노출하지 마십시오.
- 라이브 샌드박스 작업을 lint, 타입, 유닛 검사 통과 후 보호된
main푸시로 제한하고, 자격 증명은 저장소 시크릿을 통해서만 주입하십시오. - 통합 실행을 알려진 읽기 전용 fixture, 단일 워커, 명시된 요청 예산으로 제한하고, 수정된 상태와 횟수 증거만 기록하십시오.
- 인증 실패, 속도 제한 또는 fixture 누락은 CI에서 공유 샌드박스 데이터를 생성하는 대신 릴리스 차단 조건으로 처리하십시오.
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 # No API credentials needed
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 기반 유닛 테스트
// 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('creates a maintenance work order for a property', 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',
});
});
});
통합 테스트
// 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 (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('lists tenants for a known property', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
CI 비용 관리
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // AppFolio sandbox has 100 req/min rate limit
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`CI API budget exceeded: ${callCount}/${MAX_CALLS_PER_RUN} calls. ` +
'Reduce integration test scope or split across jobs.'
);
}
}
export function getCallCount(): number { return callCount; }
오류 처리
| CI 문제 | 원인 | 해결 방법 |
|---|---|---|
| 통합 작업에서 401 인증 실패 | 샌드박스 자격 증명 만료 또는 교체 | GitHub Secrets에서 APPFOLIO_CLIENT_ID 및 APPFOLIO_CLIENT_SECRET 재생성 |
| 429 요청 너무 많음 | 병렬 테스트로 인한 샌드박스 속도 제한(분당 100회 요청) 도달 | --maxWorkers=1로 통합 테스트 실행 |
| 세입자 목록 비어 있음 | AppFolio에서 샌드박스 데이터를 주기적으로 재설정 | 작업을 중지하고 CI 외부에서 미리 프로비저닝된 fixture 복원 |
| API 응답에서 타입 검사 실패 | AppFolio 스키마가 사전 통지 없이 업데이트됨 | OpenAPI 사양에서 타입 재생성, 인터페이스 업데이트 |
| 통합 작업 건너뜀 | 브랜치 보호 규칙이 refs/heads/main과 일치하지 않음 | 워크플로우 if 조건이 기본 브랜치 이름과 일치하는지 확인 |
출력
- 모크 전용 lint, 타입, 유닛 검사 결과의 풀 리퀘스트 결과
- 수정된 공급자 상태, fixture ID, 요청 수, 통합 테스트 결과가 포함된 보호된 브랜치 샌드박스 영수증
- 자격 증명 사용 불가, 공급자 오류, fixture 변경 또는 요청 예산 소진 시 차단하는 제한된 릴리스 결정
예제
작업 주문 매핑 변경의 경우, 합성 모크 응답을 추가하고 PR 스위트에서 새 필드를 검증합니다. 병합 후, 보호된 메인 워크플로우는 미리 프로비저닝된 샌드박스 작업 주문 하나를 읽고 세입자, 부동산 또는 작업 주문을 생성하지 않고 정규화된 형태를 확인합니다. fixture를 사용할 수 없거나, 자격 증명이 실패하거나, 요청 예산이 초과된 경우, 릴리스를 차단으로 표시하고 라이브 실행을 다시 시작하기 전에 샌드박스 소유자가 fixture 또는 자격 증명을 복원하도록 합니다.
리소스
다음 단계
appfolio-deploy-integration을 참조하세요.