@devix-tecnologia/directus-test-sdk

Utilitários para testes de integração contra um Directus real rodando em Docker. Não sobe nenhum container sozinho — cada pacote de teste traz seu próprio docker-compose.yml e usa este SDK para orquestrá-lo, autenticar, criar dados de teste e provar onde cada requisição realmente passou.

Absorvido do repositório directus-test (ADR 001, decisão 7). O exemplo vivo de uso é o pacote irmão @devix-tecnologia/directus-test-redis-cache.

Instalação

pnpm add -D @devix-tecnologia/directus-test-sdk

Publicado no npm público; não precisa de configuração de registry.

O que exporta

• docker — subirAmbienteDirectus(): sobe um docker-compose.yml qualquer via testcontainers, espera o healthcheck do Directus e devolve a URL base + função de teardown. chaveContainer(servico) devolve a chave <serviço>-1 que o testcontainers usa para localizar cada container do compose.
• http — directusFetch(): wrapper fino sobre fetch nativo que expõe status, headers (ex.: X-Directus-Cache-Status) e corpo da resposta — útil quando o @directus/sdk oficial esconde os headers.
• bootstrap — autenticarAdmin() e criarUsuarioComPermissao(): login administrativo e criação de role + policy (com filtro de permissão de linha) + usuário, para testes que precisam de múltiplos usuários com acessos diferentes.
• schema — verificarSchemaAplicado(): confere via GET /collections se as coleções esperadas existem na instância. É o teste de imagem dos projetos: a imagem de Directus sobe com schema apply --yes no entrypoint (ADR 001, decisão 10) e este helper prova que o snapshot foi aplicado.
• e2e — loginAdminApp(): helper Playwright para testes E2E que precisam fazer login na interface administrativa do Directus. playwright é peerDependency opcional — só é necessário para quem usa este helper.
• observability — visibilidade sobre onde uma requisição realmente "passou":
  • obterEstatisticasRedis() / diferencaDeChamadas(): lê INFO commandstats do Redis e permite tirar um snapshot antes/depois para saber quantos GET/SET/etc. um teste efetivamente disparou.
  • obterLogsDesde() / contarQueriesSql() / contarQueriesParaTabela(): lê os logs do container do Directus desde um instante (via docker logs --since) e conta quantas linhas correspondem a queries SQL — o Directus loga cada query com sua duração quando LOG_LEVEL=trace. Prefira contarQueriesParaTabela() para asserções — o Directus roda uma query de accountability/permissões em toda requisição autenticada, mesmo em cache HIT, e contarQueriesSql() genérico conta essa query de sistema junto com as de dados.
  • aguardarLogs(): dá um respiro (500ms por padrão) para o log assíncrono do container assentar antes de ler com obterLogsDesde(). Chame antes de marcar o timestamp de início de uma janela que você espera ter zero queries — senão uma query da chamada anterior, ainda não escrita no log, pode ser contada na janela seguinte (corrida que já causou teste flaky na prática).

Uso típico

import {
  autenticarAdmin,
  subirAmbienteDirectus,
  verificarSchemaAplicado,
} from '@devix-tecnologia/directus-test-sdk';

const ambiente = await subirAmbienteDirectus({
  composeFilePath: import.meta.dirname,
  env: { CACHE_TTL: '30s' },
});

const token = await autenticarAdmin(ambiente.baseUrl, {
  email: '[email protected]',
  senha: 'admin-password',
});

const schema = await verificarSchemaAplicado(ambiente.baseUrl, token, {
  colecoesEsperadas: ['lockers', 'compartimentos', 'reservas'],
});
if (!schema.ok) {
  throw new Error(`Schema incompleto, faltando: ${schema.faltando.join(', ')}`);
}

await ambiente.parar();

Teste de imagem de Directus de um projeto

it('imagem sobe com o snapshot aplicado', async () => {
  const { ok, faltando } = await verificarSchemaAplicado(baseUrl, token, {
    colecoesEsperadas: ['lockers', 'compartimentos'],
  });
  expect(faltando).toEqual([]);
  expect(ok).toBe(true);
});

O token precisa enxergar as coleções (admin, ou policy com leitura em directus_collections); coleções invisíveis ao token contam como faltando. Status diferente de 200 (token inválido, instância fora) lança erro em vez de devolver ok: false, para não mascarar falha de infraestrutura como schema faltando.

Engines de Docker não-Docker-Desktop (Colima, Rancher Desktop, OrbStack…)

subirAmbienteDirectus() detecta o DOCKER_HOST a partir do Docker context ativo (docker context inspect) e desabilita o container "Ryuk" de limpeza automática (que falha em alguns desses engines). O teardown é explícito via parar(), então desabilitar o Ryuk é seguro. Só é necessário ter docker e docker compose (v2) no PATH.

Scripts

pnpm build       # tsc → dist/
pnpm typecheck   # inclui os testes unitários
pnpm lint        # biome check .
pnpm test        # vitest --run (unitários, fetch mockado — sem Docker)