Testing

Panoramica

Usa la CLI autonoma con --json per compilare, pubblicare, installare e disinstallare la tua app dal codice di test. Installala globalmente con npm install -g twenty. In combinazione con Vitest e i client API tipizzati, puoi scrivere test di integrazione che verificano che la tua app funzioni end-to-end contro un server Twenty reale.

Uso dei pacchetti npm

Puoi installare e usare qualsiasi pacchetto npm nella tua app. Sia le funzioni logiche sia i componenti front-end vengono impacchettati con esbuild, che incorpora le loro dipendenze nell’output — non sono necessari i node_modules a runtime.

Installazione di un pacchetto

yarn add axios

Quindi importalo nel tuo codice:

src/logic-functions/fetch-data.ts

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

const handler = async () => {
  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,
});

Lo stesso vale per i componenti front-end:

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,
});

Come funziona il bundling

La fase di build usa esbuild per produrre un singolo file autonomo per ogni funzione logica e per ogni componente front-end. I pacchetti importati vengono incorporati nel bundle, ad eccezione di quelli elencati di seguito. Le funzioni logiche vengono eseguite in un ambiente Node.js. I moduli integrati di Node (fs, path, crypto, http, ecc.) sono disponibili e non necessitano di essere installati. I componenti front-end vengono eseguiti in un Web Worker. I moduli integrati di Node non sono disponibili — solo i pacchetti npm che funzionano in un ambiente browser. Nota che la sandbox implementa un DOM parziale, quindi un pacchetto può compilarsi correttamente e comunque fallire in fase di esecuzione; vedi Limitazioni attuali. Entrambi gli ambienti hanno twenty-client-sdk/core e twenty-client-sdk/metadata disponibili come moduli preforniti — questi non vengono inclusi nel bundle ma vengono risolti a runtime dal server. I componenti front-end possono anche condividere dipendenze tramite un bundle di dipendenze condivise. I pacchetti elencati nel campo frontComponentSharedDependencies del package.json dell’app vengono compilati una sola volta in un file separato e caricati da lì a runtime invece di essere incorporati in ogni componente, quindi un componente che importa solo pacchetti condivisi contiene quasi nessun codice di dipendenza proprio.

Impostazione

L’app generata tramite scaffolding include già Vitest. Se la configuri manualmente, installa le dipendenze:

yarn add -D vitest vite-tsconfig-paths

Crea un vitest.config.ts alla radice della tua app:

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,
    },
  },
});

Il modello generato include src/__tests__/run-twenty.ts, un helper per sottoprocessi che richiama la CLI globale e analizza il relativo risultato JSON. Imposta TWENTY_CLI su un percorso eseguibile assoluto per usare una build della CLI locale. Eredita TWENTY_API_URL e TWENTY_API_KEY; non è necessario alcun file di configurazione nella directory home. Usa questo helper per la configurazione e lo smantellamento:

src/__tests__/global-setup.ts

import { runTwenty } from './run-twenty';

export async function setup() {
  const result = await runTwenty(['app', 'apply', '--create']);
  if (!result.ok) throw new Error(result.error.message);
}

export async function teardown() {
  const result = await runTwenty(['app', 'uninstall', '--yes']);
  if (!result.ok) throw new Error(result.error.message);
}

Esegui test di integrazione su un workspace temporaneo: la configurazione installa l’app e lo smantellamento la disinstalla. Per la copertura dell’installazione dal registro, esegui app publish --private seguito da app install anziché app apply --create.

Scrivere un test di integrazione

Usa twenty-client-sdk per ispezionare dati e metadati dopo il completamento della configurazione della CLI:

import { MetadataApiClient } from 'twenty-client-sdk/metadata';
import { expect, it } from 'vitest';
import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';

it('installs the app', async () => {
  const result = await new MetadataApiClient().query({
    findOneApplication: {
      __args: { universalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER },
      id: true,
    },
  });
  expect(result.findOneApplication.id).toBeTruthy();
});

Per un manifest, leggi data.manifest da twenty app build --json. Per i test delle funzioni distribuite, usa la mutation executeOneLogicFunction del client dei metadati con un token utente. Risolvi la funzione nell’ID dell’applicazione installata prima di richiamarla.

Esecuzione dei test

Assicurati che il tuo server Twenty locale sia in esecuzione, quindi:

yarn test

Oppure in modalità watch durante lo sviluppo:

yarn test:watch

Controllo dei tipi

Puoi anche eseguire il controllo dei tipi sulla tua app senza eseguire i test:

twenty app typecheck

Questo controlla il file tsconfig.json della tua app con il compilatore TypeScript installato, senza generare file, e segnala eventuali errori di tipo. Le app generate dallo scaffolder includono anche uno script yarn typecheck che copre anche i file di test (tsconfig.spec.json).

CI con GitHub Actions

Lo strumento di scaffolding genera un workflow pronto all’uso in .github/workflows/ci.yml. A ogni push su main e a ogni pull request, avvia un server Twenty effimero nel runner (tramite l’azione twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test), quindi esegue yarn lint, yarn typecheck, yarn test:unit e yarn test con TWENTY_API_URL / TWENTY_API_KEY che puntano a quel server. Non sono necessari segreti e puoi fissare la versione del server tramite la variabile di ambiente TWENTY_VERSION all’inizio del workflow. Vedi Pubblicazione → CI/CD automatizzato per una spiegazione completa dei tre workflow generati dallo scaffolder (ci.yml, la pipeline di deploy cd.yml e publish.yml per la pubblicazione su npm).

Sviluppatori

App

API

Auto-ospitazione

Contribuire

Libreria UI

Panoramica

Uso dei pacchetti npm

Installazione di un pacchetto

Come funziona il bundling

Impostazione

Scrivere un test di integrazione

Esecuzione dei test

Controllo dei tipi

CI con GitHub Actions

​Panoramica

​Uso dei pacchetti npm

​Installazione di un pacchetto

​Come funziona il bundling

​Impostazione

​Scrivere un test di integrazione

​Esecuzione dei test

​Controllo dei tipi

​CI con GitHub Actions

Panoramica

Uso dei pacchetti npm

Installazione di un pacchetto

Come funziona il bundling

Impostazione

Scrivere un test di integrazione

Esecuzione dei test

Controllo dei tipi

CI con GitHub Actions