Lucidchart ci integration

Lucidchart CI Integration

Overview

Configure CI pipelines that validate Lucidchart diagramming API integrations using a two-tier testing strategy. Unit tests mock the Lucidchart REST client to verify document creation, shape manipulation, and export logic without requiring OAuth2 credentials. Integration tests run on main-branch merges with a real OAuth2 token to confirm document CRUD, versioned API header handling, and export rendering against the live Lucidchart API. This separation keeps PR cycles fast while catching OAuth flow regressions and API version changes before they reach production.

GitHub Actions Workflow

# .github/workflows/lucidchart-tests.yml
name: Lucidchart 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 OAuth credentials needed

  integration-tests:
    runs-on: ubuntu-latest
    if: 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:
          LUCID_API_KEY: ${{ secrets.LUCID_API_KEY }}
          LUCID_CLIENT_SECRET: ${{ secrets.LUCID_CLIENT_SECRET }}

Mock-Based Unit Tests

// tests/unit/document-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createDiagram } from '../../src/services/document-service';
import * as lucidClient from '../../src/lib/lucid-client';

vi.mock('../../src/lib/lucid-client');

describe('DocumentService', () => {
  it('creates a flowchart document with initial shapes', async () => {
    vi.mocked(lucidClient.post).mockResolvedValue({
      documentId: 'doc-7742',
      title: 'CI Pipeline Diagram',
      pageCount: 1,
      editUrl: 'https://lucid.app/documents/edit/doc-7742',
    });

    const result = await createDiagram('CI Pipeline Diagram', 'flowchart');
    expect(result.documentId).toBe('doc-7742');
    expect(lucidClient.post).toHaveBeenCalledWith(
      '/documents',
      { title: 'CI Pipeline Diagram', template: 'flowchart' },
      { headers: { 'Lucid-Api-Version': '1' } }
    );
  });
});

Integration Tests

// tests/integration/document-export.test.ts
import { describe, it, expect } from 'vitest';
import { LucidClient } from '../../src/lib/lucid-client';

const canRun = process.env.LUCID_API_KEY && process.env.LUCID_CLIENT_SECRET;

describe.skipIf(!canRun)('Lucidchart Document Export (live API)', () => {
  const client = new LucidClient({
    apiKey: process.env.LUCID_API_KEY!,
    clientSecret: process.env.LUCID_CLIENT_SECRET!,
  });

  it('exports a document as PNG', async () => {
    const docs = await client.get('/documents', { limit: 1 });
    expect(docs.length).toBeGreaterThan(0);

    const exported = await client.get(`/documents/${docs[0].documentId}/export`, {
      format: 'png', page: 1,
    });
    expect(exported.contentType).toBe('image/png');
    expect(exported.data.length).toBeGreaterThan(0);
  });
});

CI Cost Management

// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 20; // Lucidchart API: OAuth token refresh + tight rate limits

export function trackApiCall(): void {
  callCount++;
  if (callCount > MAX_CALLS_PER_RUN) {
    throw new Error(
      `CI API budget exceeded: ${callCount}/${MAX_CALLS_PER_RUN} calls. ` +
      'Lucidchart enforces per-app rate limits — reduce export tests or batch requests.'
    );
  }
}

export function getCallCount(): number { return callCount; }

Error Handling

CI Issue	Cause	Fix
401 Unauthorized	OAuth2 token expired or client secret rotated	Re-run OAuth flow, update LUCID_API_KEY and LUCID_CLIENT_SECRET in GitHub Secrets
400 Bad Request on export	Missing Lucid-Api-Version header	Ensure all requests include { 'Lucid-Api-Version': '1' } header
Document not found (404)	Test document deleted or workspace changed	Create a dedicated CI workspace with persistent test documents
Rate limit (429) on export	PNG/PDF exports are expensive API calls	Cache export results, limit to 1 export test per CI run
Integration tests skipped	Missing both LUCID_API_KEY and LUCID_CLIENT_SECRET secrets	Add both secrets in repo Settings > Secrets and variables

Resources

• Lucidchart Developer API Reference
• GitHub Actions Encrypted Secrets

Next Steps

See lucidchart-deploy-integration.