Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

Pruebas y mocks ​

@getenginex/sdk/testing trae createMockFetch: un fetch de mock para pasar a createEnginexClient({ fetch }), sin ninguna dependencia nueva (nada de MSW). Las respuestas por defecto coinciden con los schemas reales del SDK — incluso con validation: 'strict' — así que puedes escribir pruebas (o una demo, o un Storybook) sin levantar el gateway.

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch } from '@getenginex/sdk/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test', // in Node (Vitest, Jest): absolute baseUrl + tenantHost
  tenantHost: 'casino.test', // in the browser, both are optional
  fetch: createMockFetch(),
})

const config = await enginex.config.get()
const result = await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
// result.status === 'authenticated'

En Node (Vitest, Jest, scripts) no existe location: sin baseUrl absoluta y tenantHost, el primer request rechaza con CONFIGURATION_ERROR — incluso con el mock, que responde a cualquier origen. Los valores pueden ser ficticios (https://gateway.test, casino.test); en el browser (demo, Storybook) son opcionales. Consulta Tenant y dominios.

Rutas por defecto ​

Sin ninguna opción, createMockFetch() responde a:

  • GET /api/v1/config, /api/v1/config/branding, /api/v1/config/products, /api/v1/config/sportsbook y /api/v1/support/config, con datos plausibles de un operador ficticio;
  • POST /api/v1/auth/register, que devuelve un userId nuevo sin autenticar;
  • POST /api/v1/auth/login, que autentica y guarda tokens de sesión simulados;
  • POST /api/v1/auth/refresh, que siempre devuelve tokens nuevos — el refresh automático de la sesión (proactivo o después de un 401) funciona de punta a punta contra el mock, sin necesidad de simularlo a mano;
  • POST /api/v1/auth/logout, que siempre responde con éxito;
  • GET/PUT /api/v1/me, GET /api/v1/me/sessions y DELETE /api/v1/me/sessions/current y /mock-session-2 (perfil en memoria);
  • billetera: GET /api/v1/wallet, /wallet/balance y /wallet/transactions (saldo inicial de R$ 1.500,00 y un extracto corto, filtrable por category);
  • depósito: POST /api/v1/deposits/pix, GET /api/v1/deposits/:depositId y GET /api/v1/deposits (el cobro queda pending);
  • retiro: POST /api/v1/withdrawals, POST /api/v1/withdrawals/confirm-otp, GET /api/v1/withdrawals/:withdrawalId, GET /api/v1/withdrawals y DELETE /api/v1/withdrawals/:withdrawalId — el retiro debita el saldo (y la cancelación lo devuelve), y un monto superior al saldo responde INSUFFICIENT_BALANCE;
  • claves PIX: POST/GET /api/v1/pix-keys, DELETE /api/v1/pix-keys/:keyId y PUT /api/v1/pix-keys/:keyId/default (empieza con una clave CPF por defecto);
  • KYC: GET /api/v1/kyc/status (nivel basic, not_started) y la subida multipart de POST /api/v1/kyc/documents (201; 400 INVALID_ARGUMENT sin archivo o con un tipo inválido, como en el gateway), que pasa el estado a pending;
  • notificaciones: GET /api/v1/notifications (dos de ejemplo, una sin leer; page, limit, unread=true), PUT /api/v1/notifications/:notificationId/read y GET/PUT /api/v1/notifications/preferences.

El estado es por mock (cada createMockFetch() empieza desde cero). Como en el gateway, depósito y retiro exigen Idempotency-Key (el SDK siempre la envía) y la misma clave repite la primera respuesta; los límites mínimo/máximo vienen de GET /config. A diferencia del gateway actual, GET /withdrawals lista los retiros hechos en el mock.

Un depósito creado queda pending hasta que el "banco" confirme el PIX. Para simular el pago, guarda el fetch del mock y llama a markDepositPaid: el depósito pasa a completed y el saldo sube el valor del depósito (una sola vez).

ts
import { createMockFetch, markDepositPaid } from '@getenginex/sdk/testing'

const mockFetch = createMockFetch()
// ... createEnginexClient({ ..., fetch: mockFetch }), login and createPix
markDepositPaid(mockFetch, pix.id)
await enginex.deposits.get({ depositId: pix.id }) // status: 'completed'

Estos son también los formatos de las claves de options.routes: método + ruta completa, con el prefijo /api/v1 (p. ej., 'POST /api/v1/auth/login', nunca 'POST /auth/login'). Un segmento :nombre coincide con cualquier valor, que el handler recibe en req.params?.nombre (el mock siempre rellena params; en el tipo es opcional).

Qué handler responde, en orden:

  1. Ruta exacta: la de options.routes si existe, si no la por defecto. Una ruta exacta por defecto gana incluso a una ruta con parámetro tuya — p. ej., 'GET /api/v1/wallet/:x' no intercepta /api/v1/wallet/balance; para sobrescribir una ruta exacta por defecto, usa la misma clave exacta.
  2. Ruta con parámetro: primero las de options.routes, luego las por defecto — p. ej., tu 'GET /api/v1/deposits/:id' gana a la por defecto 'GET /api/v1/deposits/:depositId'.
  3. Ninguna: 404 NOT_FOUND.

Una ruta llamada sin handler (por defecto o de options.routes) devuelve 404 NOT_FOUND, en lugar de lanzar — el error llega a quien llama como un EnginexError normal.

Escenario de 2FA ​

ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test',
  tenantHost: 'casino.test',
  fetch: createMockFetch({ twoFactorRequired: true }),
})

