Test

Vitest kurulumu, gerçek bir Twenty sunucusunda entegrasyon testleri, tip denetimi ve GitHub Actions ile CI.

SDK, test kodundan uygulamanızı derlemenize, dağıtmanıza, yüklemenize ve kaldırmanıza olanak tanıyan programatik API’ler sağlar. Tiplenmiş API istemcileriyle birlikte Vitest kullanarak, uygulamanızın gerçek bir Twenty sunucusunda uçtan uca çalıştığını doğrulayan entegrasyon testleri yazabilirsiniz.

​

npm paketlerini kullanma

Uygulamanızda herhangi bir npm paketini yükleyip kullanabilirsiniz. Hem mantık işlevleri hem de ön uç bileşenleri, tüm bağımlılıkları çıktıya satır içi olarak ekleyen esbuild ile paketlenir — çalışma zamanında node_modules gerekmez.

​

Bir paketi yükleme

yarn add axios

Ardından kodunuza içe aktarın:

src/logic-functions/fetch-data.ts

import { defineLogicFunction } from 'twenty-sdk/define';
import axios from 'axios';

const handler = async (): Promise<any> => {
  const { data } = await axios.get('https://api.example.com/data');

  return { data };
};

export default defineLogicFunction({
  universalIdentifier: '...',
  name: 'fetch-data',
  description: 'Fetches data from an external API',
  timeoutSeconds: 10,
  handler,
});

Aynısı ön uç bileşenleri için de geçerlidir:

src/front-components/chart.tsx

import { defineFrontComponent } from 'twenty-sdk/define';
import { format } from 'date-fns';

const DateWidget = () => {
  return <p>Today is {format(new Date(), 'MMMM do, yyyy')}</p>;
};

export default defineFrontComponent({
  universalIdentifier: '...',
  name: 'date-widget',
  component: DateWidget,
});

​

Paketleme nasıl çalışır

Derleme adımı, her mantık işlevi ve her ön uç bileşeni için tek bir bağımsız dosya üretmek üzere esbuild kullanır. Tüm içe aktarılan paketler pakete satır içi eklenir.

Mantık işlevleri, Node.js ortamında çalışır. Node yerleşik modülleri (fs, path, crypto, http vb.) kullanılabilir ve kurulmaları gerekmez.

Ön uç bileşenleri, bir Web Worker içinde çalışır. Node’un yerleşik modülleri kullanılamaz — yalnızca tarayıcı ortamında çalışan tarayıcı API’leri ve npm paketleri kullanılabilir.

Her iki ortamda da twenty-client-sdk/core ve twenty-client-sdk/metadata önceden sağlanmış modüller olarak mevcuttur — bunlar paketlenmez, ancak çalışma zamanında sunucu tarafından çözülür.

​

Kurulum

İskelet aracıyla oluşturulan uygulama zaten Vitest’i içerir. Manuel kurulum yaparsanız, bağımlılıkları yükleyin:

yarn add -D vitest vite-tsconfig-paths

Uygulamanızın kök dizininde bir vitest.config.ts oluşturun:

vitest.config.ts

import tsconfigPaths from 'vite-tsconfig-paths';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  plugins: [
    tsconfigPaths({
      projects: ['tsconfig.spec.json'],
      ignoreConfigErrors: true,
    }),
  ],
  test: {
    testTimeout: 120_000,
    hookTimeout: 120_000,
    include: ['src/**/*.integration-test.ts'],
    setupFiles: ['src/__tests__/setup-test.ts'],
    env: {
      TWENTY_API_URL: 'http://localhost:2020',
      TWENTY_API_KEY: 'your-api-key',
    },
  },
});

Testler çalışmadan önce sunucuya erişilebildiğini doğrulayan bir kurulum dosyası oluşturun:

src/__tests__/setup-test.ts

import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import { beforeAll } from 'vitest';

const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
const TEST_CONFIG_DIR = path.join(os.tmpdir(), '.twenty-sdk-test');

beforeAll(async () => {
  // Verify the server is running
  const response = await fetch(`${TWENTY_API_URL}/healthz`);

  if (!response.ok) {
    throw new Error(
      `Twenty server is not reachable at ${TWENTY_API_URL}. ` +
        'Start the server before running integration tests.',
    );
  }

  // Write a temporary config for the SDK
  fs.mkdirSync(TEST_CONFIG_DIR, { recursive: true });

  fs.writeFileSync(
    path.join(TEST_CONFIG_DIR, 'config.json'),
    JSON.stringify({
      remotes: {
        local: {
          apiUrl: process.env.TWENTY_API_URL,
          apiKey: process.env.TWENTY_API_KEY,
        },
      },
      defaultRemote: 'local',
    }, null, 2),
  );
});

