@data_engine_labs/data_engine_sdk

SDK JS/TS para capturar metricas de tests y enviarlas al portal Data Engine. En v1 soporta Playwright como reporter drop-in, mas una API manual para casos avanzados.

Instalacion

El paquete se publica en el npm publico (registry.npmjs.org). No requiere token ni .npmrc.

pnpm add -D @data_engine_labs/data_engine_sdk
# o
npm i -D @data_engine_labs/data_engine_sdk

Uso con Playwright (recomendado)

Anade el reporter a tu playwright.config.ts:

import { defineConfig } from "@playwright/test";

export default defineConfig({
    reporter: [
        ["list"],
        ["@data_engine_labs/data_engine_sdk/playwright"],
    ],
});

Configura via variables de entorno (tipico en CI):

export DATA_ENGINE_API_KEY="dek_...."
export DATA_ENGINE_BASE_URL="https://portal.example.com"
export DATA_ENGINE_ENVIRONMENT="staging"

El reporter detecta el contexto del pipeline (branch, commit, URL del run, quien lo dispar) automaticamente en GitHub Actions, Azure Pipelines y GitLab CI.

Variables de entorno

| Variable | Requerida | Uso | | --- | --- | --- | | DATA_ENGINE_API_KEY | si | API key dek_... del proyecto | | DATA_ENGINE_BASE_URL | si | URL base del portal | | DATA_ENGINE_ENVIRONMENT | si | Nombre del ambiente (staging, prod, ...) | | DATA_ENGINE_BRANCH | no | Override manual de branch | | DATA_ENGINE_COMMIT_SHA | no | Override manual de commit | | DATA_ENGINE_TRIGGERED_BY | no | Override manual de trigger | | DATA_ENGINE_PIPELINE_RUN_URL | no | Override manual de URL | | DATA_ENGINE_STRICT | no | "true" para fallar el job si el submit falla | | DATA_ENGINE_DISABLE | no | "true" para desactivar el reporter |

Precedencia por campo: argumento constructor > env var > detector CI > undefined.

Uso manual (API programatica)

Para frameworks no soportados nativamente, o para reportar corridas ad-hoc:

import { createClient, detectPipeline } from "@data_engine_labs/data_engine_sdk";
import { randomUUID } from "node:crypto";

const client = createClient({
    apiKey: process.env.DATA_ENGINE_API_KEY!,
    baseUrl: process.env.DATA_ENGINE_BASE_URL!,
});

const pipeline = detectPipeline();

await client.submitRun({
    runId: randomUUID(),
    framework: "PLAYWRIGHT",
    environment: "staging",
    branch: pipeline.branch ?? "main",
    commitSha: pipeline.commitSha,
    triggeredBy: pipeline.triggeredBy,
    pipelineRunUrl: pipeline.pipelineRunUrl,
    startedAt: new Date(Date.now() - 60_000).toISOString(),
    finishedAt: new Date().toISOString(),
    results: [
        { name: "sample test", suite: "example.spec.ts", status: "PASSED", durationMs: 100, retries: 0, tags: [] },
    ],
});

Semantica de FLAKY

Un test que fallo y despues paso en un retry se reporta con status: "FLAKY" a nivel individual, pero cuenta como PASSED en el rollup de la corrida (overallStatus, passed). Esto permite trazabilidad de tests inestables sin marcar toda la corrida como fallida.

Fail-open por defecto

Si el submit al portal falla (red, 500, timeout), la SDK loguea un console.warn pero no rompe el CI job. Setea DATA_ENGINE_STRICT=true para invertir este comportamiento.

Idempotencia

Cada corrida se envia con un runId unico (UUID). Si el mismo runId se reenvia (por ejemplo por un reintento de CI), el endpoint responde 200 con el run original en lugar de crear un duplicado. Los reintentos automaticos son seguros.