Pruebas

El SDK proporciona APIs programáticas que te permiten compilar, desplegar, instalar y desinstalar tu aplicación desde código de pruebas. Combinado con Vitest y los clientes de API tipados, puedes escribir pruebas de integración que verifiquen que tu aplicación funciona de extremo a extremo contra un servidor real de Twenty.

Uso de paquetes de npm

Puedes instalar y usar cualquier paquete de npm en tu aplicación. Tanto las funciones de lógica como los componentes de frontend se empaquetan con esbuild, que incorpora todas las dependencias en la salida — no se necesitan node_modules en tiempo de ejecución.

Instalar un paquete

yarn add axios

Luego impórtalo en tu código:

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

Lo mismo funciona para los componentes de frontend:

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

Cómo funciona el empaquetado

El paso de compilación usa esbuild para producir un solo archivo autónomo por función de lógica y por componente de frontend. Todos los paquetes importados se insertan en el bundle. Las funciones de lógica se ejecutan en un entorno Node.js. Los módulos integrados de Node (fs, path, crypto, http, etc.) están disponibles y no necesitan instalarse. Los componentes de frontend se ejecutan en un Web Worker. Los módulos integrados de Node no están disponibles — solo las APIs del navegador y paquetes de npm que funcionen en un entorno de navegador. Ambos entornos tienen twenty-client-sdk/core y twenty-client-sdk/metadata disponibles como módulos preproporcionados — estos no se incluyen en el bundle sino que se resuelven en tiempo de ejecución por el servidor.

Configuración

La aplicación generada ya incluye Vitest. Si lo configuras manualmente, instala las dependencias:

yarn add -D vitest vite-tsconfig-paths

Crea un vitest.config.ts en la raíz de tu aplicación:

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

Crea un archivo de configuración global que verifique que el servidor es accesible, escriba una configuración de prueba para el SDK (~/.twenty/config.test.json) y sincronice la aplicación antes de que se ejecuten las pruebas:

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

APIs programáticas del SDK

La subruta twenty-sdk/cli exporta funciones que puedes invocar directamente desde el código de pruebas:

Función	Descripción
`appBuild`	Compilar la aplicación y opcionalmente empaquetar un tarball
`appDeploy`	Subir un tarball al servidor
`appDevOnce`	Compila y sincroniza la aplicación una vez (igual que `yarn twenty apply`)
`appInstall`	Instalar la aplicación en el espacio de trabajo activo
`appUninstall`	Desinstalar la aplicación del espacio de trabajo activo

Cada función devuelve un objeto de resultado con success: boolean y data o error.

Escribir una prueba de integración

Aquí tienes un ejemplo completo que compila, despliega e instala la aplicación, y luego verifica que aparezca en el espacio de trabajo:

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

Ejecutar pruebas

Asegúrate de que tu servidor local de Twenty esté en ejecución y luego:

yarn test

O en modo watch durante el desarrollo:

yarn test:watch

Comprobación de tipos

También puedes ejecutar la comprobación de tipos en tu aplicación sin ejecutar pruebas:

yarn twenty dev:typecheck

Esto ejecuta tsc --noEmit contra el tsconfig.json de tu aplicación e informa cualquier error de tipo. Las aplicaciones generadas también incluyen un script yarn typecheck que cubre los archivos de prueba (tsconfig.spec.json).

CI con GitHub Actions

El generador crea un flujo de trabajo listo para usar en .github/workflows/ci.yml. En cada push a main y en cada pull request, inicia un servidor efímero de Twenty en el runner (mediante la acción twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test), luego ejecuta yarn lint, yarn typecheck, yarn test:unit y yarn test con TWENTY_API_URL / TWENTY_API_KEY apuntando a ese servidor. No se requieren secretos y puedes fijar la versión del servidor mediante la variable de entorno TWENTY_VERSION en la parte superior del flujo de trabajo. Consulta Publicación → CI/CD automatizado para ver una guía completa de los tres flujos de trabajo generados (ci.yml, la canalización de despliegue cd.yml y publish.yml para la publicación en npm).

Resumen

Aplicaciones

API

Autoalojamiento

Contribuir

Uso de paquetes de npm

Instalar un paquete

Cómo funciona el empaquetado

Configuración

APIs programáticas del SDK

Escribir una prueba de integración

Ejecutar pruebas

Comprobación de tipos

CI con GitHub Actions

​Uso de paquetes de npm

​Instalar un paquete

​Cómo funciona el empaquetado

​Configuración

​APIs programáticas del SDK

​Escribir una prueba de integración

​Ejecutar pruebas

​Comprobación de tipos

​CI con GitHub Actions

Uso de paquetes de npm

Instalar un paquete

Cómo funciona el empaquetado

Configuración

APIs programáticas del SDK

Escribir una prueba de integración

Ejecutar pruebas

Comprobación de tipos

CI con GitHub Actions