Testes e mocks
@getenginex/sdk/testing traz createMockFetch: um fetch de mock para passar em createEnginexClient({ fetch }), sem nenhuma dependência nova (nada de MSW). As respostas padrão batem com os schemas reais do SDK — inclusive com validation: 'strict' — então dá para escrever testes (ou uma demo, ou um Storybook) sem subir o 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'Em Node (Vitest, Jest, scripts) não existe location: sem baseUrl absoluto e tenantHost, o primeiro request rejeita com CONFIGURATION_ERROR — mesmo com o mock, que responde a qualquer origem. Os valores podem ser fictícios (https://gateway.test, casino.test); no browser (demo, Storybook) eles são opcionais. Veja Tenant e domínios.
Rotas padrão
Sem nenhuma opção, createMockFetch() responde a:
GET /api/v1/config,/api/v1/config/branding,/api/v1/config/products,/api/v1/config/sportsbooke/api/v1/support/config, com dados plausíveis de um operador fictício;POST /api/v1/auth/register, que devolve umuserIdnovo sem autenticar;POST /api/v1/auth/login, que autentica e grava tokens de sessão simulados;POST /api/v1/auth/refresh, que sempre devolve tokens novos — o refresh automático da sessão (proativo ou depois de um 401) funciona de ponta a ponta contra o mock, sem precisar simular isso na mão;POST /api/v1/auth/logout, que sempre responde com sucesso;GET/PUT /api/v1/me,GET /api/v1/me/sessionseDELETE /api/v1/me/sessions/currente/mock-session-2(perfil em memória);- carteira:
GET /api/v1/wallet,/wallet/balancee/wallet/transactions(saldo inicial de R$ 1.500,00 e um extrato curto, filtrável porcategory); - depósito:
POST /api/v1/deposits/pix,GET /api/v1/deposits/:depositIdeGET /api/v1/deposits(a cobrança ficapending); - saque:
POST /api/v1/withdrawals,POST /api/v1/withdrawals/confirm-otp,GET /api/v1/withdrawals/:withdrawalId,GET /api/v1/withdrawalseDELETE /api/v1/withdrawals/:withdrawalId— o saque debita o saldo (e o cancelamento devolve), e um valor acima do saldo respondeINSUFFICIENT_BALANCE; - chaves PIX:
POST/GET /api/v1/pix-keys,DELETE /api/v1/pix-keys/:keyIdePUT /api/v1/pix-keys/:keyId/default(começa com uma chave CPF padrão); - KYC:
GET /api/v1/kyc/status(nívelbasic,not_started) e o upload multipart dePOST /api/v1/kyc/documents(201; 400INVALID_ARGUMENTsem arquivo ou com tipo inválido, como no gateway), que passa a situação parapending; - notificações:
GET /api/v1/notifications(duas de exemplo, uma não lida;page,limit,unread=true),PUT /api/v1/notifications/:notificationId/readeGET/PUT /api/v1/notifications/preferences.
O estado é por mock (cada createMockFetch() começa do zero). Como no gateway, depósito e saque exigem Idempotency-Key (o SDK sempre manda) e a mesma chave repete a primeira resposta; os limites mínimo/máximo vêm de GET /config. Diferente do gateway de hoje, GET /withdrawals lista os saques feitos no mock.
Um depósito criado fica pending até o "banco" confirmar o PIX. Para simular o pagamento, guarde o fetch do mock e chame markDepositPaid: o depósito vira completed e o saldo sobe o valor dele (uma única 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'Esses são também os formatos das chaves de options.routes: método + caminho completo, com o prefixo /api/v1 (ex.: 'POST /api/v1/auth/login', nunca 'POST /auth/login'). Um segmento :nome casa com qualquer valor, que o handler recebe em req.params?.nome (o mock sempre preenche params; no tipo ele é opcional).
Qual handler responde, em ordem:
- Rota exata: a de
options.routesse houver, senão a padrão. Uma rota exata padrão vence mesmo uma rota com parâmetro sua — ex.:'GET /api/v1/wallet/:x'não intercepta/api/v1/wallet/balance; para sobrescrever uma rota padrão exata, use a mesma chave exata. - Rota com parâmetro: as de
options.routesprimeiro, depois as padrão — ex.:'GET /api/v1/deposits/:id'sua vence a padrão'GET /api/v1/deposits/:depositId'. - Nenhuma:
404 NOT_FOUND.
Uma rota chamada sem handler (padrão ou de options.routes) devolve 404 NOT_FOUND, em vez de lançar — o erro chega ao chamador como um EnginexError normal.
Cenário 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'Saque com OTP
Por padrão o mock simula um operador sem OTP no saque (withdrawals.request já devolve { status: 'created' }). Com withdrawalOtp: true, GET /config passa a anunciar o fluxo withdraw_money, request devolve { status: 'otp_required' } e confirmOtp com qualquer código não vazio envia o saque:
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 no gateway, o pedido fica pendente por 10 minutos (também depois do confirmOtp): repeti-lo com a mesma Idempotency-Key e o mesmo corpo devolve o mesmo pedido, e qualquer outro request é recusado com FAILED_PRECONDITION (422) another withdrawal request is pending.
Sobrescrevendo rotas e simulando erros
options.routes sobrescreve um handler padrão ou adiciona uma rota nova, indexado por "MÉTODO /api/v1/caminho". Use os helpers ok e fail para montar as respostas no mesmo formato do 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?) monta { success: true, data, meta? } (status 200, ou o informado — ex.: 201 para imitar rotas de criação); fail(status, code, message?, details?) monta { success: false, error: { code, message, details? } } com o status HTTP informado — o mesmo formato que errorFromHttp espera para virar um EnginexError (veja Erros).
Identidade simulada
options.user troca o userId/operatorId usados nas claims do access token simulado e nas respostas de auth (padrão: mock-user-1 / mock-operator-1):
createMockFetch({ user: { userId: 'u-42', operatorId: 'op-casino' } })Realtime
createMockRealtime() é o equivalente para o realtime: um WebSocket falso para createEnginexClient({ webSocket }), sem dependências. Responde ack a cada subscribe e pong a cada ping, e abre a conexão de forma assíncrona (uma microtarefa: aguarde 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(),
})| Controle | O que faz |
|---|---|
connections() | Conexões abertas até agora (a url inclui o token, para asserts). |
emit(topic, type, payload) | Mensagem simples (modo multi-tenant); o payload vai como no fio, em snake_case. |
emitSequenced(topic, kind, seq, payload?) | snapshot, delta ou heartbeat com o envelope do modo sequenciado (gap gera snapshot_request). |
drop(code?) | Derruba a conexão (padrão 1006): o cliente reconecta e dispara onResync. |
rejectPrivate(topic?) | Responde error unauthorized aos subscribe privados (os já enviados e os novos): uma tentativa extra e, depois, closed. |
acceptPrivate(topic?) | Desfaz o rejectPrivate: os próximos subscribe voltam a receber ack (o cliente bloqueado reconecta com um token novo). |
sent() | Frames enviados pelo cliente ({ type, topic? }). |
Para o rejectPrivate() sem argumento, é privado o tópico que termina no usuário (sub) do token da conexão (balance:<sub>, predictions:orders:<sub>...), sem lista de prefixos. Se um tópico público do seu teste puder ter o id igual ao do usuário, passe o seu critério: createMockRealtime({ isPrivate: (topic) => topic.startsWith('balance:') }).
Pacotes de produto e adapters
Os pacotes de produto trazem as rotas mock na própria entrada /testing: withIgamingRoutes (@getenginex/sdk-igaming/testing) e withPredictionsRoutes (@getenginex/sdk-predictions/testing) recebem as opções do createMockFetch e somam suas rotas às do core. Eles se combinam, e as rotas que você passa vencem as padrão:
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)O que cada mock de produto responde (catálogo, bônus, ordens, portfólio...) está na página do produto: iGaming e Predictions. Para testar componentes, os adapters usam esses mesmos mocks com a biblioteca de testes de cada framework: React, Next.js e Vue.
Exemplo completo
O projeto examples/vanilla-vite do repositório monta um cliente com createMockFetch, carrega a config e faz um login mockado, sem gateway nenhum. Como rodá-lo, e os exemplos de Next.js e Vue, em Exemplos.