Docs/Guía Oficial de Integración

Documentación de Arquitectura e Integración de Qably

Aprende cómo conectar tus pipelines de CI/CD, ingerir telemetría de pruebas automatizadas y utilizar el motor de IA de Qably en tu equipo de ingeniería.

1. Arquitectura del Monorepo

Qably está construido sobre un monorepo pnpm y Turborepo, diseñado con una estricta separación de responsabilidades y tipado unificado:

apps/web: Panel de control web desarrollado en Next.js 16 (App Router), React 19, Better Auth, Zustand y Tailwind CSS v4.
apps/api: Backend de alto rendimiento construido con NestJS 11, Prisma ORM, PostgreSQL y BullMQ para procesamiento de tareas en segundo plano.
packages/types: Modelos de dominio y tipos de TypeScript compartidos (ProjectSummary, Run, AiCase, Suite).
apps/landing: Sitio de marketing estático ultrarrápido con Astro 7 e islas interactivas de React 19.

2. Autenticación & API Keys (`apps/api`)

Todas las comunicaciones desde runners de CI/CD hacia Qably se autentican mediante tokens de API por proyecto con prefijo qbly_live_*.

# Cabecera HTTP requerida en cada petición a la API

Authorization: Bearer qbly_live_8f2a1c4d9e6b4a2f

Puedes generar y revocar claves en cualquier momento desde la sección Configuración > API Keys de tu proyecto en la aplicación web.

3. Ingesta de Telemetría de Runs (`POST /runs/ingest`)

El endpoint POST /runs/ingest de apps/api procesa los resultados de las suites ejecutadas en tus pipelines en tiempo real:

POST /runs/ingest
Content-Type: application/json
Authorization: Bearer qbly_live_8f2a1c4d9e6b4a2f

{
  "projectId": "proj-1",
  "suiteId": "suite-e2e-checkout",
  "source": "github_actions",
  "commitSha": "7a8b9c0d12e",
  "branch": "main",
  "cases": [
    {
      "name": "User completes checkout with credit card",
      "status": "pass",
      "durationMs": 1420
    },
    {
      "name": "User enters expired promotional coupon",
      "status": "fail",
      "durationMs": 850,
      "error": "CouponExpiredError: Code SUMMER26 has expired"
    }
  ]
}

4. Integración con GitHub Actions

Copia el siguiente workflow en .github/workflows/qably-quality-gate.yml para conectar tus pruebas automáticamente:

name: Qably Quality Gate
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
      - name: Install dependencies
        run: pnpm install
      - name: Run Tests with Qably Telemetry
        run: pnpm test --reporter=@qably/reporter
        env:
          QABLY_TOKEN: ${{ secrets.QABLY_TOKEN }}
          QABLY_PROJECT_ID: ${{ vars.QABLY_PROJECT_ID }}

5. Generación de Pruebas con IA (`ai-prompt` & `review-inbox`)

El módulo de IA de Qably no inventa casos arbitrarios. Analiza el AST de los diffs de código en pull requests o historias de usuario y propone casos determinísticos:

1. Extracción Inteligente: Detección de condiciones de borde, manejo de errores y escenarios concurrentes en los cambios propuestos.

2. Bandeja de Revisión (Review Inbox): Cada prueba generada permanece en estado in_review hasta que un ingeniero la acepta o edita, evitando alucinaciones en el repositorio oficial.

3. Sincronización a Suite Oficial: Una vez aprobada, se convierte en un OfficialTestCase con trazabilidad histórica completa.

6. Entorno de Desarrollo Local (`apps/api`)

Para ejecutar el backend de apps/api en tu máquina local:

# 1. Iniciar base de datos PostgreSQL
docker compose up -d

# 2. Ejecutar migraciones de Prisma
pnpm --filter @qably/api prisma migrate dev

# 3. Iniciar servidor NestJS en modo desarrollo
pnpm --filter @qably/api run start:dev