Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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.

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'

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/sportsbook e /api/v1/support/config, com dados plausíveis de um operador fictício;
  • POST /api/v1/auth/register, que devolve um userId novo 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/sessions e DELETE /api/v1/me/sessions/current e /mock-session-2 (perfil em memória);
  • carteira: GET /api/v1/wallet, /wallet/balance e /wallet/transactions (saldo inicial de R$ 1.500,00 e um extrato curto, filtrável por category);
  • depósito: POST /api/v1/deposits/pix, GET /api/v1/deposits/:depositId e GET /api/v1/deposits (a cobrança fica pending);
  • saque: POST /api/v1/withdrawals, POST /api/v1/withdrawals/confirm-otp, GET /api/v1/withdrawals/:withdrawalId, GET /api/v1/withdrawals e DELETE /api/v1/withdrawals/:withdrawalId — o saque debita o saldo (e o cancelamento devolve), e um valor acima do saldo responde INSUFFICIENT_BALANCE;
  • chaves PIX: POST/GET /api/v1/pix-keys, DELETE /api/v1/pix-keys/:keyId e PUT /api/v1/pix-keys/:keyId/default (começa com uma chave CPF padrão);
  • KYC: GET /api/v1/kyc/status (nível basic, not_started) e o upload multipart de POST /api/v1/kyc/documents (201; 400 INVALID_ARGUMENT sem arquivo ou com tipo inválido, como no gateway), que passa a situação para pending;
  • notificações: GET /api/v1/notifications (duas de exemplo, uma não lida; page, limit, unread=true), PUT /api/v1/notifications/:notificationId/read e GET/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).

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'

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:

  1. Rota exata: a de options.routes se 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.
  2. Rota com parâmetro: as de options.routes primeiro, depois as padrão — ex.: 'GET /api/v1/deposits/:id' sua vence a padrão 'GET /api/v1/deposits/:depositId'.
  3. 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 ​

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'

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:

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 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:

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?) 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):

ts
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).

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(),
})
ControleO 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:

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)

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.