​

Programatik SDK API’leri

twenty-sdk/cli alt yolu, test kodundan doğrudan çağırabileceğiniz fonksiyonları dışa aktarır:

Fonksiyon	Açıklama
appBuild	Uygulamayı derleyin ve isteğe bağlı olarak bir tarball paketleyin
appDeploy	Bir tarball’ı sunucuya yükleyin
appInstall	Uygulamayı etkin çalışma alanına yükleyin
appUninstall	Uygulamayı etkin çalışma alanından kaldırın

Her fonksiyon, success: boolean ile birlikte data veya error içeren bir sonuç nesnesi döndürür.

​

Bir entegrasyon testi yazma

İşte uygulamayı derleyen, dağıtan ve yükleyen; ardından çalışma alanında göründüğünü doğrulayan tam bir örnek:

src/__tests__/app-install.integration-test.ts

import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/application-config';
import { appBuild, appDeploy, appInstall, appUninstall } from 'twenty-sdk/cli';
import { MetadataApiClient } from 'twenty-client-sdk/metadata';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';

const APP_PATH = process.cwd();

describe('App installation', () => {
  beforeAll(async () => {
    const buildResult = await appBuild({
      appPath: APP_PATH,
      tarball: true,
      onProgress: (message: string) => console.log(`[build] ${message}`),
    });

    if (!buildResult.success) {
      throw new Error(`Build failed: ${buildResult.error?.message}`);
    }

    const deployResult = await appDeploy({
      tarballPath: buildResult.data.tarballPath!,
      onProgress: (message: string) => console.log(`[deploy] ${message}`),
    });

    if (!deployResult.success) {
      throw new Error(`Deploy failed: ${deployResult.error?.message}`);
    }

    const installResult = await appInstall({ appPath: APP_PATH });

    if (!installResult.success) {
      throw new Error(`Install failed: ${installResult.error?.message}`);
    }
  });

  afterAll(async () => {
    await appUninstall({ appPath: APP_PATH });
  });

  it('should find the installed app in the workspace', async () => {
    const metadataClient = new MetadataApiClient();

    const result = await metadataClient.query({
      findManyApplications: {
        id: true,
        name: true,
        universalIdentifier: true,
      },
    });

    const installedApp = result.findManyApplications.find(
      (app: { universalIdentifier: string }) =>
        app.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
    );

    expect(installedApp).toBeDefined();
  });
});

​

Testleri çalıştırma

Yerel Twenty sunucunuzun çalıştığından emin olun, ardından:

yarn test

Veya geliştirme sırasında izleme modunda:

yarn test:watch

​

Tip denetimi

Ayrıca testleri çalıştırmadan uygulamanızda tip denetimi çalıştırabilirsiniz:

yarn twenty typecheck

Bu, tsc --noEmit komutunu çalıştırır ve tüm tip hatalarını raporlar.

​

GitHub Actions ile CI

İskelet oluşturucu, .github/workflows/ci.yml konumunda kullanıma hazır bir GitHub Actions iş akışı üretir. Entegrasyon testlerinizi main dalına yapılan her itmede ve çekme isteklerinde otomatik olarak çalıştırır.

İş akışı:

1. Kodunuzu çalışma alanına alır
2. twentyhq/twenty/.github/actions/spawn-twenty-docker-image eylemini kullanarak geçici bir Twenty sunucusu başlatır
3. yarn install --immutable ile bağımlılıkları kurar
4. Eylem çıktılarından enjekte edilen TWENTY_API_URL ve TWENTY_API_KEY ile yarn test çalıştırır

.github/workflows/ci.yml

name: CI

on:
  push:
    branches:
      - main
  pull_request: {}

env:
  TWENTY_VERSION: latest

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Spawn Twenty instance
        id: twenty
        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
        with:
          twenty-version: ${{ env.TWENTY_VERSION }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Run integration tests
        run: yarn test
        env:
          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
          TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}

Herhangi bir gizli değişken yapılandırmanız gerekmez — spawn-twenty-docker-image eylemi, koşucu içinde doğrudan geçici bir Twenty sunucusu başlatır ve bağlantı ayrıntılarını çıktı olarak verir. GITHUB_TOKEN gizli değişkeni GitHub tarafından otomatik olarak sağlanır.

latest yerine belirli bir Twenty sürümünü sabitlemek için iş akışının başındaki TWENTY_VERSION ortam değişkenini değiştirin.