Skip to main content

​
Dev/E2E Chart of Accounts Seeding

This system provides convenient ways to seed development and testing organizations with a standard set of chart of accounts, eliminating the need to manually create accounts during testing.

​
Overview

The seeding system provides the following standard dev chart of accounts:
Account NameNumberTypeDescriptionReconciled
Shopify Bank1200CreditShopify bank account❌
Paypal Bank1201CreditPayPal bank account❌
Paypal Working Capital1300CreditPayPal working capital❌
Shopify Deb.70000DebitShopify debtor account✅
Paypal Deb70001DebitPayPal debtor account✅
Shopify Fee4970DebitShopify fees❌
Paypal Fee4971DebitPayPal fees❌
Shopify Transit1360CreditShopify transit account❌
Paypal Transit1361CreditPayPal transit account❌
Währungsdifferenzen2150DebitCurrency differences❌
Rev DE8000DebitRevenue Germany❌
Rev AT8001DebitRevenue Austria❌
Rev CH8002DebitRevenue Switzerland❌
Rev FR8003DebitRevenue France❌
Rev UK8004DebitRevenue United Kingdom❌
Rev ES8005DebitRevenue Spain❌
other deb80000DebitOther debtor accounts❌
fallback99999DebitFallback account❌

​
Usage Methods

​
1. UI Button (Recommended for Manual Testing)

Navigate to /setup/chart-of-accounts in your dev environment and click the “🛠️ Seed Dev Accounts” button in the chart of accounts card header.
  • Only visible in development environment (NODE_ENV === “development”)
  • Uses the new warning button variant with proper CI colors for dev/testing purposes
  • Shows loading state during seeding
  • Displays success/error toasts
  • Automatically refreshes the page to show new accounts

​
2. CLI Script (Recommended for Automation)

Use the CLI script for automated testing or CI/CD pipelines: 
# Interactive mode (will prompt for required parameters)
pnpm seed:dev-chart

# Non-interactive mode with parameters
pnpm seed:dev-chart <organizationId> [actorId]

# Direct script usage
node scripts/seed-dev-chart-accounts.mjs [organizationId] [actorId]
Examples: Interactive Mode: 
# Will prompt for organization ID and optionally actor ID
pnpm seed:dev-chart

# Example interactive session:
🌱 Dev Chart of Accounts Seeding Tool

📋 Enter Organization ID (required): cloze123abc456def789
👤 Enter Actor ID (optional): [press enter to auto-detect]

🏢 Organization ID: cloze123abc456def789
👤 Actor ID: Auto-detect
✅ Proceed with seeding? This will create/update 18 chart accounts (y/N): y
Non-Interactive Mode: 
# Seed organization with ID (auto-finds actor)
pnpm seed:dev-chart cloze123abc456def789

# Seed with specific actor for audit trail
pnpm seed:dev-chart cloze123abc456def789 actor456def789
Environment Requirements:
  • DATABASE_URL must be set (uses organization’s database)

​
Features

  • Interactive Prompts: Asks for required parameters if not provided as arguments
  • Validation: Validates organization ID format
  • Confirmation: Shows summary and asks for confirmation before seeding
  • Non-Interactive Mode: Supports automation by providing arguments

​
3. Server Action (Programmatic Use)

For programmatic usage in tests or other server-side code: 
import { seedDevChartOfAccounts } from "@/app/lib/actions/chart_of_accounts/seed-dev-chart-of-accounts";

// Within an authenticated context (requires auth)
const result = await seedDevChartOfAccounts();
if (result.success) {
  console.log(`Seeded ${result.data.length} accounts`);
}

​
E2E Testing Integration

​
Playwright/E2E Tests

Add this to your test setup: 
// In your test setup or beforeEach
await page.goto("/setup/chart-of-accounts");
await page.click('button:has-text("🛠️ Seed Dev Accounts")');
await page.waitForSelector('.sonner-toast:has-text("Seeded")');

​
CI/CD Integration

Add to your CI pipeline after creating a test organization: 
- name: Seed dev chart of accounts
  run: |
    export DATABASE_URL=${{ secrets.TEST_DATABASE_URL }}
    # Non-interactive mode for CI
    pnpm seed:dev-chart ${{ env.TEST_ORG_ID }}
Note: In CI/CD environments, always provide parameters as arguments to avoid interactive prompts.

​
Features

  • Upsert Logic: Accounts are upserted, so running the seed multiple times is safe
  • Existing Account Handling: Won’t duplicate accounts, will update existing ones
  • Audit Trail: Uses actor ID for created/modified by tracking
  • Error Handling: Continues seeding even if individual accounts fail
  • Logging: Comprehensive logging for debugging
  • Single Source of Truth: Chart data defined once in CLI script, imported by UI seeding functions

​
Important Notes

⚠️ This is for development/testing only!
  • This seeding is NOT part of production organization setup
  • It’s separate from the standard organization seeding in create-organisation.ts
  • The UI button only appears in development environment and uses the proper warning variant styling
  • Accounts are created with standard test data, not production-ready configurations
  • Uses centralized getEnvironmentInfo() utility for consistent dev environment detection

​
Modifying Chart Data

To add, remove, or modify the standard dev chart of accounts:
  1. Edit only apps/webapp/scripts/seed-dev-chart-accounts.mjs
  2. Update the DEV_CHART_OF_ACCOUNTS array
  3. Both UI button and CLI will automatically use the updated data
The chart data is defined once in the CLI script and imported by the UI seeding functions, ensuring consistency and eliminating duplication.

​
File Structure

apps/webapp/
├── scripts/
│   └── seed-dev-chart-accounts.mjs        # 📋 CLI script + single source of truth for chart data
├── app/lib/actions/chart_of_accounts/
│   ├── chart-of-accounts-seed.ts          # Core seeding logic (imports from CLI script)
│   └── seed-dev-chart-of-accounts.ts      # Server action wrapper
├── app/lib/utils/
│   └── environment.ts                     # Centralized environment utilities (existing)
├── app/ui/cards/
│   └── chart-of-accounts-settings-card.tsx # UI with dev-only seed button
└── ../../internal-docs/dev-chart-seeding.mdx # This documentation

​
Troubleshooting

“Organization not found” error:
  • Verify the organization ID is correct
  • Ensure you have database access
“Actor not found” warning:
  • The script will continue without an actor ID
  • You can provide a specific actor ID as the second parameter
Database connection errors:
  • Verify DATABASE_URL environment variable is set
  • Check database connectivity
UI button not visible:
  • Ensure you’re in a development environment
  • Check that you’re authenticated and have access to the organization

​
Environment Utilities Usage

You can use the existing environment utilities in other components for consistent environment detection: 
import { getEnvironmentInfo } from "@/app/lib/utils/environment";

// Get full environment info
const { isDev, isStaging, isProduction, envType } = getEnvironmentInfo();

// Conditional logic for dev-only features
if (isDev) {
  // Dev-only code
}

// Or for dev AND staging features
if (isDev || isStaging) {
  // Dev and staging code
}