Pular para o conteúdo principal

Status: Approved · v2 · SPEC-MOCKS-CONTRACTS-001

depends_on: SPEC-CONTRACTS-RESPONSE-001

used_by: IS-ZERO-00.2, IS-ZERO-00.5

Contratos de mocks e fixtures

Especificação detalhada do simulador de API usado antes e durante a integração real.

Arquitetura​

Objetivo​

@raizfc/mocks simula a API, não a tela. Ele implementa HttpClient, roteia requests para handlers e opera sobre um estado em memória inicializado por cenários tipados.

packages/mocks/src/
  index.ts
  client/
    mock-client.ts
    mock-router.ts
    mock-state.ts
    mock-delay.ts
    mock-errors.ts
  data/<domain>/
  handlers/<domain>.handlers.ts
  scenarios/
    default-scenario.ts
    empty-scenario.ts
    error-scenario.ts
    rich-scenario.ts

Fluxo obrigatório​

Screen → Hook → Service → HttpClient → MockClient → Handler → State/Fixture

Fixtures​

Fixtures são TypeScript tipadas, imutáveis e determinísticas. IDs seguem team_001, user_001, match_001; datas usam um clock de cenário. Mutações nunca alteram a fixture fonte: o cenário clona os dados para MockState.

Cenários​

  • default: volume realista para desenvolvimento.
  • empty: relações vazias sem apagar entidades essenciais.
  • error: falhas selecionáveis e permissions reduzidas.
  • rich: demonstração ampla, com conteúdos, partidas, rankings e gestão.

Estados adicionais como slow/offline são opções do client, não cópias completas de fixtures.

Mutabilidade​

O MVP deve implementar stateful behavior para follow/cheer, mutes/hides, notifications, invites, links, match/report/result, wallet/payment fake e create/update essenciais. Persistência entre reloads não é requisito inicial.

Privacidade​

Handlers públicos constroem DTOs públicos; não reutilizam objetos management e depois “removem alguns campos”. O teste deve falhar se chaves proibidas forem encontradas.

Latência e falhas​

  • Delay default configurável por cenário.
  • Timeout/offline são falhas de client.
  • Erros de domínio são retornados pelo handler com envelope.
  • Testes usam delay zero.

Reset e debug​

  • resetScenario() restaura seed.
  • setScenario(name) troca todo o estado.
  • setRouteError(route, code) força caso específico.
  • Não expor ferramentas de debug em production build.

Critérios de aceite​

  • Fixtures tipadas e determinísticas.
  • Handlers cobrem todos os endpoints P0/P1 do MVP.
  • Mutations alteram state.
  • Public/private boundaries testadas.
  • Services não sabem se client é mock ou real.