let result = await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
// result.status === '2fa_required'

result = await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123', twoFactorCode: '123456' })
// result.status === 'authenticated'

Retiro con OTP ​

Por defecto el mock simula un operador sin OTP en el retiro (withdrawals.request ya devuelve { status: 'created' }). Con withdrawalOtp: true, GET /config pasa a anunciar el flujo withdraw_money, request devuelve { status: 'otp_required' } y confirmOtp con cualquier código no vacío envía el retiro:

ts
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test',
  tenantHost: 'casino.test',
  fetch: createMockFetch({ withdrawalOtp: true }),
})

await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })
const result = await enginex.withdrawals.request({ amount: 5_000, pixKeyType: 'cpf' })
// result.status === 'otp_required'
const withdrawal = await enginex.withdrawals.confirmOtp({ otp: '123456' })
// withdrawal.status === 'pending'

Como en el gateway, la solicitud queda pendiente durante 10 minutos (también después de confirmOtp): repetirla con la misma Idempotency-Key y el mismo cuerpo devuelve la misma solicitud, y cualquier otro request se rechaza con FAILED_PRECONDITION (422) another withdrawal request is pending.

Sobrescribir rutas y simular errores ​

options.routes sobrescribe un handler por defecto o agrega una ruta nueva, indexado por "MÉTODO /api/v1/ruta". Usa los helpers ok y fail para armar las respuestas en el mismo formato del gateway:

ts
import { createMockFetch, fail, ok } from '@getenginex/sdk/testing'
import { isEnginexError } from '@getenginex/sdk'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test',
  tenantHost: 'casino.test',
  fetch: createMockFetch({
    routes: {
      'POST /api/v1/auth/login': () => fail(401, 'INVALID_CREDENTIALS', 'wrong password'),
      'GET /api/v1/config/products': () => ok({ products: [] }),
      'GET /api/v1/deposits/:depositId': (req) => fail(404, 'NOT_FOUND', `no ${req.params?.depositId}`),
    },
  }),
})

try {
  await enginex.auth.login({ email: 'ana@exemplo.com', password: 'wrong' })
} catch (e) {
  if (isEnginexError(e, 'INVALID_CREDENTIALS')) {
    // ...
  }
}

ok(data, meta?, status?) arma { success: true, data, meta? } (status 200, o el indicado — p. ej., 201 para imitar rutas de creación); fail(status, code, message?, details?) arma { success: false, error: { code, message, details? } } con el status HTTP indicado — el mismo formato que errorFromHttp espera para convertirse en un EnginexError (consulta Errores).

Identidad simulada ​

options.user cambia el userId/operatorId usados en los claims del access token simulado y en las respuestas de auth (por defecto: mock-user-1 / mock-operator-1):

ts
createMockFetch({ user: { userId: 'u-42', operatorId: 'op-casino' } })

