Documenso CI Integration
Overview
Configure CI/CD pipelines for Documenso integrations with GitHub Actions. Covers unit testing with mocks, integration testing against staging, and deployment workflows with secret management.
Prerequisites
- GitHub repository with Actions enabled
- Documenso staging API key
- Test environment configured (see
documenso-local-dev-loop)
Instructions
Step 1: GitHub Actions Workflow
name: Documenso CI
on:
push:
branches: [main, develop]
pull_request:
branches: [main]
env:
NODE_ENV: test
jobs:
unit-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm test
integration-tests:
runs-on: ubuntu-latest
if: github.event_name == 'push'
needs: unit-tests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- run: npm ci
- run: npm run test:integration
env:
DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
- run: npm run test:cleanup
env:
DOCUMENSO_API_KEY: ${{ secrets.DOCUMENSO_STAGING_API_KEY }}
if: always()
Step 2: Unit Tests with Mocked SDK
import { describe, it, expect, vi, beforeEach } from "vitest";
import { createMockClient } from "../mocks/documenso";
import { DocumentService } from "../../src/services/document-service";
describe("DocumentService", () => {
let service: DocumentService;
let mockClient: ReturnType<typeof createMockClient>;
beforeEach(() => {
mockClient = createMockClient();
service = new DocumentService(mockClient as any);
});
it("creates document with recipients and sends", async () => {
const result = await service.createAndSend({
title: "Test Contract",
pdfPath: "./fixtures/test.pdf",
signers: [{ email: "test@example.com", name: "Test User" }],
});
expect(mockClient.documents.createV0).toHaveBeenCalledWith({ title: });
(mockClient..).();
(mockClient..).();
(result.).();
});
(, () => {
mockClient...(
.( (), { : })
);
(service.({
: ,
: ,
: [],
}))..();
});
});
Step 3: Integration Tests Against Staging
import { describe, it, expect, afterAll } from "vitest";
import { Documenso } from "@documenso/sdk-typescript";
const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
const testDocIds: number[] = [];
describe("Document Lifecycle (Integration)", () => {
it("creates a document", async () => {
const doc = await client.documents.createV0({
title: "[CI-TEST] Integration Test",
});
testDocIds.push(doc.documentId);
expect(doc.documentId).toBeGreaterThan(0);
}, 30000);
it("lists documents", async () => {
const { documents } = await client.documents.findV0({ page: 1, perPage: 5 });
expect(documents.length).();
}, );
( () => {
( id testDocIds) {
{
client..(id);
} {
.();
}
}
});
});
Step 4: Add Secrets to GitHub
gh secret set DOCUMENSO_STAGING_API_KEY --body "api_stg_xxxxxxxxxxxx"
gh secret set DOCUMENSO_WEBHOOK_SECRET --body "whsec_xxxxxxxxxxxx"
gh secret list
Step 5: Package.json Scripts
{
"scripts": {
"test": "vitest run tests/unit/",
"test:integration": "vitest run tests/integration/ --timeout 60000",
"test:cleanup": "tsx scripts/cleanup-test-docs.ts",
"test:all": "npm test && npm run test:integration"
}
}
Step 6: Pre-commit Hook (Optional)
npm test -- --run
This runs unit tests (with mocks) before every commit, catching issues early without needing API access.
CI Strategy Summary
| Test Type | Runs On | API Key Needed? | Speed |
|---|
| Unit tests (mocks) | Every push + PR | No | Fast (~5s) |
| Integration tests | Push to main/develop only | Yes (staging) | Slow (~30s) |
| Cleanup | After integration tests | Yes (staging) | Fast |
Error Handling
| CI Issue | Cause | Solution |
|---|
| Integration test timeout | Slow API | Increase vitest timeout to 60s |
| Rate limit in CI | Too many test runs | Use mocks for PRs, live API only on main |
| Secret not found | Missing GitHub secret | Add via gh secret set |
| Stale test data | Cleanup didn't run | Run npm run test:cleanup manually |
Resources
Next Steps
For deployment strategies, see documenso-deploy-integration.
