Test

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 npm paketleri kullanılabilir. Korumalı alanın kısmi bir DOM uyguladığını unutmayın; bu nedenle bir paket hatasız derlenip çalışma zamanında yine de başarısız olabilir. Bkz. Geçerli kısıtlamalar. 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';

const TWENTY_API_URL = process.env.TWENTY_API_URL ?? 'http://localhost:2020';
const TWENTY_API_KEY = process.env.TWENTY_API_KEY ?? '<the pre-seeded local dev key>';

// Make env vars available to globalSetup (test.env only applies to workers)
process.env.TWENTY_API_URL = TWENTY_API_URL;
process.env.TWENTY_API_KEY = TWENTY_API_KEY;

export default defineConfig({
  plugins: [
    tsconfigPaths({
      projects: ['tsconfig.spec.json'],
      ignoreConfigErrors: true,
    }),
  ],
  test: {
    testTimeout: 120_000,
    hookTimeout: 120_000,
    fileParallelism: false,
    include: ['src/**/*.integration-test.ts'],
    globalSetup: ['src/__tests__/global-setup.ts'],
    env: {
      TWENTY_API_URL,
      TWENTY_API_KEY,
    },
  },
});

Sunucunun erişilebilir olduğunu doğrulayan, SDK için bir test yapılandırması (~/.twenty/config.test.json) yazan ve testler çalışmadan önce uygulamayı eşitleyen genel bir kurulum dosyası oluşturun:

src/__tests__/global-setup.ts

import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';

import { appDevOnce, appUninstall } from 'twenty-sdk/cli';

const APP_PATH = process.cwd();
const CONFIG_DIR = path.join(os.homedir(), '.twenty');

export async function setup() {
  const apiUrl = process.env.TWENTY_API_URL!;
  const apiKey = process.env.TWENTY_API_KEY!;

  // Verify the server is running
  const response = await fetch(`${apiUrl}/healthz`);
  if (!response.ok) {
    throw new Error(`Twenty server is not reachable at ${apiUrl}.`);
  }

  // Write the SDK's test config (the CLI reads config.test.json when NODE_ENV=test)
  fs.mkdirSync(CONFIG_DIR, { recursive: true });
  fs.writeFileSync(
    path.join(CONFIG_DIR, 'config.test.json'),
    JSON.stringify({
      remotes: { local: { apiUrl, apiKey } },
      defaultRemote: 'local',
    }, null, 2),
  );

  // Start from a clean slate, then sync the app
  await appUninstall({ appPath: APP_PATH }).catch(() => {});

  const result = await appDevOnce({ appPath: APP_PATH });
  if (!result.success) {
    throw new Error(`Dev sync failed: ${result.error?.message}`);
  }
}

export async function teardown() {
  await appUninstall({ appPath: APP_PATH });
}

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
`appDevOnce`	Uygulamayı bir kez oluşturun ve eşitleyin (`yarn twenty apply` ile aynıdır)
`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 dev:typecheck

Bu, uygulamanızın tsconfig.json dosyasına göre tsc --noEmit komutunu çalıştırır ve tüm tip hatalarını raporlar. İskelet olarak oluşturulan uygulamalar ayrıca test dosyalarını da kapsayan (tsconfig.spec.json) bir yarn typecheck betiği ile birlikte gelir.

GitHub Actions ile CI

İskelet oluşturucu, .github/workflows/ci.yml konumunda kullanıma hazır bir iş akışı üretir. main dalına yapılan her itmede ve her çekme isteğinde, çalıştırıcı içinde geçici bir Twenty sunucusu başlatır (twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test eylemi aracılığıyla) ve ardından yarn lint, yarn typecheck, yarn test:unit ve yarn test komutlarını, TWENTY_API_URL / TWENTY_API_KEY bu sunucuyu işaret edecek şekilde çalıştırır. Herhangi bir gizli bilgi gerekmez ve iş akışının en üstündeki TWENTY_VERSION ortam değişkeni aracılığıyla sunucu sürümünü sabitleyebilirsiniz. Üç iskelet iş akışının (ci.yml, cd.yml dağıtım hattı ve npm yayınlama için publish.yml) eksiksiz adım adım anlatımı için Yayınlama → Otomatik CI/CD bölümüne bakın.

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

npm paketlerini kullanma

Bir paketi yükleme

Paketleme nasıl çalışır

Kurulum

Programatik SDK API’leri

Bir entegrasyon testi yazma

Testleri çalıştırma

Tip denetimi

GitHub Actions ile CI

​npm paketlerini kullanma

​Bir paketi yükleme

​Paketleme nasıl çalışır

​Kurulum

​Programatik SDK API’leri

​Bir entegrasyon testi yazma

​Testleri çalıştırma

​Tip denetimi

​GitHub Actions ile CI

npm paketlerini kullanma

Bir paketi yükleme

Paketleme nasıl çalışır

Kurulum

Programatik SDK API’leri

Bir entegrasyon testi yazma

Testleri çalıştırma

Tip denetimi

GitHub Actions ile CI