Realtime ​

createMockRealtime() es el equivalente para el realtime: un WebSocket falso para createEnginexClient({ webSocket }), sin dependencias. Responde ack a cada subscribe y pong a cada ping, y abre la conexión de forma asíncrona (una microtarea: espera antes de emitir).

ts
import { createEnginexClient } from '@getenginex/sdk'
import { coreTopics, createRealtime } from '@getenginex/sdk/realtime'
import { createMockFetch, createMockRealtime } from '@getenginex/sdk/testing'

const mock = createMockRealtime()
const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test',
  tenantHost: 'casino.test',
  fetch: createMockFetch(),
  webSocket: mock.webSocket,
})
await enginex.auth.login({ email: 'ana@exemplo.com', password: 'Senha@123' })

createRealtime(enginex).subscribe(coreTopics.balance(), (update) => console.log(update.available))
await Promise.resolve() // the connection opens
mock.emit('balance:mock-user-1', 'balance_update', {
  available: 5_000,
  change: 5_000,
  change_type: 'credit',
  updated_at: new Date().toISOString(),
})
ControlQué hace
connections()Conexiones abiertas hasta ahora (la url incluye el token, para asserts).
emit(topic, type, payload)Mensaje simple (modo multi-tenant); el payload va como en la red, en snake_case.
emitSequenced(topic, kind, seq, payload?)snapshot, delta o heartbeat con el envelope del modo secuenciado (un salto genera snapshot_request).
drop(code?)Tumba la conexión (por defecto 1006): el cliente reconecta y dispara onResync.
rejectPrivate(topic?)Responde error unauthorized a los subscribe privados (los ya enviados y los nuevos): un intento extra y, después, closed.
acceptPrivate(topic?)Deshace rejectPrivate: los próximos subscribe vuelven a recibir ack (el cliente bloqueado reconecta con un token nuevo).
sent()Frames enviados por el cliente ({ type, topic? }).

Para rejectPrivate() sin argumento, es privado el tópico que termina en el usuario (sub) del token de la conexión (balance:<sub>, predictions:orders:<sub>...), sin lista de prefijos. Si un tópico público de tu prueba pudiera tener un id igual al del usuario, pasa tu propio criterio: createMockRealtime({ isPrivate: (topic) => topic.startsWith('balance:') }).

Paquetes de producto y adapters ​

Los paquetes de producto incluyen sus rutas mock en su propia entrada /testing: withIgamingRoutes (@getenginex/sdk-igaming/testing) y withPredictionsRoutes (@getenginex/sdk-predictions/testing) reciben las opciones de createMockFetch y suman sus rutas a las del core. Se pueden combinar, y las rutas que pasas ganan sobre las predeterminadas:

ts
import { createEnginexClient } from '@getenginex/sdk'
import { createMockFetch, fail } from '@getenginex/sdk/testing'
import { createIgaming } from '@getenginex/sdk-igaming'
import { withIgamingRoutes } from '@getenginex/sdk-igaming/testing'
import { createPredictions } from '@getenginex/sdk-predictions'
import { withPredictionsRoutes } from '@getenginex/sdk-predictions/testing'

const enginex = createEnginexClient({
  baseUrl: 'https://gateway.test',
  tenantHost: 'casino.test',
  // core + iGaming + Predictions routes; your `routes` still win over all of them
  fetch: createMockFetch(
    withIgamingRoutes(
      withPredictionsRoutes({
        routes: { 'GET /api/v1/games/:gameId': () => fail(404, 'GAME_NOT_FOUND') },
      }),
    ),
  ),
})
const igaming = createIgaming(enginex)
const predictions = createPredictions(enginex)

Lo que responde cada mock de producto (catálogo, bonos, órdenes, portafolio...) está en la página del producto: iGaming y Predictions. Para probar componentes, los adapters usan estos mismos mocks con la biblioteca de pruebas de cada framework: React, Next.js y Vue.

Ejemplo completo ​

El proyecto examples/vanilla-vite del repositorio arma un cliente con createMockFetch, carga la config y hace un inicio de sesión mockeado, sin ningún gateway. Cómo ejecutarlo, y los ejemplos de Next.js y Vue, en Ejemplos.