AppFolio CI 統合 は何をしますか?
概要
AppFolio 不動産管理 API 統合を検証する CI パイプラインを、2 段階戦略で構成します。単体テストは AppFolio REST クライアントをモック化し、テナント検索、作業指示作成、物件一覧ロジックを API クォータを消費せずに検証します。統合テストはメインブランチマージ時のみ AppFolio サンドボックス環境に対して実行され、Basic 認証情報は GitHub Secrets として保存されます。これにより、PR フィードバックは高速かつ無料のまま、本番デプロイ前に実際の API 契約のずれを検出できます。
前提条件
- Actions が有効化されたリポジトリ、ロックされた依存関係のインストール、および合成テナント、物件、作業指示フィクスチャのみを使用する単体テスト
- 別途管理された AppFolio サンドボックス認証情報と、統合テスト担当者が読み取りを許可された事前プロビジョニング済みの非本番フィクスチャレコード
- 定義された CI 所有権、固定のリクエスト予算、および認証情報のローテーション、プロバイダ障害、サンドボックスデータリセットのためのインシデントパス
手順
- プルリクエストチェックはモックのみに限定し、AppFolio 認証情報を信頼されていないコードやフォークされた PR に公開しないでください。
- ライブサンドボックスジョブは、リント、型チェック、単体テストが合格した後の保護された
mainプッシュにゲートし、認証情報はリポジトリシークレットを通じてのみ注入してください。 - 統合テストの実行は、既知の読み取り専用フィクスチャ、1 ワーカー、および明示されたリクエスト予算に制限し、編集されたステータスとカウント証跡のみを記録してください。
- 認証失敗、レート制限、またはフィクスチャの欠落は、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 # 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 }}
モックベース単体テスト
// 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 サンドボックスは 100 req/min のレート制限
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 Unauthorized | サンドボックス認証情報の期限切れまたはローテーション | GitHub Secrets で APPFOLIO_CLIENT_ID と APPFOLIO_CLIENT_SECRET を再生成 |
| 429 Too Many Requests | サンドボックスのレート制限 (100 req/min) に並列テストが抵触 | 統合テストを --maxWorkers=1 で実行 |
| テナントリストが空 | AppFolio によるサンドボックスデータの定期的なリセット | ジョブを停止し、CI の外部で事前プロビジョニングされたフィクスチャを復元 |
| API レスポンスで型チェック失敗 | AppFolio スキーマが予告なく更新された | OpenAPI 仕様から型を再生成し、インターフェースを更新 |
| 統合ジョブがスキップされた | ブランチ保護ルールが refs/heads/main と一致していない | ワークフローの if 条件がデフォルトブランチ名と一致することを確認 |
出力
- モックのみのリント、型チェック、単体テストからのプルリクエスト結果
- 編集されたプロバイダステータス、フィクスチャ識別情報、リクエスト数、統合テスト結果を含む保護ブランチサンドボックスレシート
- 認証情報の利用不可、プロバイダエラー、フィクスチャのずれ、またはリクエスト予算の枯渇時にブロックする、範囲指定されたリリース決定
使用例
作業指示マッピングの変更の場合、新しいフィールドを合成モックレスポンスに追加し、PR スイートで検証します。マージ後、保護されたメインワークフローは、事前プロビジョニングされた 1 つのサンドボックス作業指示を読み取り、テナント、物件、作業指示を作成せずに正規化された形状を確認します。フィクスチャが利用できない場合、認証情報が失敗した場合、またはリクエスト予算を超えた場合は、リリースをブロックとマークし、サンドボックス所有者がフィクスチャまたは認証情報を復元してからライブラインを再実行してください。
リソース
次のステップ
appfolio-deploy-integration を参照してください。