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.
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/sportsbooky/api/v1/support/config, con datos plausibles de un operador ficticio;POST /api/v1/auth/register, que devuelve unuserIdnuevo 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/sessionsyDELETE /api/v1/me/sessions/currenty/mock-session-2(perfil en memoria);- billetera:
GET /api/v1/wallet,/wallet/balancey/wallet/transactions(saldo inicial de R$ 1.500,00 y un extracto corto, filtrable porcategory); - depósito:
POST /api/v1/deposits/pix,GET /api/v1/deposits/:depositIdyGET /api/v1/deposits(el cobro quedapending); - retiro:
POST /api/v1/withdrawals,POST /api/v1/withdrawals/confirm-otp,GET /api/v1/withdrawals/:withdrawalId,GET /api/v1/withdrawalsyDELETE /api/v1/withdrawals/:withdrawalId— el retiro debita el saldo (y la cancelación lo devuelve), y un monto superior al saldo respondeINSUFFICIENT_BALANCE; - claves PIX:
POST/GET /api/v1/pix-keys,DELETE /api/v1/pix-keys/:keyIdyPUT /api/v1/pix-keys/:keyId/default(empieza con una clave CPF por defecto); - KYC:
GET /api/v1/kyc/status(nivelbasic,not_started) y la subida multipart dePOST /api/v1/kyc/documents(201; 400INVALID_ARGUMENTsin archivo o con un tipo inválido, como en el gateway), que pasa el estado apending; - notificaciones:
GET /api/v1/notifications(dos de ejemplo, una sin leer;page,limit,unread=true),PUT /api/v1/notifications/:notificationId/readyGET/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).
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:
- Ruta exacta: la de
options.routessi 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. - 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'. - 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
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:
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:
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):
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).
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(),
})| Control | Qué 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:
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.